Skip to main content

How to Create Nested Runs in MLflow

· 6 min read
Jagdish Kumawat
Founder @ Dewiride

When one experiment is really several runs, such as trying three settings to compare them, MLflow can group them: start a parent run, then start each child run inside it with nested=True. The UI then shows the children folded under their parent instead of as loose runs. This guide compares three settings of a classifier as children of one parent, with real output from MLflow 3.18.0.

Syntax​

Syntax
with mlflow.start_run(run_name="<parent name>"):
with mlflow.start_run(run_name="<child name>", nested=True):
...
PartWhat it means
The outer start_runThe parent run. It stays open while its children run
nested=True"True creates a nested run", in the words of MLflow's reference: the new run becomes a child of the run that's open
The inner with blockEverything logged here goes to the child. When the block ends, the child ends and the parent is the open run again

Prerequisites​

Step 1: Log Three Children Under One Parent​

The example compares three values of n_neighbors for a k-nearest-neighbors classifier on the iris flowers. Each value is a child run with its setting and its cross-validated accuracy. Create nested_runs.py:

The nested_runs.py script in a macOS-style code window: inside a parent run named compare-neighbors, a loop over k 1, 5 and 15 starts a run named k-1, k-5 and k-15 with nested True, computes the cross-validated accuracy of a KNeighborsClassifier, and logs n_neighbors and accuracy.

nested_runs.py
import mlflow
from sklearn.datasets import load_iris
from sklearn.model_selection import cross_val_score
from sklearn.neighbors import KNeighborsClassifier

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

X, y = load_iris(return_X_y=True)

with mlflow.start_run(run_name="compare-neighbors"):
for k in [1, 5, 15]:
with mlflow.start_run(run_name=f"k-{k}", nested=True):
accuracy = cross_val_score(KNeighborsClassifier(n_neighbors=k), X, y, cv=5).mean()
mlflow.log_param("n_neighbors", k)
mlflow.log_metric("accuracy", accuracy)
Terminal
uv run python nested_runs.py
Output
2026/11/21 11:02:03 INFO mlflow.tracking.fluent: Experiment with name 'nested-runs-demo' does not exist. Creating a new experiment.
🏃 View run k-1 at: http://127.0.0.1:8080/#/experiments/6/runs/af617b91f3a44099befc8d7ec427fafc
🧪 View experiment at: http://127.0.0.1:8080/#/experiments/6
🏃 View run k-5 at: http://127.0.0.1:8080/#/experiments/6/runs/f155cad762614ace94cb2fcf13fc74ab
🧪 View experiment at: http://127.0.0.1:8080/#/experiments/6
🏃 View run k-15 at: http://127.0.0.1:8080/#/experiments/6/runs/b6ed19486a384b56bc82b7e2bb21f2c8
🧪 View experiment at: http://127.0.0.1:8080/#/experiments/6
🏃 View run compare-neighbors at: http://127.0.0.1:8080/#/experiments/6/runs/79590c65d8be4651ba078c1f3b554702
🧪 View experiment at: http://127.0.0.1:8080/#/experiments/6

A terminal running uv run python nested_runs.py: the nested-runs-demo experiment is created, then links to the runs k-1, k-5 and k-15, and last to the parent compare-neighbors.

Each child's link appears when its with block ends, and the parent's last, when the outer block ends.

Step 2: See the Group in the UI​

In the runs table, the parent has a + next to its name; click it to show its children:

The nested-runs-demo runs table: the parent compare-neighbors expanded, with three children: k-15 with accuracy 0.9667, k-5 with 0.9733 and k-1 with 0.96, each with its n_neighbors.

k-5 scored best, 0.9733. What links a child to its parent is a tag MLflow sets on the child, mlflow.parentRunId, holding the parent's run ID: the UI groups runs by it, and you can search by it too.

Step 3: Know the Other Way In​

start_run also takes parent_run_id="<run ID>", which nests the new run under a run you name instead of the open one. MLflow's reference adds that "the parent run must be in the ACTIVE state", so it's for adding children while the parent is still running, not for regrouping finished runs.

Common Mistakes​

MistakeWhat happensDo this instead
Starting the inner run without nested=TrueException: Run with UUID ... is already active. To start a new run, first end the current run with mlflow.end_run(). To start a nested run, call start_run with nested=TrueAdd nested=True
Starting the children after the parent's with blockThey become separate runs, not childrenStart them inside the parent's block
Logging the comparison's result inside a childIt lands on that child, not the parentLog it after the loop, inside the parent's block

Troubleshooting​

SymptomLikely causeFix
Exception: Run with UUID ... is already activeA second run without nested=TrueAdd nested=True
The children show as loose runsThey were started when no parent was openCheck the indentation of the with blocks

FAQ​

Can children have children?​

Yes: start another nested=True run inside a child, and its mlflow.parentRunId points at that child. A nested=True run started when no run is open is an ordinary top-level run.

Does autologging create nested runs too?​

Yes, for hyperparameter searches: How to Log a GridSearchCV Search in MLflow with Parent and Child Runs.

Conclusion​

mlflow.start_run(run_name=f"k-{k}", nested=True) inside the compare-neighbors run created three children, grouped under their parent in the UI by the mlflow.parentRunId tag. Open the parent first, start every child inside it with nested=True, and log the comparison's result on the parent.

Additional Resources​