Implementation:Iterative Dvc Experiments New

Knowledge Sources	DVC
Domains	Experiment_Management, Reproducibility
Last Updated	2026-02-10 00:00 GMT

Overview

Concrete tool for creating and enqueuing new experiment entries from the current workspace state, provided by the DVC library.

Description

The Experiments.new and Experiments.queue_one methods in the dvc.repo.experiments module handle the creation of new experiment entries. new validates the experiment name for uniqueness and ref format compliance, then delegates to the queue's put method to stash the current workspace state (including any parameter modifications) as a QueueEntry. queue_one is a thin convenience wrapper that calls new with a specified queue.

The method supports three queue types that correspond to different isolation levels: WorkspaceQueue (in-place execution), TempDirQueue (temporary directory isolation), and LocalCeleryQueue (distributed execution via Celery). All three share the same stash-based mechanism for capturing workspace state, differing only in how the stashed entry is later executed.

Name uniqueness is enforced by checking whether a Git ref already exists under the refs/exps/ namespace for the given baseline SHA. If a ref exists and force=False, an ExperimentExistsError is raised, preventing accidental overwriting of prior results.

Usage

Import and use these methods when:

You need to programmatically create and enqueue experiments from a DVC repository
You are building automation that queues multiple experiments with different parameter configurations
You need to validate experiment names before enqueueing

Code Reference

Source Location

Repository: DVC
File: dvc/repo/experiments/__init__.py
Lines: L202-218 (new), L134-136 (queue_one)

Signature

class Experiments:
    def new(
        self,
        queue: "BaseStashQueue",
        *args,
        **kwargs,
    ) -> "QueueEntry":
        """Create and enqueue a new experiment.

        Experiment will be derived from the current workspace.
        """
        ...

    def queue_one(
        self,
        queue: "BaseStashQueue",
        **kwargs,
    ) -> "QueueEntry":
        """Queue a single experiment."""
        ...

Import

from dvc.repo.experiments import Experiments

I/O Contract

Inputs

Experiments.new:

Name	Type	Required	Description
queue	`BaseStashQueue`	Yes	The experiment queue to enqueue the entry into. Must be one of `WorkspaceQueue`, `TempDirQueue`, or `LocalCeleryQueue`.
name	`Optional[str]`	No	Human-readable experiment name. If provided, uniqueness is validated against existing refs under the same baseline. Passed via `kwargs`.
baseline_rev	`Optional[str]`	No	The baseline Git commit SHA. Defaults to the current HEAD revision if not provided. Passed via `kwargs`.
force	`bool`	No	If `True`, allows overwriting an existing experiment with the same name. Defaults to `False`. Passed via `kwargs`.
params	`dict[str, list[str]]`	No	Parameter overrides mapping file paths to override strings. Passed through to queue's `put` method via `kwargs`.
targets	`Optional[Iterable[str]]`	No	Pipeline stage targets for the experiment. Passed through to queue's `put` method via `kwargs`.
copy_paths	`Optional[list[str]]`	No	Additional paths to copy into the experiment workspace. Passed through via `kwargs`.

Experiments.queue_one:

Name	Type	Required	Description
queue	`BaseStashQueue`	Yes	The experiment queue to use. Typically `self.celery_queue` for queued execution.
**kwargs	various	No	All additional keyword arguments are forwarded to `new`.

Outputs

Name	Type	Description
return	`QueueEntry`	A stashed experiment entry ready for execution. Contains the stash revision SHA, optional experiment name, and queue metadata needed to later reproduce the experiment.

Usage Examples

Basic Usage: Queue an Experiment

from dvc.repo import Repo

repo = Repo()
exps = repo.experiments

# Queue an experiment with parameter overrides to the Celery queue
entry = exps.queue_one(
    exps.celery_queue,
    params={"params.yaml": ["train.lr=0.001", "train.epochs=100"]},
    name="lr-experiment-1",
)
print(f"Queued experiment: {entry.name or entry.stash_rev[:7]}")

Basic Usage: Create Experiment for Immediate Execution

from dvc.repo import Repo

repo = Repo()
exps = repo.experiments

# Create an experiment on the workspace queue (in-place execution)
entry = exps.new(
    exps.workspace_queue,
    params={"params.yaml": ["model.hidden_dim=256"]},
    name="hidden-256",
)

Advanced Usage: Force Overwrite Existing Experiment

from dvc.repo import Repo

repo = Repo()
exps = repo.experiments

# Force-create an experiment even if the name already exists
entry = exps.new(
    exps.celery_queue,
    params={"params.yaml": ["train.lr=0.005"]},
    name="lr-experiment-1",
    force=True,
)

Related Pages

Implements Principle

Principle:Iterative_Dvc_Experiment_Workspace_Preparation

Requires Environment

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment