How to Test an MLflow Model in a Fresh Environment with mlflow.models.predict
A model that predicts on your computer can still fail elsewhere: a package it needs may be missing from its recorded requirements, because your own environment happened to have it. mlflow.models.predict catches that before deployment: it builds a brand-new virtual environment from the model's own requirements and predicts in it. This guide runs it with uv, with real output from MLflow 3.18.0.
Syntax
mlflow.models.predict(model_uri=model_uri, input_data=data, env_manager="uv")
| Part | What it means |
|---|---|
model_uri | The model to test, such as models:/<model ID> |
input_data | Input to predict, such as a few rows of a DataFrame. input_path= takes a file instead |
env_manager | How to build the environment: "uv", "virtualenv" (the default, which needs pyenv for the Python version), "conda", or "local" for your current environment |
MLflow's guide recommends it: "After logging your model with MLflow Tracking, it is highly recommended to validate the model locally before deploying it to production." The predictions are printed as JSON, or written to output_path=.
Prerequisites
- An MLflow tracking server at
http://127.0.0.1:8080. MLflow's tracking server guide shows how to start one. - uv installed:
uv --versionprints its version. MLflow calls it to build the environment.
Step 1: Log a Model to Test
This script logs a linear regression on scikit-learn's diabetes data into the experiment named on the command line, and prints its URI:
import sys
import mlflow
from sklearn.datasets import load_diabetes
from sklearn.linear_model import LinearRegression
mlflow.set_tracking_uri("http://127.0.0.1:8080")
mlflow.set_experiment(sys.argv[1])
X, y = load_diabetes(return_X_y=True, as_frame=True)
model = LinearRegression().fit(X, y)
with mlflow.start_run():
model_info = mlflow.sklearn.log_model(model, name="diabetes-model", input_example=X.head(3))
print("Model URI:", model_info.model_uri)
uv run python log_diabetes_model.py fresh-env-demo
Model URI: models:/m-9ec2eb5f465a44fdb231538eb5c406bb
Step 2: Predict in a Fresh Environment
fresh_env.py asks MLflow to predict three rows with the model, in a new environment built by uv:

import sys
import mlflow
from sklearn.datasets import load_diabetes
mlflow.set_tracking_uri("http://127.0.0.1:8080")
X, _ = load_diabetes(return_X_y=True, as_frame=True)
mlflow.models.predict(model_uri=sys.argv[1], input_data=X.head(3), env_manager="uv")
uv run python fresh_env.py models:/m-9ec2eb5f465a44fdb231538eb5c406bb
2026/11/21 14:13:31 INFO mlflow.models.flavor_backend_registry: Selected backend for flavor 'python_function'
2026/11/21 14:13:31 INFO mlflow.utils.virtualenv: Creating a new environment in /var/folders/…/T/tmpovei7qtx/envs/virtualenv_envs/mlflow-7ce281718f4d3c0008005aff97ca470a54f7fb7a with python version 3.15.2 using uv
Using CPython 3.15.2 interpreter at: /Library/Frameworks/Python.framework/Versions/3.15/bin/python3.15
Creating virtual environment at: /var/folders/…/T/tmpovei7qtx/envs/virtualenv_envs/mlflow-7ce281718f4d3c0008005aff97ca470a54f7fb7a
Activate with: source /var/folders/…/T/tmpovei7qtx/envs/virtualenv_envs/mlflow-7ce281718f4d3c0008005aff97ca470a54f7fb7a/bin/activate
2026/11/21 14:13:32 INFO mlflow.utils.virtualenv: Installing dependencies
Using Python 3.15.2 environment at: /private/var/folders/…/T/tmpovei7qtx/envs/virtualenv_envs/mlflow-7ce281718f4d3c0008005aff97ca470a54f7fb7a
Resolved 4 packages in 266ms
Installed 4 packages in 23ms
Using Python 3.15.2 environment at: /private/var/folders/…/T/tmpovei7qtx/envs/virtualenv_envs/mlflow-7ce281718f4d3c0008005aff97ca470a54f7fb7a
Resolved 88 packages in 212ms
Installed 87 packages in 2.08s
...
{"predictions": [206.11667724510568, 68.07103297306874, 176.882790351053]}

What happened, in order:
- A new environment, in a temporary folder (the
/var/folders/…path on a Mac), with the Python version the model was saved with, 3.15.2. - Two installs: first the build tools pip, setuptools and wheel with packaging, then the model's
requirements.txt: uv resolved 88 packages and installed 87,mlflow==3.18.0andscikit-learn==1.9.1among them. The...stands for the list of installed packages, one line each. - The prediction, run inside that environment, printed as JSON. The values match what the model gives in your own environment, so the recorded requirements are enough.
If a requirement were missing, the prediction would fail in the new environment, and MLflow would report the error from it.
Why the First Prediction Takes a Minute
The installs take a few seconds; the wait comes after. The new environment's packages have never been imported, and uv's documentation explains: "By default, uv does not compile Python (.py) files to bytecode", and "compilation is performed lazily the first time a module is imported." In a fresh environment with these packages, I measured the first import of MLflow, scikit-learn and pandas at 65 seconds, while it wrote 2,074 compiled files, and the second at 3.7 seconds. Each call builds a new environment in a new temporary folder, so each call waits again.
Common Mistakes
| Mistake | What happens | Do this instead |
|---|---|---|
env_manager="local" to save time | The model runs in your own environment, which hides a missing requirement | Use "uv", the point of the test |
Leaving out env_manager without pyenv installed | The default, "virtualenv", uses pyenv for the Python version | Pass env_manager="uv" |
Using validate_serving_input | Deprecated since MLflow 3.13.0 | Fixed: validate_serving_input is deprecated |
Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
| The first prediction takes a minute or more | Python compiles the new environment's packages on first import | Wait; it's a one-time cost per environment |
Incompatible input types for column ... Can not safely convert int64 to float64 | The input has whole numbers where the signature has decimals | Fixed: Can not safely convert int64 to float64 |
FAQ
Is the environment kept for the next call?
No: mlflow.models.predict builds it in a temporary folder, and the next call builds a new one.
Can I add a package to try a fix?
Yes: pip_requirements_override=["package==version"] installs extra or different versions in the test environment, without changing the model.
Conclusion
mlflow.models.predict(..., env_manager="uv") built a new Python 3.15.2 environment from the model's requirements and predicted three rows in it, with the same values as in my own environment: proof that the model carries everything it needs. Expect the first call to take a minute while Python compiles the new packages.
Additional Resources
- Validate Models before Deployment — MLflow's guide to
mlflow.models.predictand its environment managers. - mlflow.models —
predictand its parameters. - uv settings: compile-bytecode — why the first import is slow.
