Implementation:Iterative Dvc Experiments Show

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

Overview

Concrete tool for collecting experiment data and presenting it in structured tabular format for comparison and analysis, provided by the DVC library.

Description

The dvc.repo.experiments.show module provides two primary functions: show and tabulate. The show function collects experiment states from the repository, returning a list of ExpState objects that contain metrics, parameters, dependency hashes, timestamps, and experiment metadata for each revision. The tabulate function transforms these states into a TabularData object -- a column-oriented data structure defined in dvc.compare -- suitable for rendering as terminal tables, markdown, or CSV.

The show function delegates to the collect module, which traverses Git revisions, branches, tags, and the experiment ref namespace to gather experiment data. It supports filtering via flags like hide_queued, hide_failed, and hide_workspace, and revision selection via all_branches, all_tags, and all_commits.

The tabulate function handles the full column resolution pipeline: collecting all metric and parameter names across experiments, disambiguating names that appear in multiple files, building row data for each experiment (including baseline and derived experiments), and optionally sorting by a specified metric or parameter column. The resulting TabularData object supports operations like column dropping, projection, CSV export, and rich terminal rendering.

Usage

Import and use these functions when:

• You need to programmatically retrieve experiment metrics and parameters for analysis
• You want to build custom experiment comparison views or dashboards
• You need to export experiment results to CSV or other formats
• You are building automation that selects the best experiment based on metric values

Code Reference

Source Location

• Repository: DVC
• File: dvc/repo/experiments/show.py
• Lines: L24-49 (show), L52-109 (tabulate)
• Related: dvc/compare.py L28-274 (TabularData)

Signature

def show(
    repo: "Repo",
    revs: Union[list[str], str, None] = None,
    all_branches: bool = False,
    all_tags: bool = False,
    all_commits: bool = False,
    num: int = 1,
    hide_queued: bool = False,
    hide_failed: bool = False,
    hide_workspace: bool = False,
    sha_only: bool = False,
    **kwargs,
) -> list["ExpState"]:
    ...

def tabulate(
    baseline_states: Iterable["ExpState"],
    fill_value: Optional[str] = "-",
    error_value: str = "!",
    **kwargs,
) -> tuple["TabularData", dict[str, Iterable[str]]]:
    ...

Import

from dvc.repo.experiments.show import show, tabulate

I/O Contract

Inputs

show:

Name	Type	Required	Description
repo	Repo	Yes	The DVC repository instance.
revs	Union[list[str], str, None]	No	Specific Git revisions to show experiments for. If None, shows experiments for the current HEAD.
all_branches	bool	No	If True, includes experiments from all branches. Defaults to False.
all_tags	bool	No	If True, includes experiments from all tags. Defaults to False.
all_commits	bool	No	If True, includes experiments from all commits. Defaults to False.
num	int	No	Number of recent commits to include. Defaults to 1.
hide_queued	bool	No	If True, excludes queued experiments. Defaults to False.
hide_failed	bool	No	If True, excludes failed experiments. Defaults to False.
hide_workspace	bool	No	If True, excludes workspace experiments. Defaults to False.
sha_only	bool	No	If True, returns only SHA identifiers without resolving names. Defaults to False.

tabulate:

Name	Type	Required	Description
baseline_states	Iterable[ExpState]	Yes	List of experiment states as returned by show.
fill_value	Optional[str]	No	Value to use for missing data cells. Defaults to "-".
error_value	str	No	Value to display when a metric file has errors. Defaults to "!".
sort_by	Optional[str]	No	Column name to sort experiments by. Passed via kwargs.
sort_order	Optional[Literal["asc", "desc"]]	No	Sort direction. Passed via kwargs.
precision	Optional[int]	No	Number of significant digits for floating point values. Passed via kwargs.

Outputs

show:

Name	Type	Description
return	list[ExpState]	List of experiment states, each containing rev (revision SHA), name, data (with metrics, params, deps, timestamp), and experiments (list of child ExpRange objects representing derived experiments).

tabulate:

Name	Type	Description
return[0]	TabularData	Column-oriented table data with headers including Experiment, rev, typ, Created, parent, State, Executor, plus dynamically resolved metric, parameter, and dependency columns. Supports rendering, CSV export, filtering, and projection.
return[1]	dict[str, Iterable[str]]	Dictionary mapping data categories ("metrics", "params", "deps") to their respective column header names, enabling category-aware operations on the table.

Usage Examples

Basic Usage: Show All Experiments

from dvc.repo import Repo
from dvc.repo.experiments.show import show

with Repo() as repo:
    exp_states = show(repo)
    for state in exp_states:
        print(f"Baseline: {state.rev[:7]}")
        if state.experiments:
            for exp_range in state.experiments:
                for exp in exp_range.revs:
                    print(f"  Experiment: {exp.name} ({exp.rev[:7]})")

Tabulate and Render Experiments

from dvc.repo import Repo
from dvc.repo.experiments.show import show, tabulate

with Repo() as repo:
    exp_states = show(repo, all_branches=True)
    td, data_headers = tabulate(exp_states)

    # Render as terminal table
    td.render()

    # Export as CSV
    csv_output = td.to_csv()
    print(csv_output)

Sort Experiments by Metric

from dvc.repo import Repo
from dvc.repo.experiments.show import show, tabulate

with Repo() as repo:
    exp_states = show(repo)
    td, data_headers = tabulate(
        exp_states,
        sort_by="accuracy",
        sort_order="desc",
    )
    td.render()

Programmatic Access to Experiment Data

from dvc.repo import Repo
from dvc.repo.experiments.show import show, tabulate

with Repo() as repo:
    exp_states = show(repo)
    td, data_headers = tabulate(exp_states)

    # Access specific columns
    metric_columns = data_headers["metrics"]
    param_columns = data_headers["params"]

    # Convert to list of dicts for further analysis
    rows = td.as_dict()
    for row in rows:
        print(row)

Related Pages

Implements Principle

• Principle:Iterative_Dvc_Experiment_Comparison