dvc.api.exp_show()

Description

Retrieves DVC experiments tracked in a repository. Without arguments, this function retrieves all experiments derived from the Git HEAD. This function provides programmatic access to experiment data, including parameters, metrics, and metadata, making it easy to analyze, compare, and report on experiments.

Signature

dvc.api.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]

Parameters

repo

str

default:"None"

Location of the DVC repository.

Defaults to the current project (found by walking up from current working directory)
Can be a URL or a file system path
Both HTTP and SSH protocols are supported for online Git repos

repo="https://github.com/iterative/example-get-started"
repo="git@server.com:user/project.git"
repo="/path/to/local/repo"

revs

Union[str, list[str]]

default:"None"

Git revision(s) to use as a reference point for listing experiments.

Defaults to None, which uses HEAD as the starting point
Can be a single string or a list of strings
Each revision can be a branch, tag, or commit SHA

revs="main"                      # Single revision
revs=["main", "development"]     # Multiple revisions
revs="v1.0.0"                    # Tag

num

int

default:"1"

Show experiments from the last num commits (first parents) starting from the revs baseline.

Give a negative value to include all first-parent commits (similar to git log -n)
Defaults to 1 (only experiments from the most recent commit)

num=1    # Only latest commit
num=5    # Last 5 commits
num=-1   # All commits

param_deps

bool

default:"False"

Include only parameters that are stage dependencies.

When True, filters to show only parameters explicitly listed as dependencies
When False, shows all parameters

param_deps=True  # Only dependency parameters

force

bool

default:"False"

Force re-collection of experiments instead of loading from cache.

DVC caches experiment data for performance
Use force=True to reload all experiment data and ignore cached results
Useful when you need the most up-to-date data

force=True  # Reload from source

config

dict

default:"None"

Config dictionary to be passed through to the DVC project.

config={"cache": {"dir": "/tmp/cache"}}

Returns

experiments

list[dict]

A list of dictionaries, where each dictionary contains information about an individual experiment.Each experiment dict includes:

Experiment: Name of the experiment
rev: Git revision/commit hash
Created: Timestamp when created
State: Experiment state (Queued, Running, Success, Failed)
metrics.*: All metrics (e.g., metrics.accuracy)
params.*: All parameters (e.g., params.train.lr)

[
    {
        "Experiment": "exp-random-forest",
        "rev": "abc123",
        "Created": "2024-03-04 10:30:45",
        "metrics.accuracy": 0.92,
        "params.train.lr": 0.001,
        "params.train.epochs": 10
    },
    {...}
]

Examples

Basic Usage - Show All Experiments

import dvc.api
import json

# Get all experiments from HEAD
experiments = dvc.api.exp_show()

for exp in experiments:
    print(f"Experiment: {exp.get('Experiment')}")
    print(f"  Accuracy: {exp.get('metrics.accuracy')}")
    print(f"  Learning Rate: {exp.get('params.train.lr')}")
    print()

Show Experiments from Multiple Commits

import dvc.api

# Show experiments from last 5 commits
experiments = dvc.api.exp_show(num=5)

print(f"Found {len(experiments)} experiments across 5 commits")

Show Experiments from Specific Branch

import dvc.api

# Get experiments from development branch
dev_experiments = dvc.api.exp_show(revs="development")

# Get experiments from main branch
main_experiments = dvc.api.exp_show(revs="main")

print(f"Development: {len(dev_experiments)} experiments")
print(f"Main: {len(main_experiments)} experiments")

Compare Experiment Metrics

import dvc.api
import pandas as pd

# Get all experiments
experiments = dvc.api.exp_show(num=-1)

# Extract key metrics
data = []
for exp in experiments:
    data.append({
        "name": exp.get("Experiment", "baseline"),
        "accuracy": exp.get("metrics.accuracy"),
        "f1_score": exp.get("metrics.f1_score"),
        "training_time": exp.get("metrics.training_time")
    })

df = pd.DataFrame(data)
print(df.sort_values("accuracy", ascending=False))
print(f"\nBest accuracy: {df['accuracy'].max():.4f}")

Find Best Performing Experiment

import dvc.api

experiments = dvc.api.exp_show()

# Find experiment with highest accuracy
best_exp = max(
    experiments,
    key=lambda x: x.get("metrics.accuracy", 0)
)

print(f"Best experiment: {best_exp['Experiment']}")
print(f"Accuracy: {best_exp['metrics.accuracy']:.4f}")
print(f"Parameters:")
for key, value in best_exp.items():
    if key.startswith("params."):
        print(f"  {key}: {value}")

Filter Experiments by Criteria

import dvc.api

experiments = dvc.api.exp_show()

# Filter experiments with accuracy > 0.90
high_accuracy = [
    exp for exp in experiments
    if exp.get("metrics.accuracy", 0) > 0.90
]

print(f"Found {len(high_accuracy)} high-performing experiments:")
for exp in high_accuracy:
    print(f"  {exp['Experiment']}: {exp['metrics.accuracy']:.4f}")

Analyze Parameter Impact

import dvc.api
import matplotlib.pyplot as plt

experiments = dvc.api.exp_show()

# Extract learning rate vs accuracy
lr_values = [exp.get("params.train.lr") for exp in experiments]
accuracy_values = [exp.get("metrics.accuracy") for exp in experiments]

# Filter out None values
data = [(lr, acc) for lr, acc in zip(lr_values, accuracy_values) if lr and acc]
lr_values, accuracy_values = zip(*data)

plt.scatter(lr_values, accuracy_values)
plt.xlabel("Learning Rate")
plt.ylabel("Accuracy")
plt.title("Learning Rate vs Accuracy")
plt.xscale("log")
plt.show()

Export Experiments to CSV

import dvc.api
import csv

experiments = dvc.api.exp_show(num=-1)

# Get all unique keys
all_keys = set()
for exp in experiments:
    all_keys.update(exp.keys())

# Write to CSV
with open("experiments.csv", "w", newline="") as f:
    writer = csv.DictWriter(f, fieldnames=sorted(all_keys))
    writer.writeheader()
    writer.writerows(experiments)

print(f"Exported {len(experiments)} experiments to experiments.csv")

Compare Across Multiple Branches

import dvc.api

branches = ["main", "feature-1", "feature-2"]
results = {}

for branch in branches:
    experiments = dvc.api.exp_show(revs=branch)
    
    if experiments:
        best = max(experiments, key=lambda x: x.get("metrics.accuracy", 0))
        results[branch] = {
            "best_exp": best.get("Experiment"),
            "accuracy": best.get("metrics.accuracy"),
            "count": len(experiments)
        }

for branch, data in results.items():
    print(f"\n{branch}:")
    print(f"  Best: {data['best_exp']}")
    print(f"  Accuracy: {data['accuracy']:.4f}")
    print(f"  Total experiments: {data['count']}")

Remote Repository Access

import dvc.api

# Get experiments from remote repository
experiments = dvc.api.exp_show(
    repo="https://github.com/iterative/example-get-started",
    num=-1
)

print(f"Found {len(experiments)} experiments in remote repo")

Force Refresh Cache

import dvc.api

# Get latest data, bypassing cache
experiments = dvc.api.exp_show(force=True)

print(f"Retrieved {len(experiments)} experiments (fresh data)")

Only Show Dependency Parameters

import dvc.api

# Show only parameters that are stage dependencies
experiments = dvc.api.exp_show(param_deps=True)

for exp in experiments:
    print(f"\nExperiment: {exp['Experiment']}")
    # Only dependency params will be included
    for key, value in exp.items():
        if key.startswith("params."):
            print(f"  {key}: {value}")

Build Leaderboard

import dvc.api
from tabulate import tabulate

experiments = dvc.api.exp_show(num=-1)

# Build leaderboard
leaderboard = []
for exp in experiments:
    leaderboard.append({
        "Experiment": exp.get("Experiment", "baseline"),
        "Accuracy": exp.get("metrics.accuracy", 0),
        "F1 Score": exp.get("metrics.f1_score", 0),
        "Learning Rate": exp.get("params.train.lr", "N/A")
    })

# Sort by accuracy
leaderboard.sort(key=lambda x: x["Accuracy"], reverse=True)

print(tabulate(leaderboard, headers="keys", tablefmt="grid"))

Use Cases

Experiment Tracking

Track and analyze all experiments in your project.

Model Selection

Find the best performing model based on metrics.

Hyperparameter Analysis

Understand the impact of different parameters.

Team Collaboration

Share and compare experiments across team members.

Return Value Structure

Each experiment dictionary contains:

Experiment metadata

{
    "Experiment": "exp-random-forest",
    "rev": "abc123def456",
    "Created": "2024-03-04 10:30:45",
    "State": "Success",
    ...
}

Metrics (prefixed with 'metrics.')

{
    "metrics.accuracy": 0.9249,
    "metrics.precision": 0.9156,
    "metrics.recall": 0.9342,
    "metrics.f1_score": 0.9248,
    ...
}

Parameters (prefixed with 'params.')

{
    "params.train.lr": 0.001,
    "params.train.epochs": 10,
    "params.train.batch_size": 32,
    "params.model.hidden_units": 128,
    ...
}

Nested parameters

Parameters are flattened with dot notation:

# params.yaml
train:
  lr: 0.001
  optimizer:
    type: adam
    beta1: 0.9

# In exp_show() output
{
    "params.train.lr": 0.001,
    "params.train.optimizer.type": "adam",
    "params.train.optimizer.beta1": 0.9
}

Best Practices

Use for model selection

Systematically find the best model:

import dvc.api

experiments = dvc.api.exp_show(num=-1)

# Multi-criteria selection
candidates = [
    exp for exp in experiments
    if exp.get("metrics.accuracy", 0) > 0.90
    and exp.get("metrics.training_time", float('inf')) < 300
]

best = max(candidates, key=lambda x: x["metrics.f1_score"])
print(f"Selected: {best['Experiment']}")

Track experiment progress

Monitor running experiments:

import dvc.api
import time

while True:
    experiments = dvc.api.exp_show(force=True)
    
    running = [e for e in experiments if e.get("State") == "Running"]
    queued = [e for e in experiments if e.get("State") == "Queued"]
    
    print(f"Running: {len(running)}, Queued: {len(queued)}")
    
    if not running and not queued:
        break
    
    time.sleep(60)  # Check every minute

Compare against baseline

Always maintain and compare against a baseline:

import dvc.api

experiments = dvc.api.exp_show()

# Find baseline (usually the commit without experiment name)
baseline = next((e for e in experiments if not e.get("Experiment")), None)

if baseline:
    for exp in experiments:
        if exp.get("Experiment"):
            acc_diff = exp.get("metrics.accuracy", 0) - baseline.get("metrics.accuracy", 0)
            print(f"{exp['Experiment']}: {acc_diff:+.4f} vs baseline")

Handle missing values

Experiments may have different metrics/parameters:

import dvc.api

experiments = dvc.api.exp_show()

for exp in experiments:
    # Safe access with .get()
    accuracy = exp.get("metrics.accuracy")
    if accuracy is not None:
        print(f"{exp.get('Experiment', 'baseline')}: {accuracy:.4f}")
    else:
        print(f"{exp.get('Experiment', 'baseline')}: No accuracy metric")

Integration Examples

Streamlit Dashboard

import dvc.api
import streamlit as st
import pandas as pd

st.title("DVC Experiments Dashboard")

# Load experiments
experiments = dvc.api.exp_show(num=-1)

# Convert to DataFrame
df = pd.DataFrame(experiments)

# Display metrics
st.dataframe(df)

# Plot accuracy over time
if "metrics.accuracy" in df.columns:
    st.line_chart(df["metrics.accuracy"])

MLflow Integration

import dvc.api
import mlflow

experiments = dvc.api.exp_show()

for exp in experiments:
    with mlflow.start_run(run_name=exp.get("Experiment")):
        # Log metrics
        for key, value in exp.items():
            if key.startswith("metrics.") and isinstance(value, (int, float)):
                mlflow.log_metric(key.replace("metrics.", ""), value)
        
        # Log parameters
        for key, value in exp.items():
            if key.startswith("params."):
                mlflow.log_param(key.replace("params.", ""), value)

params_show()

Show parameters only

metrics_show()

Show metrics only

exp_save()

Create new experiments

Overview

Data Access

Metadata

SCM

Filesystem

dvc.api.exp_show()

Description

Signature

Parameters

Returns

Examples

Basic Usage - Show All Experiments

Show Experiments from Multiple Commits

Show Experiments from Specific Branch

Compare Experiment Metrics

Find Best Performing Experiment

Filter Experiments by Criteria

Analyze Parameter Impact

Export Experiments to CSV

Compare Across Multiple Branches

Remote Repository Access

Force Refresh Cache

Only Show Dependency Parameters

Build Leaderboard

Use Cases

Experiment Tracking

Model Selection

Hyperparameter Analysis

Team Collaboration

Return Value Structure

Best Practices

Integration Examples

Streamlit Dashboard

MLflow Integration

params_show()

metrics_show()

exp_save()

Build docs developers (and LLMs) love

Overview

Data Access

Metadata

SCM

Filesystem

Documentation Index

​Description

​Signature

​Parameters

​Returns

​Examples

​Basic Usage - Show All Experiments

​Show Experiments from Multiple Commits

​Show Experiments from Specific Branch

​Compare Experiment Metrics

​Find Best Performing Experiment

​Filter Experiments by Criteria

​Analyze Parameter Impact

​Export Experiments to CSV

​Compare Across Multiple Branches

​Remote Repository Access

​Force Refresh Cache

​Only Show Dependency Parameters

​Build Leaderboard

​Use Cases

Experiment Tracking

Model Selection

Hyperparameter Analysis

Team Collaboration

​Return Value Structure

​Best Practices

​Integration Examples

​Streamlit Dashboard

​MLflow Integration

​Related Functions

params_show()

metrics_show()

exp_save()

Build docs developers (and LLMs) love

Description

Signature

Parameters

Returns

Examples

Basic Usage - Show All Experiments

Show Experiments from Multiple Commits

Show Experiments from Specific Branch

Compare Experiment Metrics

Find Best Performing Experiment

Filter Experiments by Criteria

Analyze Parameter Impact

Export Experiments to CSV

Compare Across Multiple Branches

Remote Repository Access

Force Refresh Cache

Only Show Dependency Parameters

Build Leaderboard

Use Cases

Return Value Structure

Best Practices

Integration Examples

Streamlit Dashboard

MLflow Integration

Related Functions