Implementation:Iterative Dvc Api Artifacts

Knowledge Sources	Iterative_Dvc
Domains	API, Artifact_Management
Last Updated	2026-02-10 10:00 GMT

Overview

Public API function for resolving a DVC artifact to its Git revision and file path, provided by the DVC library.

Description

The dvc/api/artifacts.py module (58 lines) exposes a single public function, artifacts_show, that looks up a named artifact in a DVC repository and returns its Git revision and repository-relative path. This function is part of DVC's public Python API and is the programmatic equivalent of the dvc artifacts show CLI command.

The function accepts an artifact name (which may include a directory prefix parsed by Artifacts.parse_path), an optional version or stage (which are mutually exclusive), and an optional repo URL or path. It opens the repository with subrepo support enabled, resolves the artifact's Git revision via _repo.artifacts.get_rev, switches to that revision, and then resolves the artifact's path within the repository using _repo.artifacts.get_path. The result is a dictionary with two keys: "rev" (the Git commit SHA) and "path" (the repository-relative POSIX path to the artifact file).

Usage

Use artifacts_show when you need to programmatically determine which Git revision and file path correspond to a specific artifact version or stage in a DVC model registry. This is particularly useful for building automation pipelines that fetch specific model versions, or for integrating DVC artifact resolution into custom deployment workflows.

Code Reference

Source Location

• Repository: DVC
• File: dvc/api/artifacts.py
• Lines: L1-58

Signature

def artifacts_show(
    name: str,
    version: Optional[str] = None,
    stage: Optional[str] = None,
    repo: Optional[str] = None,
) -> dict[str, str]:
    """
    Return path and Git revision for an artifact in a DVC project.

    Args:
        name (str): name of the artifact to open.
        version (str, optional): version of the artifact to open.
            Defaults to the latest version.
        stage (str, optional): name of the model registry stage.
        repo (str, optional): path or URL for the DVC repo.

    Returns:
        Dictionary of the form:
            {"rev": ..., "path": ...}

    Raises:
        dvc.exceptions.ArtifactNotFoundError: The specified artifact
            was not found in the repo.
        ValueError: If both version and stage are specified.
    """
    ...

Import

from dvc.api import artifacts_show

I/O Contract

Inputs

Name	Type	Required	Description
name	str	Yes	Name of the artifact to look up. May include a directory prefix (e.g., "subdir:model-name") that is parsed by Artifacts.parse_path.
version	Optional[str]	No	Specific version of the artifact to retrieve. Defaults to the latest version. Mutually exclusive with stage.
stage	Optional[str]	No	Model registry stage name (e.g., "prod", "staging"). Mutually exclusive with version.
repo	Optional[str]	No	Path or URL of the DVC repository. Defaults to the current working directory. Supports both local paths and remote Git URLs (HTTP/SSH).

Outputs

Name	Type	Description
(return value)	dict[str, str]	A dictionary with two keys: "rev" (the Git commit SHA for the artifact) and "path" (the repository-relative path to the artifact file).

Usage Examples

Basic Usage

from dvc.api import artifacts_show

# Look up the latest version of an artifact
result = artifacts_show("my-model")
print(result)
# {"rev": "abc1234...", "path": "models/my-model.pkl"}

# Look up a specific version
result = artifacts_show("my-model", version="v1.2.0")
print(result["rev"])   # Git commit SHA for version v1.2.0
print(result["path"])  # Path to the artifact file

# Look up by model registry stage
result = artifacts_show("my-model", stage="prod")

# Look up in a remote repository
result = artifacts_show(
    "my-model",
    repo="https://github.com/myorg/myrepo",
)

Related Pages

Implements Principle

• Principle:Iterative_Dvc_Artifact_Resolution