dvc.api.params_show()

Description

Retrieve parameters tracked in a DVC repository. Without arguments, this function retrieves all parameters from all tracked parameter files for the current working tree. Parameters are typically stored in YAML, JSON, TOML, or Python files and tracked in dvc.yaml. This function provides programmatic access to these parameters for analysis, comparison, or dynamic configuration.

Signature

dvc.api.params_show(
    *targets: str,
    repo: Optional[str] = None,
    stages: Optional[Union[str, Iterable[str]]] = None,
    rev: Optional[str] = None,
    deps: bool = False,
    config: Optional[dict] = None,
) -> dict

Parameters

*targets

str

default:"None"

Names of the parameter files to retrieve parameters from (positional arguments).

If no targets are provided, all parameter files tracked in dvc.yaml will be used
Targets don’t necessarily have to be defined in dvc.yaml
Can specify multiple files: params_show("params.yaml", "config.toml")

# Single target
params = dvc.api.params_show("params.yaml")

# Multiple targets
params = dvc.api.params_show("params.yaml", "config.json")

# No targets (all params)
params = dvc.api.params_show()

repo

str

default:"None"

Location of the DVC repository.

Defaults to the current project (found by walking up from the 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"

stages

Union[str, Iterable[str]]

default:"None"

Name or names of the stages to retrieve parameters from.

If None, all parameters from all stages will be retrieved
Can be a single string or an iterable of strings
If called from a different location than dvc.yaml, use: {relpath}:{stage}

stages="train"                          # Single stage
stages=["prepare", "train", "evaluate"] # Multiple stages
stages="subdir/dvc.yaml:train"          # Stage in subdirectory

rev

str

default:"None"

Name of the Git revision to retrieve parameters from.

Defaults to None (current working tree)
Can be a branch name, tag name, commit hash, or DVC experiment name
If repo is not a Git repo, this option is ignored

rev="main"
rev="v1.0.0"
rev="abc123"
rev="exp-tuned-hyperparams"

deps

bool

default:"False"

Whether to retrieve only parameters that are stage dependencies.

When True, only returns parameters explicitly listed as dependencies
When False, returns all parameters

# Get only dependency parameters
params = dvc.api.params_show(deps=True)

config

dict

default:"None"

Config dictionary to be passed through to the DVC project.

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

Returns

parameters

dict

A dictionary containing the parameters. The structure depends on the parameter files:

Single file: Returns the parameters directly
Multiple files with unique keys: Merges parameters from all files
Multiple files with conflicting keys: Prefixes keys with filename:key

# Example return value
{
    "prepare": {
        "split": 0.2,
        "seed": 20170428
    },
    "train": {
        "n_est": 50,
        "min_split": 0.01
    }
}

Examples

Basic Usage - All Parameters

import dvc.api
import json

# Get all parameters from current working tree
params = dvc.api.params_show()
print(json.dumps(params, indent=2))

{
  "prepare": {
    "split": 0.2,
    "seed": 20170428
  },
  "featurize": {
    "max_features": 200,
    "ngrams": 2
  },
  "train": {
    "seed": 20170428,
    "n_est": 50,
    "min_split": 0.01
  }
}

From Specific Git Revision

import dvc.api

# Get parameters from a branch
params_main = dvc.api.params_show(rev="main")
params_dev = dvc.api.params_show(rev="development")

print(f"Main branch learning rate: {params_main['train']['lr']}")
print(f"Dev branch learning rate: {params_dev['train']['lr']}")

Filter by Stages

import dvc.api

# Get parameters for a single stage
train_params = dvc.api.params_show(stages="train")
print(train_params)
# {"train": {"seed": 20170428, "n_est": 50, "min_split": 0.01}}

# Get parameters for multiple stages
params = dvc.api.params_show(stages=["prepare", "train"])
print(params)
# {"prepare": {...}, "train": {...}}

Specific Parameter Files

import dvc.api

# Get parameters from specific file
params = dvc.api.params_show("params.yaml")
print(params)

# Get parameters from multiple files
params = dvc.api.params_show(
    "configs/params_dev.yaml",
    "configs/params_prod.yaml"
)
print(params)

Remote Repository

import dvc.api

# Get parameters from remote repo
params = dvc.api.params_show(
    repo="https://github.com/iterative/example-get-started"
)
print(params)

Compare Parameters Across Branches

import dvc.api

branches = ["main", "experiment-1", "experiment-2"]
comparison = {}

for branch in branches:
    params = dvc.api.params_show(rev=branch)
    comparison[branch] = params.get("train", {})

print("Learning Rate Comparison:")
for branch, params in comparison.items():
    lr = params.get("lr", "N/A")
    print(f"  {branch}: {lr}")

Access Nested Parameters

import dvc.api

params = dvc.api.params_show()

# Access nested values
learning_rate = params["train"]["lr"]
epochs = params["train"]["epochs"]
batch_size = params["train"]["batch_size"]

print(f"Training with lr={learning_rate}, epochs={epochs}, batch={batch_size}")

Handle Multiple Files with Conflicts

import dvc.api

# When multiple files have the same parameter keys,
# they are prefixed with filename
params = dvc.api.params_show(
    "configs/params_dev.yaml",
    "configs/params_prod.yaml"
)

print(params)
# {
#   "configs/params_prod.yaml:lr": 0.001,
#   "configs/params_dev.yaml:lr": 0.01,
#   ...
# }

Load Parameters for Training

import dvc.api

# Load hyperparameters from DVC
params = dvc.api.params_show(stages="train")
train_config = params.get("train", {})

# Use in training script
model = create_model(
    learning_rate=train_config["lr"],
    epochs=train_config["epochs"],
    batch_size=train_config["batch_size"]
)

Get Only Dependency Parameters

import dvc.api

# Get only parameters that are stage dependencies
dep_params = dvc.api.params_show(deps=True)
print(dep_params)

Error Handling

import dvc.api

try:
    params = dvc.api.params_show(
        "params.yaml",
        repo="https://github.com/user/repo",
        rev="main"
    )
    print(params)
except FileNotFoundError:
    print("Parameters file not found")
except Exception as e:
    print(f"Error: {e}")

Use Cases

Hyperparameter Tracking

Track and compare hyperparameters across experiments and branches.

Dynamic Configuration

Load parameters programmatically in training and inference scripts.

Experiment Comparison

Compare parameter settings across different experiments.

Reproducibility

Retrieve exact parameters used in past experiments for reproduction.

Parameter File Formats

YAML
JSON
TOML
Python

# params.yaml
train:
  lr: 0.001
  epochs: 10
  batch_size: 32

model:
  hidden_units: 128
  dropout: 0.2

params = dvc.api.params_show("params.yaml")
print(params["train"]["lr"])  # 0.001

{
  "train": {
    "lr": 0.001,
    "epochs": 10
  }
}

params = dvc.api.params_show("params.json")
print(params["train"]["epochs"])  # 10

[train]
lr = 0.001
epochs = 10

[model]
hidden_units = 128

params = dvc.api.params_show("params.toml")
print(params["model"]["hidden_units"])  # 128

# params.py
LEARNING_RATE = 0.001
EPOCHS = 10

MODEL_CONFIG = {
    "hidden_units": 128,
    "dropout": 0.2
}

params = dvc.api.params_show("params.py")
print(params["LEARNING_RATE"])  # 0.001

Return Value Structure

Single parameter file

When retrieving parameters from a single file, the structure matches the file content:

params = dvc.api.params_show("params.yaml")
# {
#   "train": {"lr": 0.001, "epochs": 10},
#   "model": {"units": 128}
# }

Multiple files (unique keys)

When parameter keys are unique across files, they’re merged:

params = dvc.api.params_show("train_params.yaml", "model_params.yaml")
# {
#   "train": {"lr": 0.001},  # from train_params.yaml
#   "model": {"units": 128}   # from model_params.yaml
# }

Multiple files (conflicting keys)

When keys conflict, they’re prefixed with the filename:

params = dvc.api.params_show("dev_params.yaml", "prod_params.yaml")
# {
#   "dev_params.yaml:lr": 0.01,
#   "prod_params.yaml:lr": 0.001
# }

Stage filtering

When filtering by stages, only parameters used by those stages are returned:

params = dvc.api.params_show(stages="train")
# {
#   "train": {"lr": 0.001, "epochs": 10}
# }

Best Practices

Version control parameters

Store parameters in version control and track with DVC:

# params.yaml (in Git)
train:
  lr: 0.001
  epochs: 10

# dvc.yaml
stages:
  train:
    cmd: python train.py
    params:
      - params.yaml:train

Use for reproducibility

Retrieve exact parameters for reproducing results:

import dvc.api

# Get parameters from successful experiment
params = dvc.api.params_show(
    rev="exp-best-model",
    stages="train"
)

# Reproduce training with same parameters
train_model(**params["train"])

Compare across experiments

Build parameter comparison tools:

import dvc.api
import pandas as pd

experiments = ["exp-1", "exp-2", "exp-3"]
param_comparison = []

for exp in experiments:
    params = dvc.api.params_show(rev=exp)
    param_comparison.append({
        "experiment": exp,
        **params.get("train", {})
    })

df = pd.DataFrame(param_comparison)
print(df)

Handle missing parameters gracefully

Use .get() with defaults for robustness:

import dvc.api

params = dvc.api.params_show()

# Safe access with defaults
lr = params.get("train", {}).get("lr", 0.001)
epochs = params.get("train", {}).get("epochs", 10)

metrics_show()

Retrieve metrics values

exp_show()

Show experiments with params

read()

Read any tracked file

Overview

Data Access

Metadata

SCM

Filesystem

dvc.api.params_show()

Description

Signature

Parameters

Returns

Examples

Basic Usage - All Parameters

From Specific Git Revision

Filter by Stages

Specific Parameter Files

Remote Repository

Compare Parameters Across Branches

Access Nested Parameters

Handle Multiple Files with Conflicts

Load Parameters for Training

Get Only Dependency Parameters

Error Handling

Use Cases

Hyperparameter Tracking

Dynamic Configuration

Experiment Comparison

Reproducibility

Parameter File Formats

Return Value Structure

Best Practices

metrics_show()

exp_show()

read()

Build docs developers (and LLMs) love

Overview

Data Access

Metadata

SCM

Filesystem

​Description

​Signature

​Parameters

​Returns

​Examples

​Basic Usage - All Parameters

​From Specific Git Revision

​Filter by Stages

​Specific Parameter Files

​Remote Repository

​Compare Parameters Across Branches

​Access Nested Parameters

​Handle Multiple Files with Conflicts

​Load Parameters for Training

​Get Only Dependency Parameters

​Error Handling

​Use Cases

Hyperparameter Tracking

Dynamic Configuration

Experiment Comparison

Reproducibility

​Parameter File Formats

​Return Value Structure

​Best Practices

​Related Functions

metrics_show()

exp_show()

read()

Build docs developers (and LLMs) love

Description

Signature

Parameters

Returns

Examples

Basic Usage - All Parameters

From Specific Git Revision

Filter by Stages

Specific Parameter Files

Remote Repository

Compare Parameters Across Branches

Access Nested Parameters

Handle Multiple Files with Conflicts

Load Parameters for Training

Get Only Dependency Parameters

Error Handling

Use Cases

Parameter File Formats

Return Value Structure

Best Practices

Related Functions