Working with Hub Repositories

A model is a Git repository

Every model, dataset and Space on the Hub is a Git repository with large files stored through Git LFS or Hugging Face's own storage backend. A typical model repo contains config.json, tokenizer files, one or more weight files (preferably in the safetensors format), an optional generation_config.json, and a README.md model card. The card should tell you the intended use, training data, evaluation results, limitations and the licence; always read the licence before using a model in a product, because some open weights restrict commercial use. Because repos are versioned, any branch, tag or commit hash can be requested with the revision argument. Pinning a commit hash makes your project reproducible: if the author pushes new weights, your code keeps loading the exact files you tested. The huggingface_hub library offers lower-level helpers such as hf_hub_download for one file and snapshot_download for a whole repo, both using the same cache as transformers.

How files reach your code

Models and datasets follow the same path from a versioned repo to an object in your program.

Pinning revisions and fetching single files

Replace the placeholder with a real commit hash from the repo's "Files and versions" tab.

from huggingface_hub import hf_hub_download, snapshot_download
from transformers import AutoModelForSequenceClassification

model_id = "distilbert/distilbert-base-uncased-finetuned-sst-2-english"

# One file, from the cache if it is already there
config_path = hf_hub_download(repo_id=model_id, filename="config.json")
print(config_path)

# Only the files you need from the whole repo
local_dir = snapshot_download(repo_id=model_id,
                              allow_patterns=["*.json", "*.safetensors", "*.txt"])

# Reproducible loading: pin a branch, tag or commit hash
model = AutoModelForSequenceClassification.from_pretrained(
    model_id, revision="main"  # use a commit hash in production
)

Offline mode for exams and labs

Set HF_HUB_OFFLINE=1 to make the libraries use only the local cache and never touch the network. It is handy on machines with flaky internet and in CI, where an unexpected download should be an error rather than a silent delay.

Quick check: Why pin a model to a specific commit hash with `revision`?

• It makes the download faster
• So your code keeps loading exactly the weights you tested even if the repo is updated
• It is required for private models
• It converts the weights to safetensors