Implementation:Iterative Dvc Experiments Save

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

Overview

Concrete tool for saving the current workspace status as a versioned experiment snapshot, provided by the DVC library.

Description

The save function in dvc.repo.experiments.save persists the current workspace state as an experiment commit under DVC's experiment ref namespace (refs/exps/). Unlike run, which reproduces the pipeline before capturing results, save captures the workspace as-is without re-executing any pipeline stages. This makes it suitable for snapshotting results from manual experimentation, interactive sessions, or external training runs.

The function works by creating a new queue entry on the WorkspaceQueue, initializing an executor, and then calling the executor's save method, which stages all relevant files (metrics, parameters, pipeline outputs) and creates a Git commit. The commit is stored under the experiment ref namespace and the result is collected by the queue. The function returns the experiment's commit SHA, or None if the save operation produced no result.

The function supports optional targeting of specific pipeline stages, recursive stage discovery, force overwrite of existing experiment names, inclusion of untracked files, and custom commit messages.

Usage

Import and use this function when:

You want to snapshot the current workspace as a named experiment without re-running the pipeline
You have completed an experiment externally and want to capture the results in DVC's experiment tracking system
You need to save intermediate workspace states during interactive exploration

Code Reference

Source Location

Repository: DVC
File: dvc/repo/experiments/save.py
Lines: L16-48

Signature

def save(
    repo: "Repo",
    targets: Optional[Iterable[str]] = None,
    name: Optional[str] = None,
    recursive: bool = False,
    force: bool = False,
    include_untracked: Optional[list[str]] = None,
    message: Optional[str] = None,
) -> Optional[str]:
    ...

Import

from dvc.repo.experiments.save import save

I/O Contract

Inputs

Name	Type	Required	Description
repo	`Repo`	Yes	The DVC repository instance. Must have Git SCM initialized (not `no_scm` mode).
targets	`Optional[Iterable[str]]`	No	Specific pipeline stage targets to include in the save. If `None`, all stages are included.
name	`Optional[str]`	No	Human-readable name for the experiment. Used as the ref name under `refs/exps/`. If `None`, DVC auto-generates a name.
recursive	`bool`	No	If `True`, recursively discovers stages from the specified targets. Defaults to `False`.
force	`bool`	No	If `True`, allows overwriting an existing experiment with the same name. Defaults to `False`.
include_untracked	`Optional[list[str]]`	No	List of file paths that are currently untracked by Git but should be included in the experiment snapshot.
message	`Optional[str]`	No	Custom commit message for the experiment's Git commit. If `None`, a default message is generated.

Outputs

Name	Type	Description
return	`Optional[str]`	The experiment commit SHA if the save was successful. `None` if no result was produced. The commit is persisted as a Git ref under `refs/exps/{baseline_sha}/{name}`.

Usage Examples

Basic Usage: Save Current Workspace

from dvc.repo import Repo
from dvc.repo.experiments.save import save

with Repo() as repo:
    exp_sha = save(repo, name="baseline-run")
    if exp_sha:
        print(f"Saved experiment: {exp_sha[:7]}")

Save with Untracked Files

from dvc.repo import Repo
from dvc.repo.experiments.save import save

with Repo() as repo:
    # Include model checkpoint that is not yet tracked by Git
    exp_sha = save(
        repo,
        name="checkpoint-v1",
        include_untracked=["models/checkpoint.pt", "logs/train.log"],
    )

Force Overwrite Existing Experiment

from dvc.repo import Repo
from dvc.repo.experiments.save import save

with Repo() as repo:
    # Overwrite a previous experiment with the same name
    exp_sha = save(
        repo,
        name="tuned-model",
        force=True,
        message="Re-saved after manual parameter tuning",
    )

Save Specific Pipeline Targets

from dvc.repo import Repo
from dvc.repo.experiments.save import save

with Repo() as repo:
    # Only save results from the "train" and "evaluate" stages
    exp_sha = save(
        repo,
        targets=["train", "evaluate"],
        name="train-eval-only",
    )

Related Pages

Implements Principle

Principle:Iterative_Dvc_Experiment_Result_Capture

Requires Environment

Page Connections

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

Principle

Implementation

Heuristic

Environment