Skip to main content

How to Restore a Deleted Run in MLflow

· 6 min read
Jagdish Kumawat
Founder @ Dewiride

Deleting a run in MLflow doesn't erase it: the run moves to a deleted stage, out of sight but with all its data. Until someone removes it for good with mlflow gc, you can bring it back exactly as it was. This guide restores three deleted runs, one in the UI, one in Python and one from a terminal, with real screens and output from MLflow 3.18.0.

Syntax​

Syntax (Python)
mlflow.restore_run("<run ID>")
Syntax (terminal)
mlflow runs restore --run-id <run ID>
PartWhat it means
"<run ID>" / --run-idThe ID of the deleted run, printed when it was created and shown on its page
The resultThe run's lifecycle stage goes from deleted back to active, and it shows in the runs table and in searches again

The command finds the tracking server through MLFLOW_TRACKING_URI. In the UI, the State filter and a Restore button do the same.

Prerequisites​

Step 1: Create Three Deleted Runs​

The example is three runs that were deleted by mistake right after they were created. Create deleted_by_mistake.py:

deleted_by_mistake.py
import mlflow

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

for name in ["first-try", "second-try", "third-try"]:
with mlflow.start_run(run_name=name) as run:
mlflow.log_metric("accuracy", 0.9)
mlflow.delete_run(run.info.run_id)
print(f"Deleted {name}: {run.info.run_id}")
Terminal
uv run python deleted_by_mistake.py
Output (without the View run links)
Deleted first-try: 6a3eb52639e9461f89120ea1f19b4c54
Deleted second-try: 1206e339ecd44d399e9c1ed15a90f46c
Deleted third-try: ee86a5b0de29405fbe93220a97285714

The experiment, restore-demo, now shows an empty runs table.

Step 2: Restore a Run in the UI​

Click State: Active in the toolbar and choose Deleted. The table switches to the deleted runs:

The restore-demo runs table with State: Deleted selected: three runs, third-try, second-try and first-try, each with a green tick in the Created column.

Tick first-try. Where the toolbar would offer Delete, it now offers Restore:

The deleted runs of restore-demo with first-try ticked: the toolbar shows Rename, Restore, Compare and Add tags.

Click Restore, then Restore again in the dialog:

The Restore Experiment Run dialog: 1 experiment run will be restored, with a Restore button.

Set State back to Active. first-try is back:

The restore-demo runs table with State: Active: first-try is listed again.

Step 3: Restore a Run in Python​

mlflow.restore_run() takes the run's ID. Create restore_run.py, which takes the ID on the command line:

The restore_run.py script in a macOS-style code window: it takes a run ID from the command line, calls mlflow.restore_run with it, reads the run back with mlflow.get_run, and prints its name and lifecycle stage.

restore_run.py
import sys

import mlflow

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

run_id = sys.argv[1]
mlflow.restore_run(run_id)
run = mlflow.get_run(run_id)
print(run.info.run_name, "is now", run.info.lifecycle_stage)

Restore second-try with its ID from Step 1:

Terminal
uv run python restore_run.py 1206e339ecd44d399e9c1ed15a90f46c
Output
second-try is now active

Step 4: Restore a Run from the Terminal​

Point the terminal at the server, then restore third-try:

Terminal
export MLFLOW_TRACKING_URI=http://127.0.0.1:8080
uv run mlflow runs restore --run-id ee86a5b0de29405fbe93220a97285714
Output
Run with id ee86a5b0de29405fbe93220a97285714 has been restored.

All three runs are active again, with their accuracy and everything else they logged.

Common Mistakes​

MistakeWhat happensDo this instead
Looking for a deleted run with State: ActiveIt isn't thereSwitch State to Deleted
Trying to restore a run after mlflow gc removed itRESOURCE_DOES_NOT_EXIST: Run with id=... not foundNothing brings it back; run gc only on runs you're sure about
Running the command without MLFLOW_TRACKING_URIRun with id=... not found: the command looked in a local databaseSet the variable in the same terminal first

Troubleshooting​

SymptomLikely causeFix
Restoring a run that isn't deleted prints "has been restored"MLflow 3.18.0 accepts it without an error, though its CLI reference says it returns one; nothing changesCheck the run's stage with mlflow.get_run(run_id).info.lifecycle_stage
The Restore button doesn't appearThe ticked run isn't deleted, so the toolbar offers DeleteSwitch State to Deleted first
You need a deleted run's IDDeleted runs don't appear in normal searchesOpen the run under State: Deleted, or search with run_view_type=ViewType.DELETED_ONLY in Python

FAQ​

Does a restored run lose anything?​

No. Deleting only changed its lifecycle stage, so its parameters, metrics, tags and files are all still there.

Can I restore several runs at once?​

Yes: tick them all under State: Deleted and click Restore once.

How long can I wait before restoring?​

As long as you like, until mlflow gc permanently deletes the run: How to Permanently Delete MLflow Runs with mlflow gc.

Conclusion​

A deleted run came back with State: Deleted and Restore in the UI, with mlflow.restore_run(run_id) in Python, and with mlflow runs restore --run-id in a terminal. Restoring works until mlflow gc removes the run for good.

Additional Resources​