Skip to main content

How to Search MLflow Runs in Python with search_runs

· 6 min read
Jagdish Kumawat
Founder @ Dewiride

mlflow.search_runs() is the Python way to look through an experiment's runs: one call returns them as a pandas DataFrame, one row per run, with a column for every metric, parameter and tag. You can filter, sort and limit the result on the server. This guide searches three small runs, reads the columns MLflow returns, and narrows them to the best runs, with real output from MLflow 3.18.0.

Syntax​

Syntax
runs = mlflow.search_runs(
experiment_names=["<experiment name>"],
filter_string="<filter>",
order_by=["<column> ASC|DESC"],
max_results=<number>,
output_format="pandas",
)
ArgumentWhat it means
experiment_namesThe experiments to search, by name. experiment_ids does the same by ID; use one or the other, not both. With neither, MLflow searches the active experiment
filter_stringWhich runs to keep, such as "metrics.r2 > 0.75". Empty by default: all runs
order_byA list of columns to sort by, each with an optional ASC or DESC. "The default ordering is to sort by start_time DESC", newest first
max_resultsThe most runs to return. "Default is 100,000"
output_format"pandas", the default, for a DataFrame, or "list" for a list of Run objects

run_view_type and search_all_experiments are covered in How to Include Deleted Runs in an MLflow Search in Python and the function's reference.

Prerequisites​

Step 1: Create Three Runs​

The example is three forests with 50, 100 and 200 trees, each with the R² it scored. Create forest_runs.py:

forest_runs.py
import mlflow

mlflow.set_tracking_uri("http://127.0.0.1:8080")
mlflow.set_experiment("python-search-demo")

for trees, r2 in [(50, 0.71), (100, 0.76), (200, 0.78)]:
with mlflow.start_run(run_name=f"{trees}-trees"):
mlflow.log_param("n_estimators", trees)
mlflow.log_metric("r2", r2)
Terminal
uv run python forest_runs.py

It prints a View run link for each of the three runs.

Step 2: Search the Experiment​

Create search_runs.py. It searches the experiment twice: once for everything, once for the runs with an R² above 0.75, best first:

The search_runs.py script in a macOS-style code window: it calls mlflow.search_runs with experiment_names python-search-demo and prints the result's type, shape and columns and three of its columns, then searches again with filter_string metrics.r2 > 0.75 and order_by metrics.r2 DESC and prints the run names and R² values.

search_runs.py
import mlflow

mlflow.set_tracking_uri("http://127.0.0.1:8080")

runs = mlflow.search_runs(experiment_names=["python-search-demo"])
print(type(runs).__name__, runs.shape)
print(list(runs.columns))
print(runs[["tags.mlflow.runName", "params.n_estimators", "metrics.r2"]])

good = mlflow.search_runs(
experiment_names=["python-search-demo"],
filter_string="metrics.r2 > 0.75",
order_by=["metrics.r2 DESC"],
)
print(good[["tags.mlflow.runName", "metrics.r2"]])
Terminal
uv run python search_runs.py
Output
DataFrame (3, 12)
['run_id', 'experiment_id', 'status', 'artifact_uri', 'start_time', 'end_time', 'metrics.r2', 'params.n_estimators', 'tags.mlflow.source.type', 'tags.mlflow.runName', 'tags.mlflow.user', 'tags.mlflow.source.name']
tags.mlflow.runName params.n_estimators metrics.r2
0 200-trees 200 0.78
1 100-trees 100 0.76
2 50-trees 50 0.71
tags.mlflow.runName metrics.r2
0 200-trees 0.78
1 100-trees 0.76

A terminal running uv run python search_runs.py: DataFrame (3, 12), the list of twelve column names, a table of the three runs newest first with their n_estimators and r2, and a second table with only 200-trees and 100-trees.

Step 3: Read the Result​

  • One row per run, three here, and 12 columns.
  • The run's own fields come first: run_id, experiment_id, status, artifact_uri, start_time and end_time.
  • Everything the run logged follows, with a prefix: metrics.r2, params.n_estimators, and the tags, including the ones MLflow sets itself, such as tags.mlflow.runName, the run's name.
  • Newest first: 200-trees was logged last, so it's row 0.
  • Parameters are text: params.n_estimators holds '200', not 200. Metrics are numbers.

The second search kept the two runs with an R² above 0.75 and ordered them by R², highest first. Filtering and ordering happen on the tracking server, so only those runs are sent back. How to Write a Search Filter for MLflow Runs lists every kind of filter.

Step 4: Get Run Objects Instead​

With output_format="list", the same search returns a list of Run objects, the type mlflow.get_run() returns. Create run_objects.py:

run_objects.py
import mlflow

mlflow.set_tracking_uri("http://127.0.0.1:8080")

runs = mlflow.search_runs(experiment_names=["python-search-demo"], output_format="list")
print(runs[0].info.run_name, runs[0].data.params, runs[0].data.metrics)
Terminal
uv run python run_objects.py
Output
200-trees {'n_estimators': '200'} {'r2': 0.78}

run.info holds the run's own fields and run.data what it logged. A list is handier when you want one run's values; a DataFrame when you want a table.

Common Mistakes​

MistakeWhat happensDo this instead
Passing both experiment_ids and experiment_namesMlflowException: Only experiment_ids or experiment_names can be used, but not bothPick one
Indexing the DataFrame like a list, runs[0]KeyError: 0, because [0] looks for a column called 0Use runs.iloc[0] for the first row, or output_format="list"
Leaving out the experiment, without mlflow.set_experiment()MLflow searches the active experiment, Default, and finds nothing hereName the experiment

Troubleshooting​

SymptomLikely causeFix
KeyError: 'metrics.r2'None of the returned runs logged that metric, so the column doesn't existCheck the name, or use runs.columns to see what's there
An empty DataFrameThe experiment name is wrong, or no run matches the filterSearch without filter_string to see whether the experiment has runs
TypeError: Invalid comparison between dtype=str and intA parameter column, which holds text, was compared with a numberConvert it first: runs["params.n_estimators"].astype(int) > 100

FAQ​

How many runs does it return?​

Up to 100,000 by default; max_results sets a smaller limit, and max_results=2 here returned the two newest runs.

Can I search several experiments at once?​

Yes: list them all in experiment_names. search_all_experiments=True searches every experiment.

What's the difference from MlflowClient().search_runs()?​

MlflowClient().search_runs() takes experiment IDs, returns Run objects one page at a time, and returns 1,000 runs per call by default. mlflow.search_runs() collects the pages for you and can return a DataFrame.

Conclusion​

mlflow.search_runs(experiment_names=[...]) returned the experiment's runs as a DataFrame, newest first, with metrics., params. and tags. columns. filter_string, order_by and max_results narrowed and sorted them on the server, and output_format="list" returned Run objects instead.

Additional Resources​