Skip to main content

Register a model in Unity Catalog

Register your models in Unity Catalog, so that you govern them like your data: with centralized access control, auditing, lineage, and discovery across workspaces. MLflow registers each model as <catalog>.<schema>.<model>, and each registration creates a new model version. Assign an alias, such as Challenger, to a version so that downstream jobs load it by name instead of by version number.

Choose how to register your model:

Scenario

Option

Training and registration of a new model on your data

Train and register a model

Registration of a model that you trained and saved elsewhere

Register a saved model from a volume

Registration of a pretrained Hugging Face model

Register a Hugging Face model

Scenario

Option

Training and registration of a new model on your data

Train and register a model

Registration of a model that you trained and saved elsewhere

Register a saved model from a volume

Registration of a pretrained Hugging Face model

Register a Hugging Face model

Requirements​

You need the following before you register a model:

  • A workspace that is enabled for Unity Catalog.
  • The USE CATALOG and USE SCHEMA privileges on the catalog and schema where you register the model, and the CREATE MODEL privilege on the schema.
  • Compute with MLflow, scikit-learn, PyTorch, and Hugging Face transformers installed:
tip

The ML base environment in environment version 5 runs Python 3.12.3, and it includes MLflow 3.8.1, scikit-learn 1.6.1, PyTorch, and transformers 4.57.1. The PyTorch build in that environment is a CPU build (2.9.0+cpu), so the packages on this page don't need %pip install on serverless compute. See ML base environment.

Train and register a model​

The following MLflow 3 example trains a scikit-learn random forest classifier on the Iris dataset inside an MLflow run, and registers the model in Unity Catalog. Replace <catalog> and <schema> with a catalog and schema where you have the privileges in Requirements. Because the code passes registered_model_name to log_model(), MLflow registers the model as a new version, and infers the model signature from the input example and its predicted output:

Python
import mlflow
from sklearn import datasets
from sklearn.ensemble import RandomForestClassifier

mlflow.set_registry_uri("databricks-uc")

catalog = "<catalog>"
schema = "<schema>"

with mlflow.start_run():
# Train a scikit-learn model on the Iris dataset
X, y = datasets.load_iris(return_X_y=True, as_frame=True)
clf = RandomForestClassifier(max_depth=7)
clf.fit(X, y)

# Log the model, and register it in Unity Catalog
mlflow.sklearn.log_model(
sk_model=clf,
name="model",
input_example=X.iloc[[0]],
registered_model_name=f"{catalog}.{schema}.iris_model",
)

To learn how MLflow 3 tracks a training run and the model that it produces, import and run the MLflow 3 traditional machine learning example notebook. See MLflow 3 traditional ML workflow. For deep learning, see MLflow 3 deep learning workflow.

To register the model that you train, pass registered_model_name="<catalog>.<schema>.<model>" when you log the model, as in the examples on this page, or use MLflow autologging. See Train and register Unity Catalog-compatible models.

Register a saved model from a volume​

If you trained a model in another environment, upload the saved model file and a small sample input file to a Unity Catalog volume, and then register the model from the volume. The following example registers a pickled scikit-learn model, infers the model signature from the sample input, and assigns the Challenger alias to the new version:

Python
import mlflow
import pickle
import pandas as pd
from mlflow.models import infer_signature

mlflow.set_registry_uri("databricks-uc")

catalog = "<catalog>"
schema = "<schema>"

# The saved model and the sample input in a volume
model_path = f"/Volumes/{catalog}/{schema}/model_weights/logistic_model.pkl"
sample_path = f"/Volumes/{catalog}/{schema}/model_weights/sample_input.csv"

# Load the saved model object
with open(model_path, "rb") as f:
loaded_model = pickle.load(f)

# Load the sample input, and infer the model signature
sample_input = pd.read_csv(sample_path, index_col=0)
signature = infer_signature(sample_input, loaded_model.predict(sample_input).tolist())

# Log the model, and register it in Unity Catalog
with mlflow.start_run():
model_info = mlflow.sklearn.log_model(
loaded_model,
name="model",
signature=signature,
input_example=sample_input,
registered_model_name=f"{catalog}.{schema}.logistic_classifier",
)

# Assign an alias, so that downstream jobs can load this version by name
client = mlflow.tracking.MlflowClient()
client.set_registered_model_alias(
f"{catalog}.{schema}.logistic_classifier",
"Challenger",
model_info.registered_model_version,
)

print(f"Model registered: {model_info.model_uri}")

The same pattern works for other frameworks that save a complete model object. For example, replace pickle.load with torch.load(path, weights_only=False) or keras.models.load_model, and replace mlflow.sklearn with mlflow.pytorch or mlflow.keras. Loading with weights_only=False can run arbitrary code when unpickling, so load only files you trust.

A weights-only checkpoint, such as a PyTorch state_dict, doesn't contain the model object. To register one, instantiate the original model class in code, call load_state_dict(), and then log and register the result.

Register a Hugging Face model​

To register a pretrained Hugging Face model, wrap it in a transformers pipeline, and log it with the MLflow transformers flavor. The pipeline includes the tokenizer and configuration, so you don't log them separately.

Python
import mlflow
from transformers import pipeline
from mlflow.models import infer_signature

mlflow.set_registry_uri("databricks-uc")

catalog = "<catalog>"
schema = "<schema>"
model_name = "sentiment_classifier"
hf_model_id = "distilbert-base-uncased-finetuned-sst-2-english"

# Download the model and tokenizer from Hugging Face
classifier = pipeline("text-classification", model=hf_model_id)

# Run a sample prediction to infer the model signature
sample_input = ["Databricks helps teams engineer data pipelines."]
sample_output = classifier(sample_input)
signature = infer_signature(sample_input, sample_output)

# Log the model, and register it in Unity Catalog
with mlflow.start_run(run_name="huggingface_import"):
model_info = mlflow.transformers.log_model(
transformers_model=classifier,
name="model",
task="text-classification",
signature=signature,
input_example=sample_input,
registered_model_name=f"{catalog}.{schema}.{model_name}",
)

client = mlflow.tracking.MlflowClient()
client.set_registered_model_alias(
f"{catalog}.{schema}.{model_name}",
"Challenger",
model_info.registered_model_version,
)

print(f"Model registered: {model_info.model_uri}")

To register a different model, replace hf_model_id with the Hugging Face model ID, and set task to the model's task, such as "summarization" or "token-classification".

Verify the registered model​

Confirm that the model and its new version appear in the catalog and schema that you registered it to:

  1. In your workspace, click Data icon. Catalog, and open the catalog and schema where you registered the model. The model appears under Models.
  2. Click the model. The model details page lists its versions. Confirm that the new version appears.
  3. If you used the saved model or Hugging Face example, confirm that the new version has the Challenger alias.

Troubleshooting​

Use these entries if registration fails or a package is missing.

Registration fails with a permission error

Confirm that you have the USE CATALOG and USE SCHEMA privileges on the target catalog and schema, and the CREATE MODEL privilege on the schema. See Requirements.

An import fails for mlflow, sklearn, torch, or transformers

On classic compute, install the packages with %pip install mlflow scikit-learn torch transformers. On serverless compute, select the ML base environment. See Requirements.

Next steps​