●Change8

Migrating to MLflow v3.1.0

Version v3.1.0 introduces 4 breaking changes. This guide details how to update your code.

Released: 6/10/2025

4
Breaking Changes
7
Migration Steps
18
Affected Symbols

⚠️ Check Your Code

If you use any of these symbols, you need to read this guide:

mlflow.genai.promptsmlflow.evaluatemlflow.search_tracemlflow.genai.optimize_promptmlflow[databricks] (custom prompt judges)mlflow.tracking.MlflowSparkStudymlflow.spark_udfmlflow.logging.lock_uvmlflow.tracing.LogLoggedModelParamsmlflow.models.DSPyFlavormlflow.models.ResponsesAgent.predict_streammlflow.tracking.search_promptsmlflow.load_promptmlflow.gateway.GeminiSupportmlflow.tracing.PydanticAIAutologgingmlflow.tracing.smolagentsmlflow.artifacts.videomlflow.get_artifact_uri

Breaking Changes

●Issue #1

Prompt registry APIs have been moved under the `mlflow.genai.prompts` namespace; update imports and calls to use `mlflow.genai.prompts` instead of the previous location.

●Issue #2

When the tracking URI is set to Databricks and no registry URI is provided, the default registry URI now points to `databricks-uc`; explicitly set `registry_uri` if you relied on the previous default.

●Issue #3

`mlflow.evaluate` no longer logs the SHAP explainer; remove any code that expects SHAP artifacts from evaluation runs.

●Issue #4

`mlflow.search_trace()` now returns a DataFrame in V3 schema format; adjust column names and data handling to the new schema.

Migration Steps

  1. 1
    Update all imports of prompt registry APIs to use the new `mlflow.genai.prompts` namespace.
  2. 2
    If you relied on the implicit default registry URI when using Databricks, explicitly set `registry_uri` to the desired value.
  3. 3
    Remove any expectations of SHAP explainer artifacts from `mlflow.evaluate` outputs.
  4. 4
    Adapt code that consumes `mlflow.search_trace()` results to the new V3 DataFrame schema (e.g., column name changes).
  5. 5
    If you lock model dependencies, ensure `uv` is installed and use the new `uv`‑based locking option when calling `mlflow.log_model`.
  6. 6
    Review any custom prompt judge integrations to use the updated `mlflow[databricks]` extra.
  7. 7
    Verify that any custom tracing logic handles the new request/response preview fields.

Release Summary

MLflow 3 introduces a model‑centric GenAI architecture with new LoggedModel entity, prompt optimization, enhanced tracing, and many integrations, while also delivering several breaking changes that necessitate migration steps.

Need More Details?

View the full release notes and all changes for MLflow v3.1.0.

View Full Changelog