Pulling models & images

Public repos pull anonymously. Private repos need a login — see Push for the one-shot provisioning step that also writes the credentials hippius-hub uses on pull.

---

Pull a single file

Python (huggingface_hub)

from hippius_hub import hf_hub_download

path = hf_hub_download(
    repo_id="my-models/qwen-7b",
    filename="config.json",
    revision="v1",
)
print(path)  # ~/.cache/hippius/hub/models--my-models--qwen-7b/snapshots/v1/config.json

Drop-in for hf_hub_download — the cache layout matches huggingface_hub exactly, so transformers / diffusers reading from the same directory Just Works.

CLI (hippius-hub)

# Single file — uses the parallel Rust downloader
hippius-hub download my-models/qwen-7b model.safetensors --revision v1

# Verify the SHA256 of the bytes after download
hippius-hub download my-models/qwen-7b model.safetensors --verify-hash

Optional flags: --revision <tag>, --chunk-size <bytes> (defaults to HIPPIUS_CHUNK_SIZE), --cache-dir <path>.

Docker

# Pull by tag
docker pull registry.hippius.com/my-models/my-app:v1

# Pull by digest (immutable)
docker pull registry.hippius.com/my-models/my-app@sha256:0c1a…

Public images pull without docker login. The same reference works anywhere an image is accepted (Dockerfile, docker-compose.yml, Kubernetes pod specs).

ORAS

oras pull registry.hippius.com/my-models/my-artifact:v1

oras pulls arbitrary OCI artifacts — model weights, datasets, anything you previously pushed with oras push. The Model Registry stores model files this way under the hood.

---

Pull a whole repo

Python (huggingface_hub)

from hippius_hub import snapshot_download

local_dir = snapshot_download(
    repo_id="my-models/qwen-7b",
    revision="v1",
    allow_patterns=["*.safetensors", "*.json"],
    ignore_patterns="optimizer*",
    max_workers=8,
)

Drop-in for snapshot_download. For whole-repo pulls this is the recommended path — it parallelizes across files and lays bytes out in the HF cache shape that transformers.from_pretrained(...) reads from.

CLI (hippius-hub)

The CLI's download command pulls one file at a time. For pulling every file in a revision, prefer snapshot_download from Python — it parallelizes across files and matches the HF cache layout.

If you really want shell only, loop over the filenames from hippius-hub models show <repo> <revision> --json.

Docker

A Docker image is one manifest — docker pull <image>:<tag> already pulls every layer it references. There's no separate "whole repo" command.

---

Tag vs digest

Tags (:v1, :main) are mutable — re-pushing to the same revision moves the tag onto a new manifest. Digests (@sha256:…) are immutable — the same bytes forever.

• Pin to a digest for CI/CD, Kubernetes manifests, and anywhere reproducibility matters.
• Use a tag for interactive development and the "give me the latest" case.

hippius-hub models show <repo> prints every tag and digest indexed for a repo.

---

Tuning parallel downloads

The Rust downloader ships in the wheel — no compile step needed. Two knobs are worth knowing:

Env var	Default	What it does
HIPPIUS_CHUNK_SIZE	104857600 (100 MiB)	Per-chunk size for the parallel Rust downloader. Smaller = more parallel requests, larger = fewer/bigger requests.
HIPPIUS_VERIFY_HASH	unset (off)	Set to 1/true to SHA256-verify every download against the registry's recorded digest.

For snapshot_download, max_workers=8 (the default) parallelizes across files. Bump it higher on fat connections.

---

Where to next

• Push — upload your own models or container images.
• CLI reference — every hippius-hub command, grouped by goal.