dvc.api.params_show()

Retrieve parameters from DVC-tracked parameter files programmatically

Source: dvc/api/show.py:156-404

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="[e-mail]: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

# 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

JSON

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

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

TOML

[train]
lr = 0.001
epochs = 10

[model]
hidden_units = 128

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

Python

# 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)

Related Functions

metrics_show()

Retrieve metrics values

exp_show()

Show experiments with params

read()

Read any tracked file