Source: huggingface_hub guide: Download files from the Hub
The huggingface_hub client's download APIs: hf_hub_download, snapshot_download with patterns and revisions, the cache, hf CLI, dry-run and Xet-based transfers.
Contents
- What: library documentation (huggingface_hub v2.4.0 docs)
- Publisher: Hugging Face
- Date: accessed 2026-11-14
- Original: Download files from the Hub
Summary
This guide documents how Python code and the hf CLI fetch files from Hub repos into a version-aware local cache. It covers pinning to a revision, filtering which files to fetch, and the Xet storage backend that speeds up large transfers.
Key claims
hf_hub_downloadfetches one file into the cache and returns its path. Do not modify the returned file, because doing so corrupts the cache.revisionaccepts a branch, a tag, a PR ref (refs/pr/N) or a commit hash. A commit hash must be the full hash, not the 7-character short form.snapshot_downloadfetches a whole repo concurrently.allow_patternsandignore_patterns(fnmatch globs) skip unneeded files, for example.binweights when you only need safetensors.- The cache lives under
HF_HOME(by default~/.cache/huggingface/hub/models--org--name/snapshots/<commit>/).local_dirwrites a plain folder instead. hf downloadmirrors these APIs, acceptshf://URIs, and has a--dry-runmode that lists file sizes and cache status.hf_xet(installed by default since huggingface_hub 0.32.0) downloads content-addressed chunks with deduplication. It replaces the deprecatedhf_transfer.