Experiments

---
name: experiments
description: "Run, queue, compare, promote, share, and clean up DVC experiments
  without confusing them with ordinary pipeline reproduction."
disable-model-invocation: true
metadata:
  disco-role: operating
license: Apache 2.0
---

# DVC Experiments

Use this sub-skill when a user asks to run, queue, compare, apply, branch, push, pull, rename, remove, save, or clean DVC experiments with the `dvc exp`/`dvc experiments` command family or the public experiments API.

## Route Here For

- Running experiments with `dvc exp run`, including `--name`, `--set-param`, `--queue`, `--run-all`, `--jobs`, `--temp`, `--copy-paths`, `--message`, and `--no-hydra`.
- Comparing and inspecting experiments with `dvc exp show`, `dvc exp diff`, `dvc exp list`/`ls`, and the bundled `scripts/inspect_experiments.py` helper.
- Promoting or restoring experiment results with `dvc exp apply`, `dvc exp branch`, and `dvc exp save`.
- Sharing and maintaining experiment refs with `dvc exp push`, `dvc exp pull`, `dvc exp rename`, `dvc exp remove`/`rm`, and `dvc exp clean`.

## Route Elsewhere

- Use `../data-and-pipelines/` for creating stages, `dvc.yaml`, dependencies, outs, and normal `dvc repro` pipeline design.
- Use `../metrics-params-plots/` for interpreting metrics, params, and plots beyond how `dvc exp show` surfaces them.
- Use `../remotes-and-cache/` for configuring remotes, credentials, cache layout, and storage backends used by `exp push/pull --remote`.

## Read Next

- Read `references/workflows.md` for concrete run, queue, compare, promote, share, and cleanup recipes.
- Read `references/api-reference.md` for `dvc.api.exp_save()` and `dvc.api.exp_show()` signatures, returns, and safe usage.
- Read `references/troubleshooting.md` when experiments are hidden, stale, queued, failed, blocked by workspace state, missing copied files, or affected by Hydra/network boundaries.
- Run `python scripts/inspect_experiments.py --help` to inspect experiments as JSON through the public API without network access by default.

## Default Decision Pattern

1. Confirm that the user already has a DVC project with a pipeline; if not, route to `data-and-pipelines` first.
2. Use `dvc exp run` for a one-off experiment that should execute now, `dvc exp run --queue` for parameter sweeps or deferred execution, and `dvc exp run --run-all -j <n>` to execute queued experiments.
3. Use `dvc exp show --json` or the bundled inspector for machine-readable comparison; use `dvc exp diff` for pairwise metric/param changes.
4. Use `dvc exp apply` for workspace inspection, `dvc exp branch` for durable Git review, and `dvc exp push/pull` only after remote and cache behavior are clear.