On this page
A model page may load while downloading repeatedly retries as soon as the large files begin. Raising timeouts or clearing the cache may not help. Small files and weights can use different download methods, and account permission, the proxy route, and disk space need separate checks. Preserve completed files and investigate the tool you actually use to reduce unnecessary downloads from scratch.
How do small Hub files, Xet chunks and legacy Git LFS downloads differ?
Check ordinary Hub requests with a model card or config.json. Large weights are usually downloaded in Xet chunks, which divide a large file into smaller pieces for transfer. Identify your tool in the table below; legacy Git LFS has its own compatibility method. Preserve completed cache files while troubleshooting and use a small file to check account access and networking.
Current download method
| Method | Actual large-file backend | Best use case |
|---|---|---|
| huggingface_hub / hf CLI | huggingface_hub 0.32+ installs hf_xet automatically and uses Xet chunk downloads | Preferred for model and dataset downloads |
| git clone + git-xet | Xet, while retaining a Git workflow | When you need the complete repository and commit history |
| Old Git LFS client | Continues working through a compatibility bridge | Legacy workflow; not the current performance-first choice |
| Single file in the browser | Download address generated by the Hub | Viewing a small file or making a temporary download |
Official Hugging Face documentation states that the Hub now uses Xet. Git LFS remains compatible, but hf_transfer is deprecated in favor of hf_xet. Old tutorials that tell users only to install Git LFS and enable HF_HUB_ENABLE_HF_TRANSFER are no longer appropriate as the default approach in 2026.
Downloading config.json helps separate permission issues from basic network failures
python -m pip install -U huggingface_hub
hf auth login
hf download gpt2 config.json
# 查看版本
python -c "import huggingface_hub; print(huggingface_hub.__version__)"If a small file from a public model succeeds, Hub metadata, basic HTTPS, and the local cache directory are working. If a gated model returns 401/403, accept its license in the browser with the same account and verify the token has read permission. Switching nodes will not grant account approval.
The token is stored by hf auth login; do not put it in Clash YAML, a Notebook cell, or a public script. On team servers, use your own secrets management instead of copying a personal token.
Set environment variables before importing huggingface_hub
The following example changes HF_HOME. After signing in in the previous section, check which token source you are still using: the value of HF_TOKEN takes priority for authentication; HF_TOKEN_PATH can select another file location, while the default token file follows HF_HOME.
Select the proxy and cache directory before downloading a gated model. After changing the directory, run hf auth whoami to check the current account and log in again in that environment if needed. The public-model examples do not require login, and their success does not confirm access to a gated model.
CLASH_PORT=7890
export HTTPS_PROXY="http://127.0.0.1:$CLASH_PORT"
export HTTP_PROXY="http://127.0.0.1:$CLASH_PORT"
export HF_HOME="$HOME/hf-cache"
export HF_HUB_DOWNLOAD_TIMEOUT=30
mkdir -p "$HF_HOME"
hf download openai-community/gpt2 --include '*.json'
hf download openai-community/gpt2 --cache-dir "$HF_HOME/hub"Official documentation notes that huggingface_hub reads environment variables at import time. If you change variables after a Notebook has already imported the library, the current kernel may keep the old values. Restart the kernel or set them before startup. HF_HUB_DOWNLOAD_TIMEOUT defaults to 10 seconds and should be increased only when the connection succeeds but reads are slow.
HF_HOME affects both the token and cache root. To move only the repository cache, use HF_HUB_CACHE or the command's --cache-dir. The current user must be able to write to the directory, with enough space for temporary chunks, model revision data, and extraction.
If the page opens but model chunks time out, find Xet requests on the connections screen
Model cards and README files use short requests. Xet large-file downloads also access addresses that locate data by file content and storage addresses with temporary access authorization. A working web page only proves that huggingface.co is reachable. If retries continue once chunk downloads begin, select one node and keep it selected, then check failed domains, status codes, and cache write errors.
Compare related Hub/Xet requests on one fixed node to rule out reachability differences between outbound routes, then restore automatic selection after the download. A route change alone does not prove that a presigned URL is invalid; inspect the status code and authorization details. Do not permanently cover temporary storage domains with a broad DOMAIN-KEYWORD rule.
401 / 403
Check repository access and the token; do not increase the timeout.
httpx.TimeoutException / Read timed out
Pin a node and confirm where the failed request routes. Adjust HF_HUB_DOWNLOAD_TIMEOUT for slow Hub file reads; investigate Xet chunk errors through hf_xet logs rather than assuming one variable controls every download.
No space left on device
Move HF_HOME/HF_HUB_CACHE while retaining completed cache data, and do not switch nodes.
Permission denied while writing the cache
Fix directory ownership and mount permissions; do not redownload the entire model as root.
Only a pointer file of a few KB was downloaded
The Git workflow is missing git-xet/git-lfs, or the large-file checkout did not finish.
Reuse completed Hub files; the chunk-cache variable has no effect
The default Hub cache is ~/.cache/huggingface/hub, with Xet-related data in ~/.cache/huggingface/xet. Changing HF_HOME changes the paths used from then on; it does not move existing files automatically. Preserve completed files in the original directory before deciding which cache to move or keep using.
Hub refs, blobs, and snapshots reuse files that have already completed. After an interrupted download, rerun it with the same repo_id, revision, user, and cache directory.
Current official documentation says HF_XET_CHUNK_CACHE_SIZE_BYTES has no effect: hf_xet no longer uses a local download chunk cache, and the variable cannot enable one. Reuse completed Hub files and check requests and disk space. Do not delete blobs or redownload the model to “enable chunk caching.”
from pathlib import Path
from huggingface_hub import snapshot_download
cache_dir = Path.home() / "hf-cache" / "hub"
path = snapshot_download(
repo_id="openai-community/gpt2",
revision="main",
cache_dir=cache_dir,
)
print(path)If you must use Git, install git-xet and retain LFS compatibility
Use this path only when the project genuinely depends on Git history or branch operations. For ordinary model downloads, prefer hf download; resumable downloads and cache behavior are easier to observe.
If git xet is unavailable, install git-xet using the official instructions for your platform. macOS can use Homebrew, and the official Windows documentation provides a winget installation method. Older clients can still download through LFS bridge, but for speed or large-file problems, update the relevant Hugging Face download tools first.
HF_REPO='OWNER/MODEL'
# 例如 HF_REPO='openai-community/gpt2'
git lfs install
git xet install
git clone "https://huggingface.co/$HF_REPO"
cd "${HF_REPO##*/}"
git xet --version
git lfs version
git statusGit uses git config and environment variables, which are separate from the Python SDK configuration. If the hf CLI works but git clone stalls, inspect only Git/Xet/LFS and the Git proxy; do not change HF_HOME again.
Enable offline mode and confirm model weights and the tokenizer load locally
Check the download and offline use
Run the same download command again
It should quickly use the same snapshot instead of retransferring every chunk.
Load the model once
Use the actual transformers or project code to read the weights and tokenizer.
Test in offline mode
When cached content is available, set HF_HUB_OFFLINE=1 or use local_files_only; it should not access the Hub again.
Check credentials and disk space
Notebook files, logs, and Git history contain no token, and the cache volume still has room for upgrades.
Record the revision and snapshot path
This lets you distinguish a new model version from corrupted old cache during the next update.