dvc exp remove

Remove one or more experiments from the project

Description

Remove experiments from your DVC project. This command deletes experiment references and associated data, helping you clean up unsuccessful experiments or maintain a tidy experiment history. You can remove individual experiments, all experiments from specific commits, or queued experiments.

This operation is irreversible. Removed experiments cannot be recovered. Review your selection carefully before removing experiments.

Usage

dvc exp remove [<experiment>...] [options]

Aliases: dvc exp rm

Arguments

experiment · string[]

One or more experiment names to remove. Can specify multiple experiments separated by spaces.

dvc exp remove exp-a1b2c
dvc exp remove exp-123 exp-456 exp-789

Options

Selection Options

--rev · string[]

Remove all experiments from the specified Git revisions. Can be used multiple times.

dvc exp remove --rev HEAD
dvc exp remove --rev main --rev feature-branch

--all-commits · boolean · default: "false"

Remove experiments from all Git commits.

dvc exp remove --all-commits

--num · integer · default: "1"

Remove experiments from the last N commits. Used with --rev or --all-commits.

dvc exp remove --num 5

--queue · boolean · default: "false"

Remove all queued experiments (experiments staged with dvc exp run --queue but not yet executed).

dvc exp remove --queue

--keep · integer

Keep the N most recent experiments and remove the rest. Must be used with --rev or --all-commits.

dvc exp remove --all-commits --keep 10

-g, --git-remote · string

Name or URL of the Git remote to remove the experiment from. This removes experiments from a remote repository.

dvc exp remove exp-a1b2c --git-remote origin
dvc exp remove exp-a1b2c --git-remote https://github.com/user/repo.git

Examples

Remove a single experiment

dvc exp remove exp-a1b2c

Output:

Removed experiments: 'exp-a1b2c'

Removing an experiment deletes its reference and cached data, but doesn’t affect any Git branches created from it.

Remove multiple experiments

dvc exp remove exp-123 exp-456 exp-789

Output:

Removed experiments: 'exp-123', 'exp-456', 'exp-789'

Remove all experiments from current commit

dvc exp remove --rev HEAD

Output:

Removed experiments: 'exp-a1b2c', 'exp-d3e4f', 'exp-g7h8i'

This is useful for cleaning up after a hyperparameter sweep on the current commit.

Remove all queued experiments

# Queue some experiments
dvc exp run --queue -S lr=0.1
dvc exp run --queue -S lr=0.01
dvc exp run --queue -S lr=0.001

# Remove all queued experiments
dvc exp remove --queue

Output:

Removed experiments: 'exp-queued-1', 'exp-queued-2', 'exp-queued-3'

This only removes queued experiments that haven’t been executed yet.

Remove experiments from multiple branches

dvc exp remove --rev main --rev feature-branch

Output:

Removed experiments: 'exp-main-1', 'exp-main-2', 'exp-feature-1', 'exp-feature-2'

Keep only recent experiments

# Keep 5 most recent experiments, remove all others
dvc exp remove --all-commits --keep 5

Output:

Removed experiments: 'exp-old-1', 'exp-old-2', 'exp-old-3', ...

Use --keep to maintain a fixed number of experiments for reference while cleaning up older ones.

Remove from last N commits

# Remove experiments from last 3 commits
dvc exp remove --num 3

Output:

Removed experiments: 'exp-1', 'exp-2', 'exp-3', 'exp-4', 'exp-5'

Remove all experiments

dvc exp remove --all-commits

Output:

Removed experiments: 'exp-1', 'exp-2', ..., 'exp-99', 'exp-100'

This removes ALL experiments from your project. Use with extreme caution!

Remove from remote repository

dvc exp remove exp-a1b2c --git-remote origin

Output:

Removed experiments: 'exp-a1b2c' from remote 'origin'

This removes the experiment from the remote Git repository, not just your local copy.

Common Workflows

Clean up failed experiments

# View all experiments including failed ones
dvc exp show

# Remove failed experiments one by one
dvc exp remove exp-failed-1 exp-failed-2 exp-failed-3

Maintain experiment history limit

# Periodically clean up, keeping only last 20 experiments
dvc exp remove --all-commits --keep 20

Cancel queued experiments

# Queue multiple experiments
for lr in 0.1 0.01 0.001 0.0001 0.00001; do
  dvc exp run --queue -S train.lr=$lr
done

# Decided not to run them
dvc exp remove --queue

Clean up before archiving

# Before archiving project, remove all experiments
# (keep only promoted branches)
dvc exp remove --all-commits

# Archive repository
git archive --format=zip --output=project-archive.zip HEAD

Remove experiments after promotion

# Find best experiment
dvc exp show --sort-by accuracy --sort-order desc

# Promote it to a branch
dvc exp branch exp-best model/production

# Remove the temporary experiment
dvc exp remove exp-best

# The branch persists even though experiment is removed
git branch

Removing an experiment doesn’t affect Git branches created from it using dvc exp branch.

Understanding Removal Scope

What Gets Removed

1. Experiment references: Entries in DVC’s experiment database
2. Cached data: Model outputs and artifacts unique to the experiment
3. Metrics history: Historical metrics recorded for the experiment
4. Parameter snapshots: Parameter values used in the experiment

What Doesn’t Get Removed

1. Git branches: Branches created via dvc exp branch remain intact
2. Shared cache: Data shared with other experiments or commits
3. Git commits: Regular Git commits are unaffected
4. Current workspace: Your working directory remains unchanged

DVC uses reference counting for cached data. Removing an experiment only deletes data that’s not referenced by other experiments or commits.

Validation and Safety

Confirm before removal

# List experiments that would be removed
dvc exp show --rev HEAD

# Then remove
dvc exp remove --rev HEAD

Remove with filtering

# View all experiments
dvc exp show

# Remove only specific failed ones
dvc exp show | grep "!" | awk '{print $1}' | xargs dvc exp remove

Backup before bulk removal

# Export experiments to JSON before removing
dvc exp show --json > experiments-backup.json

# Now safe to remove
dvc exp remove --all-commits --keep 10

# Can review backup if needed
cat experiments-backup.json | jq

Troubleshooting

No experiments to remove

dvc exp remove --rev HEAD

Output:

No experiments to remove.

This means there are no experiments associated with the specified revision.

Experiment not found

dvc exp remove nonexistent-exp

Output:

ERROR: experiment 'nonexistent-exp' not found

Solution:

# List available experiments
dvc exp show

# Use correct experiment name
dvc exp remove exp-a1b2c

Cannot remove from remote

dvc exp remove exp-a1b2c --git-remote origin

Output:

ERROR: permission denied when removing from remote 'origin'

Removing experiments from a remote requires write access to the remote repository.

Related Commands

• dvc exp show - View experiments before removing
• dvc exp run - Create new experiments
• dvc exp branch - Convert experiment to permanent branch before removing
• dvc gc - Clean up unused cache data (after removing experiments)