Implementation:Iterative Dvc Experiments Apply Remove
| Knowledge Sources | |
|---|---|
| Domains | Experiment_Management, Version_Control |
| Last Updated | 2026-02-10 00:00 GMT |
Overview
Concrete tool for applying experiment results to the workspace and removing experiments from the ref namespace, provided by the DVC library.
Description
The dvc.repo.experiments.apply and dvc.repo.experiments.remove modules provide the final lifecycle operations for DVC experiments.
The apply function resolves an experiment revision (by name or SHA), checks out its complete state into the current workspace using a detach-head-and-restore pattern, runs dvc checkout to update DVC-tracked files, and records the applied experiment's SHA under the EXEC_APPLY ref. It handles experiments that are stored both as committed refs and as queued stash entries, using the ApplyStash context manager to preserve workspace state during the operation.
The remove function deletes experiment refs and/or queue entries based on flexible selection criteria. It supports removal by name (exp_names), by baseline revision (rev), all experiments (all_commits), queued experiments only (queue), or inverse selection (keep). For committed experiments, it deletes the Git refs under refs/exps/. For queued experiments, it delegates to the Celery queue's task removal mechanism. When targeting a remote repository, it pushes empty refspecs to delete remote refs and notifies DVC Studio of the changes.
Usage
Import and use these functions when:
- You want to promote an experiment's results to the current workspace
- You need to clean up experiment refs after a hyperparameter search
- You need to clear the experiment queue of pending entries
- You are building automation that selects and applies the best experiment
Code Reference
Source Location
- Repository: DVC
- File:
dvc/repo/experiments/apply.py - Lines: L22-56 (
apply) - File:
dvc/repo/experiments/remove.py - Lines: L23-98 (
remove)
Signature
@locked
@scm_context
def apply(
repo: "Repo",
rev: str,
**kwargs,
) -> None:
...
@locked
@scm_context
def remove(
repo: "Repo",
exp_names: Union[str, list[str], None] = None,
rev: Optional[Union[list[str], str]] = None,
all_commits: bool = False,
num: int = 1,
queue: bool = False,
git_remote: Optional[str] = None,
keep: bool = False,
) -> list[str]:
...
Import
from dvc.repo.experiments.apply import apply
from dvc.repo.experiments.remove import remove
I/O Contract
Inputs
apply:
| Name | Type | Required | Description |
|---|---|---|---|
| repo | Repo |
Yes | The DVC repository instance. Must have Git SCM initialized. |
| rev | str |
Yes | Experiment revision identifier. Can be an experiment name, a Git SHA, or a short SHA. The function resolves the name through experiment refs and the Celery queue. |
| **kwargs | various | No | Additional keyword arguments passed to dvc_checkout. The force=True flag is set automatically.
|
remove:
| Name | Type | Required | Description |
|---|---|---|---|
| repo | Repo |
Yes | The DVC repository instance. Must have Git SCM initialized. |
| exp_names | Union[str, list[str], None] |
No | Experiment names to remove. Resolved against both committed experiment refs and queued entries. |
| rev | Optional[Union[list[str], str]] |
No | Baseline revision(s). All experiments derived from these baselines will be removed. |
| all_commits | bool |
No | If True, removes all committed experiments. Defaults to False.
|
| num | int |
No | Number of recent commits to include when resolving by rev. Defaults to 1.
|
| queue | bool |
No | If True, clears all queued (pending) experiments from the Celery queue. Cannot be used with keep. Defaults to False.
|
| git_remote | Optional[str] |
No | Name of a Git remote. If provided, removes experiments from the remote repository instead of the local one. |
| keep | bool |
No | If True, inverts the selection: removes all experiments except the specified ones. Cannot be used with queue. Defaults to False.
|
Outputs
apply:
| Name | Type | Description |
|---|---|---|
| return | None |
The function modifies the workspace in place. The current working directory is updated to match the experiment's state. DVC-tracked files are checked out. The EXEC_APPLY ref is set to the applied experiment's SHA.
|
remove:
| Name | Type | Description |
|---|---|---|
| return | list[str] |
List of removed experiment names. Git refs under refs/exps/ are deleted for committed experiments. Celery task entries are removed for queued experiments. If git_remote is specified, remote refs are deleted and DVC Studio is notified.
|
Usage Examples
Basic Usage: Apply an Experiment
from dvc.repo import Repo
from dvc.repo.experiments.apply import apply
with Repo() as repo:
# Apply experiment by name
apply(repo, rev="best-lr-experiment")
# Workspace now contains the experiment's parameters,
# metrics, and outputs
Basic Usage: Remove Experiments by Name
from dvc.repo import Repo
from dvc.repo.experiments.remove import remove
with Repo() as repo:
removed = remove(repo, exp_names=["failed-run-1", "failed-run-2"])
print(f"Removed experiments: {removed}")
Clear the Experiment Queue
from dvc.repo import Repo
from dvc.repo.experiments.remove import remove
with Repo() as repo:
removed = remove(repo, queue=True)
print(f"Cleared {len(removed)} queued experiments")
Remove All Experiments Except the Best
from dvc.repo import Repo
from dvc.repo.experiments.remove import remove
with Repo() as repo:
# Keep only the best experiment, remove everything else
removed = remove(
repo,
exp_names=["best-experiment"],
keep=True,
)
print(f"Removed {len(removed)} experiments, kept 'best-experiment'")
Remove Experiments from a Remote
from dvc.repo import Repo
from dvc.repo.experiments.remove import remove
with Repo() as repo:
removed = remove(
repo,
exp_names=["old-experiment"],
git_remote="origin",
)
print(f"Removed from remote: {removed}")
Remove All Experiments for a Baseline
from dvc.repo import Repo
from dvc.repo.experiments.remove import remove
with Repo() as repo:
# Remove all experiments derived from a specific commit
removed = remove(repo, rev=["abc1234"])
print(f"Removed: {removed}")