Skip to main content
Source: dvc/api/artifacts.py:7-58

​
Description

Returns the path and Git revision for an artifact in a DVC project. Artifacts are managed through the DVC model registry and can have versions or be assigned to stages (like staging, production). The resulting path and revision can be used in conjunction with other dvc.api calls (like open() or read()) to access and work with the artifact.

​
Signature

dvc.api.artifacts_show(
    name: str,
    version: Optional[str] = None,
    stage: Optional[str] = None,
    repo: Optional[str] = None,
) -> dict[str, str]

​
Parameters

​
name
str
required
Name of the artifact to look up.The artifact name is defined in the model registry and typically corresponds to a model or dataset.
name="my-model"
name="classifier-v2"
name="production-model"
​
version
str
default:"None"
Version of the artifact to retrieve. Defaults to the latest version if not specified.Mutually exclusive with stage - you can specify either version or stage, not both.
version="v1"
version="v2.0.1"
version="1"
​
stage
str
default:"None"
Name of the model registry stage.Common stages include “staging”, “production”, “dev”, etc.Mutually exclusive with version - you can specify either version or stage, not both.
stage="production"
stage="staging"
stage="dev"
​
repo
str
default:"None"
Path or URL for the DVC repository.
  • Defaults to the current project
  • Can be a local path or remote URL
  • Both HTTP and SSH protocols are supported
repo="https://github.com/user/ml-project"
repo="/path/to/local/repo"
repo="[email protected]:company/models.git"

​
Returns

​
artifact_info
dict[str, str]
A dictionary containing the artifact’s Git revision and file path:
{
    "rev": "abc123def456...",  # Git commit hash
    "path": "models/classifier.pkl"  # Relative path to artifact
}
  • rev: The Git revision (commit hash) where the artifact is stored
  • path: The relative path to the artifact file within the repository

​
Raises

​
ArtifactNotFoundError
exception
Raised when the specified artifact was not found in the repository.
​
ValueError
exception
Raised when both version and stage are specified (they are mutually exclusive).

​
Examples

​
Get Latest Version of Artifact

import dvc.api

# Get the latest version
artifact = dvc.api.artifacts_show("my-classifier")

print(f"Revision: {artifact['rev']}")
print(f"Path: {artifact['path']}")
# Output:
# Revision: abc123def456...
# Path: models/classifier.pkl

​
Get Specific Version

import dvc.api

# Get a specific version
artifact_v1 = dvc.api.artifacts_show("my-classifier", version="v1")
artifact_v2 = dvc.api.artifacts_show("my-classifier", version="v2")

print(f"V1 path: {artifact_v1['path']}")
print(f"V2 path: {artifact_v2['path']}")

​
Get Artifact from Registry Stage

import dvc.api

# Get artifact assigned to production stage
prod_artifact = dvc.api.artifacts_show(
    "my-model",
    stage="production"
)

print(f"Production model at: {prod_artifact['path']}")
print(f"From revision: {prod_artifact['rev']}")

​
Load Artifact Using Returned Info

import dvc.api
import pickle

# Get artifact info
artifact = dvc.api.artifacts_show("my-model", stage="production")

# Use the info to read the artifact
model_data = dvc.api.read(
    artifact["path"],
    rev=artifact["rev"],
    mode="rb"
)

# Load the model
model = pickle.loads(model_data)
predictions = model.predict(X_test)

​
Open Artifact with Context Manager

import dvc.api
import pickle

# Get artifact location
artifact = dvc.api.artifacts_show("classifier", version="v3")

# Stream the artifact
with dvc.api.open(
    artifact["path"],
    rev=artifact["rev"],
    mode="rb"
) as f:
    model = pickle.load(f)
    
results = model.predict(test_data)

​
Compare Staging and Production

import dvc.api

# Get staging and production versions
staging = dvc.api.artifacts_show("my-model", stage="staging")
production = dvc.api.artifacts_show("my-model", stage="production")

print("Staging:")
print(f"  Rev: {staging['rev']}")
print(f"  Path: {staging['path']}")

print("\nProduction:")
print(f"  Rev: {production['rev']}")
print(f"  Path: {production['path']}")

if staging['rev'] != production['rev']:
    print("\nStaging and production are on different revisions")

​
Remote Repository Access

import dvc.api

# Get artifact from remote repository
artifact = dvc.api.artifacts_show(
    "shared-model",
    version="v2",
    repo="https://github.com/company/ml-models"
)

print(f"Remote artifact: {artifact['path']} @ {artifact['rev'][:7]}")

​
Handle Multiple Artifacts

import dvc.api

artifact_names = ["model-a", "model-b", "model-c"]
artifacts = {}

for name in artifact_names:
    try:
        artifact = dvc.api.artifacts_show(name, stage="production")
        artifacts[name] = artifact
        print(f"✓ {name}: {artifact['path']}")
    except Exception as e:
        print(f"✗ {name}: {e}")

print(f"\nFound {len(artifacts)} production artifacts")

​
Download Artifact to Local File

import dvc.api
import requests

# Get artifact info
artifact = dvc.api.artifacts_show("my-model", stage="production")

# Get the URL
url = dvc.api.get_url(
    artifact["path"],
    rev=artifact["rev"]
)

# Download if it's an HTTP URL
if url.startswith("http"):
    response = requests.get(url)
    with open("local_model.pkl", "wb") as f:
        f.write(response.content)
    print("Model downloaded to local_model.pkl")

​
Error Handling

import dvc.api
from dvc.exceptions import ArtifactNotFoundError

try:
    artifact = dvc.api.artifacts_show(
        "my-model",
        version="v5",
        repo="https://github.com/user/repo"
    )
    print(f"Found: {artifact['path']}")
except ArtifactNotFoundError:
    print("Artifact not found in registry")
except ValueError as e:
    print(f"Invalid parameters: {e}")
except Exception as e:
    print(f"Error: {e}")

​
List All Versions

import dvc.api

model_name = "classifier"
versions = ["v1", "v2", "v3", "v4"]

print(f"Versions of {model_name}:\n")

for version in versions:
    try:
        artifact = dvc.api.artifacts_show(model_name, version=version)
        print(f"{version}:")
        print(f"  Path: {artifact['path']}")
        print(f"  Rev: {artifact['rev'][:7]}")
    except ArtifactNotFoundError:
        print(f"{version}: Not found")

​
Validate Stage Assignment

import dvc.api

def get_production_model(name):
    """Get production model, with fallback to staging."""
    try:
        return dvc.api.artifacts_show(name, stage="production")
    except ArtifactNotFoundError:
        print(f"No production version, trying staging...")
        try:
            return dvc.api.artifacts_show(name, stage="staging")
        except ArtifactNotFoundError:
            raise ValueError(f"No production or staging version for {name}")

artifact = get_production_model("my-classifier")
print(f"Using: {artifact['path']}")

​
Use Cases

Model Deployment

Retrieve production models for deployment in inference services.

Version Management

Access specific versions of models from the registry.

Stage Promotion

Get artifacts from different stages (dev, staging, production).

Model Comparison

Compare different versions or stages of the same artifact.

​
Model Registry Integration

Artifacts are managed through the DVC model registry. Here’s how they work:
1

Register an artifact

dvc artifacts add my-model models/classifier.pkl
2

Create versions

# Version is created automatically
dvc artifacts add my-model models/classifier_v2.pkl
3

Assign to stage

dvc artifacts assign my-model --stage production --version v2
4

Access programmatically

artifact = dvc.api.artifacts_show("my-model", stage="production")

​
Version vs Stage

Use version when you need a specific version of an artifact:
# Get exact version
artifact = dvc.api.artifacts_show("model", version="v2.1.0")

# Good for:
# - Reproducibility
# - Testing specific versions
# - Rollback scenarios

​
Best Practices

In deployment pipelines, use stages rather than hardcoding versions:
# ✅ Good - Flexible, follows stage assignments
artifact = dvc.api.artifacts_show("model", stage="production")

# ❌ Bad - Hardcoded, requires code changes
artifact = dvc.api.artifacts_show("model", version="v2")
When you need exact reproducibility, use specific versions:
# For reproducing results from a paper
artifact = dvc.api.artifacts_show(
    "research-model",
    version="v1.0.0",  # Exact version from publication
    repo="https://github.com/lab/research-repo"
)
Use the returned info with other dvc.api functions:
# Get artifact location
artifact = dvc.api.artifacts_show("model", stage="production")

# Load the artifact
with dvc.api.open(artifact["path"], rev=artifact["rev"], mode="rb") as f:
    model = pickle.load(f)

# Or get the URL
url = dvc.api.get_url(artifact["path"], rev=artifact["rev"])
Always handle the case where an artifact might not exist:
from dvc.exceptions import ArtifactNotFoundError

try:
    artifact = dvc.api.artifacts_show("model", stage="production")
except ArtifactNotFoundError:
    # Fall back to staging or default
    print("No production model, using staging")
    artifact = dvc.api.artifacts_show("model", stage="staging")

​
Common Patterns

​
Deployment Script

import dvc.api
import pickle
import os

def deploy_model(model_name, stage="production"):
    """Deploy a model from the registry."""
    
    # Get artifact info
    artifact = dvc.api.artifacts_show(model_name, stage=stage)
    
    print(f"Deploying {model_name} from {stage} stage")
    print(f"  Revision: {artifact['rev'][:7]}")
    print(f"  Path: {artifact['path']}")
    
    # Load model
    model_data = dvc.api.read(
        artifact["path"],
        rev=artifact["rev"],
        mode="rb"
    )
    model = pickle.loads(model_data)
    
    # Save locally for serving
    os.makedirs("deployed_models", exist_ok=True)
    with open(f"deployed_models/{model_name}.pkl", "wb") as f:
        f.write(model_data)
    
    print(f"✓ Model deployed successfully")
    return model

# Deploy production model
model = deploy_model("my-classifier", stage="production")

​
Model Version Comparison

import dvc.api
import pickle

def compare_versions(model_name, v1, v2, test_data):
    """Compare two versions of a model."""
    
    results = {}
    
    for version in [v1, v2]:
        artifact = dvc.api.artifacts_show(model_name, version=version)
        
        with dvc.api.open(artifact["path"], rev=artifact["rev"], mode="rb") as f:
            model = pickle.load(f)
        
        predictions = model.predict(test_data)
        accuracy = calculate_accuracy(predictions, test_labels)
        
        results[version] = {
            "accuracy": accuracy,
            "path": artifact["path"],
            "rev": artifact["rev"]
        }
    
    return results

# Compare versions
comparison = compare_versions("classifier", "v1", "v2", X_test)
print(comparison)

read()

Read artifact contents

open()

Stream artifact data

get_url()

Get artifact storage URL
Learn More: See the DVC Model Registry documentation for details on managing artifacts.

Build docs developers (and LLMs) love

Get started for freeTalk to us