MLflow 3 Migration Guide
This guide covers breaking changes and API updates when migrating from MLflow 2.x to MLflow 3.x.
Installation
Install MLflow 3 by running:
pip install "mlflow>=3.1"
Resources: Website | Documentation | Release Notes
Key Changes from MLflow 2.x
Model Logging API Changes
MLflow 2.x:
with mlflow.start_run():
mlflow.pyfunc.log_model(
artifact_path="model",
python_model=python_model,
)
MLflow 3:
# No longer requires starting a Run before logging models
mlflow.pyfunc.log_model(
name="model", # Use 'name' instead of 'artifact_path'
python_model=python_model,
)
Models are now first-class entities in MLflow 3. You can call log_model directly without the mlflow.start_run() context manager. Use the name parameter to enable searching for LoggedModels.
Model Artifacts Storage Location
MLflow 2.x:
experiments/
└── <experiment_id>/
└── <run_id>/
└── artifacts/
└── ... # model artifacts stored here
MLflow 3:
experiments/
└── <experiment_id>/
└── models/
└── <model_id>/
└── artifacts/
└── ... # model artifacts stored here
This change impacts the behavior of mlflow.client.MlflowClient.list_artifacts(). Model artifacts are no longer stored as run artifacts.
UI Changes
Artifacts Tab
In MLflow 3.x, the Artifacts tab in the run page no longer displays model artifacts. Model artifacts are now accessed through the Logged Models page, which provides a dedicated view for model-specific information and artifacts.
Breaking Changes
Removed Features
-
MLflow Recipes: Completely removed (#15250). Migrate to standard MLflow tracking and model registry functionality or consider MLflow Projects.
-
Model Flavors: The following flavors are no longer supported:
-
AI Gateway: The 'routes' and 'route_type' config keys removed (#15331). Use the new configuration format.
-
Deployment Server: The deployment server and
start-serverCLI command removed (#15327). Usemlflow models serveor containerized deployments.
Tracking API Changes
run_uuid Attribute Removed
Replace run_uuid with run_id:
# MLflow 2.x
run_info.run_uuid
# MLflow 3
run_info.run_id
Git Tags Removed
The following run tags have been removed (#15366):
mlflow.gitBranchNamemlflow.gitRepoURL
TensorFlow Autologging
The every_n_iter parameter removed from TensorFlow autologging (#15412). Implement custom logging callbacks for fine-tuned logging frequency.
Model API Changes
Removed Parameters
The following parameters have been removed from model logging/saving APIs:
example_no_conversion(#15322)code_path(#15368) - Use default code directory structurerequirements_filefrom PyTorch flavor (#15369) - Usepip_requirementsorextra_pip_requirementsinference_configfrom Transformers flavor (#15415) - Set configuration before logging
ModelInfo Changes
The signature_dict property removed from ModelInfo (#15367). Use the signature property instead.
Evaluation API Changes
Baseline Model Comparison
The baseline_model parameter removed (#15362). Use mlflow.validate_evaluation_results API to compare models:
# For classical ML models, use mlflow.models.evaluate
result_1 = mlflow.models.evaluate(model_1, data)
result_2 = mlflow.models.evaluate(model_2, data)
# Compare results
mlflow.validate_evaluation_results(result_1, result_2)
For GenAI evaluation, use mlflow.genai.evaluate with the new evaluation framework. See the GenAI Evaluation Migration Guide for details on migrating from the legacy LLM evaluation approach.
MetricThreshold Changes
Use greater_is_better instead of higher_is_better:
# MLflow 2.x
threshold = MetricThreshold(higher_is_better=True)
# MLflow 3
threshold = MetricThreshold(greater_is_better=True)
Custom Metrics
The custom_metrics parameter removed (#15361). Use the newer custom metrics approach in the evaluation API.
Explainer Logging
mlflow.evaluate no longer logs an explainer as a model by default. To enable:
mlflow.evaluate(
...,
evaluator_config={
"log_model_explainability": True,
"log_explainer": True,
},
)
Environment Variables
MLFLOW_GCS_DEFAULT_TIMEOUT removed (#15365). Configure timeouts using standard GCS client library approaches.
Migration FAQs
Can MLflow 3.x load resources created with MLflow 2.x?
Yes, MLflow 3.x can load resources (runs, models, traces, etc.) created with MLflow 2.x. However, the reverse is not true.
When testing MLflow 3.x, use a separate environment to avoid conflicts with MLflow 2.x.
load_model throws ResourceNotFound error. What's wrong?
In MLflow 3.x, model artifacts are stored in a different location. Use the model URI returned by log_model:
# ❌ Don't use mlflow.get_artifact_uri("model")
with mlflow.start_run() as run:
mlflow.sklearn.log_model(my_model, name="model")
mlflow.sklearn.load_model(mlflow.get_artifact_uri("model")) # Fails!
# ✅ Use the model URI from log_model
with mlflow.start_run() as run:
info = mlflow.sklearn.log_model(my_model, name="model")
# Recommended: use model_uri from result
mlflow.sklearn.load_model(info.model_uri)
# Alternative: use model_id
mlflow.sklearn.load_model(f"models:/{info.model_id}")
# Deprecated: use run_id (will be removed in future)
mlflow.sklearn.load_model(f"runs:/{run.info.run_id}/model")
How do I modify model requirements?
Use mlflow.models.update_model_requirements():
import mlflow
class DummyModel(mlflow.pyfunc.PythonModel):
def predict(self, context, model_input: list[str]) -> list[str]:
return model_input
model_info = mlflow.pyfunc.log_model(name="model", python_model=DummyModel())
mlflow.models.update_model_requirements(
model_uri=model_info.model_uri,
operation="add",
requirement_list=["scikit-learn"],
)
How do I stay on MLflow 2.x?
Pin MLflow to the latest 2.x version:
pip install 'mlflow<3'
Compatibility
We strongly recommend upgrading both client and server to MLflow 3.x for the best experience. A mismatch between client and server versions may lead to unexpected behavior.
Getting Help
For detailed guidance on migrating specific code, please consult: