Implementation:Iterative Dvc Api Show

Knowledge Sources	Iterative_Dvc DVC Python API
Domains	Metrics, Parameters, API
Last Updated	2026-02-10 10:00 GMT

Overview

Concrete tool for retrieving metrics and parameters from DVC projects programmatically via the DVC Python API.

Description

The dvc.api.show module provides two public functions (metrics_show and params_show) for retrieving metrics and parameters from DVC projects without requiring CLI invocation. metrics_show collects and returns all metrics recorded in the project, while params_show retrieves parameter values used across pipeline stages. Both functions support querying specific Git revisions and applying configuration overrides, making them suitable for use in experiment tracking dashboards, CI/CD pipelines, and custom analysis scripts.

Usage

Import these functions when building Python applications that need to programmatically access DVC metrics or parameters. Use metrics_show to retrieve recorded experiment metrics (e.g., accuracy, loss) and params_show to retrieve hyperparameters and configuration values used in pipeline stages.

Code Reference

Source Location

• Repository: Iterative_Dvc
• File: dvc/api/show.py
• Lines: 1-404

Signature

def metrics_show(
    *targets: str,
    repo: Optional[str] = None,
    rev: Optional[str] = None,
    config: Optional[dict[str, Any]] = None,
) -> dict:
    """Returns a dictionary containing the metrics values from the DVC project.

    Collects and deserializes all metrics files tracked by DVC,
    returning their contents as a nested dictionary keyed by file path.
    """

def params_show(
    *targets: str,
    repo: Optional[str] = None,
    rev: Optional[str] = None,
    stages: Optional[str] = None,
    deps: bool = False,
    config: Optional[dict[str, Any]] = None,
) -> dict:
    """Returns a dictionary containing the parameters from the DVC project.

    Retrieves parameter values used by pipeline stages, optionally
    filtering by specific targets or stages.
    """

Import

from dvc.api import metrics_show, params_show

I/O Contract

Inputs

Name	Type	Required	Description
targets	str (variadic)	No	Specific metrics or params files to retrieve; if omitted, all are returned
repo	Optional[str]	No	URL or local path to the DVC repository
rev	Optional[str]	No	Git revision (branch, tag, commit SHA)
stages	Optional[str]	No	(params_show only) Specific pipeline stage to query parameters for
deps	bool	No	(params_show only) Whether to include parameters from stage dependencies
config	Optional[dict]	No	DVC configuration overrides

Outputs

Name	Type	Description
metrics_show returns	dict	Nested dictionary of metrics keyed by file path, e.g. {"metrics.json": {"accuracy": 0.95, "loss": 0.05}}
params_show returns	dict	Nested dictionary of parameters keyed by file path, e.g. {"params.yaml": {"lr": 0.001, "epochs": 10}}

Usage Examples

Retrieve Metrics

import dvc.api

# Get all metrics from the current project
metrics = dvc.api.metrics_show()
print(metrics)
# {"metrics.json": {"accuracy": 0.95, "f1": 0.92}}

# Get metrics from a specific revision
metrics_v1 = dvc.api.metrics_show(rev="v1.0")
print(metrics_v1["metrics.json"]["accuracy"])

Retrieve Parameters

import dvc.api

# Get all parameters from the current project
params = dvc.api.params_show()
print(params)
# {"params.yaml": {"lr": 0.001, "epochs": 50, "batch_size": 64}}

# Get parameters for a specific stage
train_params = dvc.api.params_show(stages="train")
print(train_params)

Compare Metrics Across Revisions

import dvc.api

# Compare metrics between two revisions
metrics_v1 = dvc.api.metrics_show(rev="v1.0")
metrics_v2 = dvc.api.metrics_show(rev="v2.0")

acc_v1 = metrics_v1["metrics.json"]["accuracy"]
acc_v2 = metrics_v2["metrics.json"]["accuracy"]
print(f"Accuracy improved from {acc_v1} to {acc_v2}")

Retrieve Params from a Remote Repository

import dvc.api

# Get parameters from a remote repository
params = dvc.api.params_show(
    repo="https://github.com/example/project",
    rev="experiment-branch",
)
print(params["params.yaml"]["learning_rate"])

Related Pages

• Environment:Iterative_Dvc_Python_Runtime