Skip to main content

How to Delete a Run in MLflow

· 6 min read
Jagdish Kumawat
Founder @ Dewiride

Experiments collect runs you don't need: drafts, test runs, runs that crashed. Deleting them keeps the runs table and every search focused on the ones that matter. In MLflow, deleting moves a run aside rather than erasing it, so a mistake can be undone. This guide deletes three draft runs, one with each of the three ways MLflow offers, with real screens and output from MLflow 3.18.0.

Syntax​

Syntax (Python)
mlflow.delete_run("<run ID>")
Syntax (terminal)
mlflow runs delete --run-id <run ID>
PartWhat it means
"<run ID>" / --run-idThe ID of the run to delete, shown on the run's page and in its View run link
The resultThe run's lifecycle stage becomes deleted: it disappears from the runs table and from searches, and its data stays where it is

The command finds the tracking server through the MLFLOW_TRACKING_URI environment variable. In the UI, the Delete button above the runs table does the same.

Prerequisites​

Step 1: Create the Runs​

The example is one run to keep, final, and three drafts to delete. Create draft_runs.py:

draft_runs.py
import mlflow

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

for name in ["final", "draft-1", "draft-2", "draft-3"]:
with mlflow.start_run(run_name=name):
mlflow.log_metric("accuracy", 0.9 if name == "final" else 0.5)
Terminal
uv run python draft_runs.py

It prints a View run link for each run, with its ID. draft-3's ID here is c0ddc14d00a948eba76769a1839e1af8.

Step 2: Delete a Run in the UI​

Open the experiment, delete-demo, and tick the box in front of draft-1. The toolbar above the table changes to Rename, Delete, Compare and Add tags:

The delete-demo runs table with draft-1 ticked: the toolbar now shows Rename, a red Delete button, Compare and Add tags, above the runs draft-3, draft-2, draft-1 and final.

Click Delete. MLflow asks you to confirm:

The Delete Experiment Run dialog: Selected 1 experiment run, with Cancel and Delete selected buttons.

Click Delete selected. draft-1 disappears from the table:

The delete-demo runs table after the deletion: draft-3, draft-2 and final are left.

Tick several runs to delete them together; the dialog counts them.

Step 3: Delete a Run in Python​

mlflow.delete_run() takes a run ID. This script finds draft-2 by name, deletes it, and reads its lifecycle stage back. Create delete_run.py:

The delete_run.py script in a macOS-style code window: it searches the delete-demo experiment for the run named draft-2 as a list of runs, calls mlflow.delete_run with its run ID, and prints the run's name and its lifecycle stage from mlflow.get_run.

delete_run.py
import mlflow

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

run = mlflow.search_runs(
experiment_names=["delete-demo"],
filter_string="attributes.run_name = 'draft-2'",
output_format="list",
)[0]

mlflow.delete_run(run.info.run_id)
print(run.info.run_name, "is now", mlflow.get_run(run.info.run_id).info.lifecycle_stage)
Terminal
uv run python delete_run.py
Output
draft-2 is now deleted

mlflow.get_run() still finds the run: deleted runs keep their data, with the lifecycle stage deleted instead of active.

Step 4: Delete a Run from the Terminal​

Point the terminal at the server, then delete draft-3 by its ID:

Terminal
export MLFLOW_TRACKING_URI=http://127.0.0.1:8080
uv run mlflow runs delete --run-id c0ddc14d00a948eba76769a1839e1af8
Output
Run with ID c0ddc14d00a948eba76769a1839e1af8 has been deleted.

All three drafts are now deleted, and final is the only run left in the table.

Common Mistakes​

MistakeWhat happensDo this instead
Expecting deleting to free disk spaceThe run's data and files stay on the serverRemove deleted runs for good with mlflow gc
A wrong run IDRESOURCE_DOES_NOT_EXIST: Run with id=0123456789abcdef0123456789abcdef not foundCopy the ID from the run's page or its View run link
Running the command without MLFLOW_TRACKING_URIMlflowException: Run with id=... not found, and a new, empty mlflow.db appears in the folder: the command looked in a local database instead of your serverSet the variable in the same terminal first, and delete the stray mlflow.db

Troubleshooting​

SymptomLikely causeFix
A deleted run still shows in a search in PythonThe search includes deleted runs, with run_view_type=ViewType.ALLLeave run_view_type at its default
Deleting the same run again prints "has been deleted" againMLflow 3.18.0 accepts it without an error, though its CLI reference says it returns oneNothing to fix: the run stays deleted
You deleted the wrong runDeleting only moved it to the deleted stageRestore it: How to Restore a Deleted Run in MLflow

FAQ​

Where do deleted runs go?​

Nowhere: they stay in the same database with the lifecycle stage deleted. The runs table's State filter shows them, and searches in Python include them when you ask: How to Include Deleted Runs in an MLflow Search in Python.

Can I delete a whole experiment?​

Yes, with mlflow.delete_experiment() or the Delete button on the UI's experiments list, and mlflow.restore_experiment() brings it back.

Is a deleted run ever removed for good?​

Only when you run mlflow gc, which permanently deletes runs in the deleted stage.

Conclusion​

The Delete button, mlflow.delete_run(run_id) and mlflow runs delete --run-id all moved a run to the deleted stage: gone from the table and from searches, but kept, so it can be restored until mlflow gc removes it for good.

Additional Resources​