On this page
First determine whether the slow path is the Hub page, Xet chunks, or an old Git LFS download
When a Hugging Face model download is slow or interrupted, do not rush to clear the cache. Model cards and config.json use ordinary Hub requests, large weights usually download as Xet chunks, and older repositories may still use Git LFS. These three paths use different tools, logs, and recovery methods. Confirm the account and network with a small file first, then configure the Clash proxy, timeout, and cache directory.
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.
Download config.json first to separate access permission from network issues
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
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 are short requests, while Xet large-file downloads also access content-addressed and presigned storage URLs. A working page proves only that huggingface.co is reachable. If chunk downloads repeatedly retry, pin one node and inspect the failing domain, status code, and cache write errors.
If an automatic policy changes outbound routes mid-download, the presigned URL and concurrent connections may all fail. Put the relevant Hub/Xet requests in one fixed policy group, then restore automatic selection after the entire download finishes. Do not permanently cover temporary storage domains with an overly 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, confirm that Xet requests match it, then moderately increase HF_HUB_DOWNLOAD_TIMEOUT.
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.
Retry the same revision, reusing the Hub cache first, then decide whether to enable Xet chunk caching
The default Hub cache is ~/.cache/huggingface/hub, while related Xet files are stored in ~/.cache/huggingface/xet. Setting HF_HOME moves both.
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 the default Xet chunk cache size is 0, meaning it is disabled by default. Consider setting HF_XET_CHUNK_CACHE_SIZE_BYTES only if you frequently download the same content ranges and have enough disk space. For one slow download, pin the node and increase the download timeout first; do not delete completed blobs just to test 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.
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 statusIf the git xet command is unavailable, install git-xet using the official instructions for your platform. macOS can use Homebrew, while official Windows documentation provides a winget installation method. Older clients can still download through the LFS bridge, but for speed or large-file issues, upgrade the Hugging Face toolchain first.
Git 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.
After the download finishes, disconnect the network and confirm that the model is truly local
Even after the progress bar completes, the project may still contact the Hub while loading a tokenizer, configuration, or custom code. Finish with an offline test using the real project to confirm that every required file is in the local cache.
Delivery verification
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.