TopolearnEvery from_pretrained call goes through the Hub; knowing how it resolves files avoids broken deploys and security mistakes.
A checkpoint on the Hub is a Git repository identified as owner/name, e.g. Qwen/Qwen2.5-0.5B-Instruct. It typically contains config.json (architecture hyperparameters), weights in model.safetensors (sharded for large models, with an index file), tokenizer files, a generation_config.json and a model card describing intended use, license and limitations.
from_pretrained("owner/name") downloads the files to the local cache (~/.cache/huggingface/hub, configurable with HF_HOME) and reuses them afterwards. Practical knobs:
revision="a1b2c3d"pins a commit, branch or tag. Pin in production so an upstream push cannot change your model.token=orhf auth logingives access to gated or private repos; accept the license on the model page first.HF_HUB_OFFLINE=1forces cache-only loading on air-gapped machines.- A local directory path works anywhere a repo id does.
safetensors is the default weight format: it loads fast via memory mapping and cannot execute code, unlike pickled .bin files.
trust_remote_code=True lets a repo run its own Python modeling code on your machine. Only enable it for repos you trust, and pin the revision when you do. Most popular architectures are built into Transformers and need no remote code.
Check the license and model card before using a model commercially; open weights does not always mean unrestricted use.
Example
from huggingface_hub import list_repo_files, snapshot_download
from transformers import AutoConfig
repo = "Qwen/Qwen2.5-0.5B-Instruct"
print(list_repo_files(repo)[:5])
# ['.gitattributes', 'LICENSE', 'README.md', 'config.json', ...]
config = AutoConfig.from_pretrained(repo) # downloads only config.json
print(config.model_type, config.num_hidden_layers) # qwen2 24
# pin a revision for reproducibility (a branch, tag or commit hash)
config = AutoConfig.from_pretrained(repo, revision="main")
# download a whole repo once, then load from the local path
path = snapshot_download(repo, allow_patterns=["*.json", "*.safetensors"])
print(path) # ~/.cache/huggingface/hub/models--Qwen--Qwen2.5-0.5B-Instruct/...Remember
- Checkpoints are Hub repos with config, safetensors weights and tokenizer files
- Pin
revisionin production; files are cached under HF_HOME - Only use
trust_remote_code=Truefor trusted, pinned repos
Watch out for
- Loading a model with trust_remote_code=True from an unknown repo, which runs arbitrary code on your machine.