How do you pin Hugging Face models the way a lockfile pins packages?

Hugging Face has no lockfile for models, but you can get the same effect by passing a full-length commit hash as the revision argument and recording it in your repository. A branch like main or a tag can move; a commit hash identifies one exact snapshot of the files.

What does a lockfile actually do?

A lockfile freezes a resolution. Your package manager records exact versions and hashes so that tomorrow's build installs what yesterday's build installed. The point is repeatability and a reviewable diff when something changes.

Model downloads without a revision do the opposite. from_pretrained("org/model") fetches whatever the default branch points to now. If the publisher updates weights, or someone gains write access and swaps them, your next job silently loads different files.

How do revisions work on the Hub?

Hugging Face's download documentation lists what revision accepts: a tag such as v1.0, a branch name, a pull request ref like refs/pr/3, or a specific commit hash. It also notes that a commit hash must be the full-length hash, not the seven character short form.

Of those, only the commit hash is immutable in practice. Tags and branches are names that can be repointed, and a pull request ref points at unreviewed content from a contributor.

What does a pinned load look like?

A constructed example, a config file kept in version control:

models:
  sentiment-classifier:
    repo_id: example-org/sentiment-base
    revision: 0123456789abcdef0123456789abcdef01234567
    format: safetensors
    reviewed_by: j.rao
    reviewed_on: 2026-10-12

and in code you read that entry and pass revision= to the download or from_pretrained call. The hash above is a placeholder pattern, you record the real one you reviewed.

A pull request that changes the hash is now a code review event. The reviewer asks what changed in the model repository between the two commits, and who made the change.

How does the local cache fit in?

The Hub library caches by revision. Its cache documentation describes a snapshots folder with one directory per known revision, each holding symlinks to content stored as blobs. The default location is ~/.cache/huggingface/hub, and can be changed with HF_HOME or HF_HUB_CACHE.

Two practical uses. In CI, set the cache directory to a known path so you can see which revisions were fetched. In production, bake the pinned snapshot into the image or a volume at build time, and run with offline mode so the running service cannot fetch anything new.

What lockfiles also give you that a hash does not

A hash pins one repository. Real lockfiles also pin transitive dependencies. Models often have companions: tokenizers, adapters, remote code, datasets. Pin each one separately, and list them together in the same file so one review covers the set. Pay particular attention to anything that executes code at load time.

What to do

1. Create a models manifest in your repository with repo, full commit hash and weight format.
2. Pass the hash as revision everywhere you download or load.
3. Review any hash change like a dependency bump, including the diff of files in the model repository.
4. Prefer safetensors, and record the format so a switch back to pickle is visible.
5. Pre fetch pinned snapshots at build time and run services offline.
6. Pin tokenizers, adapters and datasets the same way.
7. Add a CI check that fails on a from_pretrained call without a revision.

Safeguard's dependency scanning and policies cover the Python packages around your model code, so the model manifest and the package lockfile can be reviewed in one pull request flow.

Quick check

Sources

• Download files from the Hub, Hugging Face docs, fetched 18 October 2026
• Understand caching, Hugging Face docs, fetched 18 October 2026
• Pickle scanning, Hugging Face Hub docs, fetched 18 October 2026

Last reviewed: 18 October 2026.