Downloading

download_artifact resolves a version, then streams every managed file into a destination directory in parallel, recreating each file at its in-artifact path. It returns the list of local paths written, in manifest order.

metrana.download_artifact(
    type,
    name,
    *,
    dest,                 # destination directory
    alias=None,           # resolve by alias …
    version_index=None,   # … or by numeric index (mutually exclusive)
    workspace=None,       # defaults to the active run's workspace
    storage=None,         # "s3://…" to also fetch reference files from your bucket
    api_key=None,
    base_url=None,
    concurrency=None,
) -> list[Path]

Choosing a version

By default — with neither alias nor version_index — the download resolves the latest alias. Supply exactly one of alias or version_index to pick a specific version:

# Latest committed version (default).
metrana.download_artifact("model", "llm", dest="./m")

# A specific immutable version by index.
metrana.download_artifact("model", "llm", dest="./m", version_index=3)

# Whatever a user alias currently points at.
metrana.download_artifact("model", "llm", dest="./m", alias="production")

Passing both alias and version_index raises MetranaArtifactValidationError.

Where files land

Each file is written at dest / <its in-artifact path>, so a version uploaded from a directory comes back with its layout intact:

./restored/weights.bin

# version contains "weights.bin" and "sub/config.json"
paths = metrana.download_artifact("model", "llm", dest="./restored")
# ./restored/sub/config.json

The directory is created as needed. Downloads are verified end-to-end — each file’s size and SHA-256 are checked against the manifest, and a transfer that can’t be verified after retries raises MetranaArtifactTransferError rather than leaving a corrupt file in place. In-artifact paths are also constrained to stay inside dest, so a manifest can never write outside the destination.

Fetching reference files from your bucket

Reference files — bytes that live in a bucket you own, whether catalogued with references= or uploaded with storage= — are not served by Metrana, which never holds their bytes. To fetch them, opt in by passing storage="s3://…", and download_artifact retrieves each one directly from its bucket using the AWS credentials in your environment:

metrana.download_artifact(
    "model", "llm", dest="./m", storage="s3://acme-artifacts/metrana",
)

This needs the s3 extra — pip install 'metrana[s3]' (see Installation) — and standard AWS credentials, exactly like the upload side. Managed files always download regardless.

Without storage=, reference files are skipped with a warning; you can still fetch them yourself from the storage_uri reported by list_artifact_files.

Look before you fetch

To inspect a version’s contents — sizes, digests, which entries are references — without downloading, use list_artifact_files:

for f in metrana.list_artifact_files("model", "llm", alias="production"):
    kind = "reference" if f.is_reference else "managed"
    print(f"{f.path}  {f.size} bytes  ({kind})")

Tuning throughput

concurrency caps simultaneous downloads (default 16). Raise it to saturate a fast link:

metrana.download_artifact("dataset", "corpus", dest="./data", concurrency=32)

See Configuration for api_key, base_url, and workspace resolution.