Implementation:Iterative Dvc Api Experiments

Knowledge Sources	Iterative_Dvc
Domains	API, Experiment_Tracking
Last Updated	2026-02-10 10:00 GMT

Overview

Public API functions for saving and displaying DVC experiments programmatically, provided by the DVC library.

Description

The dvc/api/experiments.py module (120 lines) exposes two public functions -- exp_save and exp_show -- that provide programmatic access to DVC's experiment tracking capabilities. These functions are part of DVC's public Python API and correspond to the dvc exp save and dvc exp show CLI commands.

exp_save creates a new DVC experiment snapshot from the current workspace state. It accepts an optional name (auto-generated if not provided, e.g., "urban-sign"), a force flag to overwrite existing experiments with the same name, and an include_untracked list to capture untracked files in the experiment snapshot. It opens a Repo context and delegates to repo.experiments.save(), returning the Git revision SHA of the created experiment.

exp_show retrieves experiment data from a DVC repository. It accepts a repo path or URL, revs (one or more Git revisions to use as baselines), num (number of parent commits to include), param_deps (to filter parameters to stage dependencies only), force (to bypass the experiment cache), and config (to pass DVC configuration). It opens the repository, calls repo.experiments.show(), tabulates the results, and post-processes the output via _postprocess -- which converts rich.text.Text objects to native Python types (floats where possible, strings otherwise) and replaces falsy values with None.

Usage

Use exp_save to programmatically create experiment snapshots -- for example, at the end of a training script to record the final state. Use exp_show to retrieve structured experiment data for analysis, comparison dashboards, or CI/CD pipelines that need to inspect experiment metrics and parameters.

Code Reference

Source Location

• Repository: DVC
• File: dvc/api/experiments.py
• Lines: L1-121

Signature

def exp_save(
    name: Optional[str] = None,
    force: bool = False,
    include_untracked: Optional[list[str]] = None,
) -> str:
    """Create a new DVC experiment using exp save.

    Args:
        name (str, optional): specify a name for this experiment.
        force (bool): overwrite the experiment if one with the
            same name already exists. Defaults to False.
        include_untracked (List[str], optional): specify untracked
            file(s) to be included in the saved experiment.

    Returns:
        str: The Git revision of the created experiment.

    Raises:
        ExperimentExistsError: If an experiment with the given name
            already exists and force=False.
    """
    ...


def exp_show(
    repo: Optional[str] = None,
    revs: Optional[Union[str, list[str]]] = None,
    num: int = 1,
    param_deps: bool = False,
    force: bool = False,
    config: Optional[dict] = None,
) -> list[dict]:
    """Get DVC experiments tracked in repo.

    Args:
        repo (str, optional): location of the DVC repository.
        revs (Union[str, List[str]], optional): Git revision(s) to
            use as baselines. Defaults to HEAD.
        num (int, optional): show experiments from the last num
            commits. Defaults to 1.
        param_deps (bool, optional): include only parameters that
            are stage dependencies. Defaults to False.
        force (bool, optional): force re-collection, bypassing
            experiment cache. Defaults to False.
        config (dict, optional): DVC project config. Defaults to None.

    Returns:
        List[Dict]: Each item contains info for an individual experiment.
    """
    ...

Import

from dvc.api import exp_save, exp_show

I/O Contract

exp_save Inputs

Name	Type	Required	Description
name	Optional[str]	No	Name for the experiment. If None, a default name is auto-generated (e.g., "urban-sign").
force	bool	No	If True, overwrite an existing experiment with the same name. Defaults to False.
include_untracked	Optional[list[str]]	No	List of untracked file paths to include in the experiment snapshot. Defaults to None.

exp_save Output

Name	Type	Description
(return value)	str	The Git revision (commit SHA) of the newly created experiment.

exp_show Inputs

Name	Type	Required	Description
repo	Optional[str]	No	Path or URL of the DVC repository. Defaults to the current project directory.
revs	Optional[Union[str, list[str]]]	No	Git revision(s) to use as baseline starting points. Defaults to HEAD.
num	int	No	Number of first-parent commits to include from each revision. Use a negative value for all commits. Defaults to 1.
param_deps	bool	No	If True, only include parameters that are stage dependencies. Defaults to False.
force	bool	No	If True, bypass the experiment cache and re-collect all data. Defaults to False.
config	Optional[dict]	No	DVC project configuration dictionary. Defaults to None.

exp_show Output

Name	Type	Description
(return value)	list[dict]	A list of dictionaries, each representing one experiment. Values are post-processed: rich.text.Text objects are converted to float or str, and falsy values are replaced with None.

Usage Examples

Saving an Experiment

from dvc.api import exp_save

# Save the current workspace as a named experiment
rev = exp_save(name="baseline-v1")
print(f"Experiment saved at revision: {rev}")

# Save with untracked files included
rev = exp_save(
    name="with-configs",
    include_untracked=["configs/train.yaml"],
)

# Overwrite an existing experiment
rev = exp_save(name="baseline-v1", force=True)

Showing Experiments

from dvc.api import exp_show

# Get all experiments from HEAD
experiments = exp_show()
for exp in experiments:
    print(exp)

# Get experiments from a specific branch
experiments = exp_show(revs="feature-branch")

# Get experiments from the last 5 commits
experiments = exp_show(num=5)

# Get experiments from a remote repository
experiments = exp_show(repo="https://github.com/myorg/myrepo")

Related Pages

Implements Principle

• Principle:Iterative_Dvc_Experiment_Tracking