Skip to main content
Source: dvc/api/experiments.py:62-120

​
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="[email protected]: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": "exp-random-forest",
    "rev": "abc123def456",
    "Created": "2024-03-04 10:30:45",
    "State": "Success",
    ...
}

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

{
    "params.train.lr": 0.001,
    "params.train.epochs": 10,
    "params.train.batch_size": 32,
    "params.model.hidden_units": 128,
    ...
}
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

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']}")
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
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")
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

Build docs developers (and LLMs) love

Get started for freeTalk to us