Skip to main content

How to Include Deleted Runs in an MLflow Search in Python

· 4 min read
Jagdish Kumawat
Founder @ Dewiride

A deleted MLflow run isn't gone: it's in the deleted stage, and mlflow.search_runs() simply leaves it out by default. To find deleted runs, to restore one or to check what a cleanup removed, tell the search which runs to look at with run_view_type. This guide searches three runs, one of them deleted, in all three views, with real output from MLflow 3.18.0.

Syntax​

Syntax
from mlflow.entities import ViewType

mlflow.search_runs(experiment_names=["<experiment name>"], run_view_type=ViewType.<VIEW>)
ViewType.<VIEW>Which runs
ViewType.ACTIVE_ONLYRuns that aren't deleted. The default
ViewType.DELETED_ONLYOnly deleted runs
ViewType.ALLBoth

MlflowClient().search_runs() takes the same run_view_type argument.

Prerequisites​

Step 1: Create Three Runs and Delete One​

The example is three runs, alpha, beta and gamma, with beta deleted. Create greek_runs.py:

greek_runs.py
import mlflow

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

for name in ["alpha", "beta", "gamma"]:
with mlflow.start_run(run_name=name) as run:
mlflow.log_metric("score", 1.0)
if name == "beta":
mlflow.delete_run(run.info.run_id)
Terminal
uv run python greek_runs.py

It prints a View run link for each run.

Step 2: Search in All Three Views​

Create view_types.py, which runs the same search once per view:

The view_types.py script in a macOS-style code window: it imports ViewType from mlflow.entities, loops over ViewType.ACTIVE_ONLY, DELETED_ONLY and ALL, searches the deleted-search-demo experiment with each as run_view_type, and prints the view's name with the sorted run names.

view_types.py
import mlflow
from mlflow.entities import ViewType

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

for view in [ViewType.ACTIVE_ONLY, ViewType.DELETED_ONLY, ViewType.ALL]:
runs = mlflow.search_runs(experiment_names=["deleted-search-demo"], run_view_type=view)
print(f"{ViewType.to_string(view):12} {sorted(runs['tags.mlflow.runName'])}")
Terminal
uv run python view_types.py
Output
active_only ['alpha', 'gamma']
deleted_only ['beta']
all ['alpha', 'beta', 'gamma']

A terminal running uv run python view_types.py: active_only finds alpha and gamma, deleted_only finds beta, and all finds alpha, beta and gamma.

The default search, the first line, doesn't see beta at all. ViewType.to_string() turns each view into its name.

Step 3: Tell Deleted Runs Apart​

The DataFrame search_runs() returns has no column for whether a run is deleted. Ask for Run objects instead, and read run.info.lifecycle_stage. Create which_deleted.py:

which_deleted.py
import mlflow
from mlflow.entities import ViewType

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

runs = mlflow.search_runs(
experiment_names=["deleted-search-demo"],
run_view_type=ViewType.ALL,
output_format="list",
)
for run in runs:
print(f"{run.info.run_name:6} {run.info.lifecycle_stage}")
Terminal
uv run python which_deleted.py
Output
gamma active
beta deleted
alpha active

lifecycle_stage is active or deleted. It's separate from a run's status, such as FINISHED or FAILED: a finished run can be deleted.

Common Mistakes​

MistakeWhat happensDo this instead
Passing the view as text, run_view_type="all"ValueError: Unexpected view_type: allUse ViewType.ALL from mlflow.entities
Expecting the default search to find a deleted runIt's not in the resultsAdd run_view_type=ViewType.DELETED_ONLY or ViewType.ALL
Looking for a deleted flag in the DataFrameThere's no such columnUse output_format="list" and run.info.lifecycle_stage

Troubleshooting​

SymptomLikely causeFix
A run is missing from every viewIt was permanently deleted with mlflow gc, or it's in another experimentCheck the experiment name; a run removed by gc can't come back
NameError: name 'ViewType' is not definedThe import is missingAdd from mlflow.entities import ViewType
Deleted runs show up where you didn't expect themThe search uses ViewType.ALLUse the default, ViewType.ACTIVE_ONLY

FAQ​

What are the ViewType values?​

Numbers: ACTIVE_ONLY is 1, DELETED_ONLY 2 and ALL 3. Use the names; they're clearer.

Is there the same switch in the UI?​

Yes: the State filter next to the runs table's search box, with Active and Deleted.

How do I restore a run I found this way?​

Pass its run ID to mlflow.restore_run(): How to Restore a Deleted Run in MLflow.

Conclusion​

mlflow.search_runs() searches active runs by default. run_view_type=ViewType.DELETED_ONLY found only the deleted run, ViewType.ALL found all three, and run.info.lifecycle_stage from a list of Run objects told which ones were deleted.

Additional Resources​