Problem: Hugging Face model download hangs/times out in China — switch HF_ENDPOINT to hf-mirror, zero code changes —— Trove problem library

What you will run into

Running AI projects in China, transformers / huggingface-cli model downloads hang at Fetching xx files or spin forever, then time out (Could not connect to huggingface.co-style).

You retry again and again thinking it is bandwidth — but the problem is not bandwidth, it is that huggingface.co itself is unreachable from CN networks.

Why this happens

The official Hugging Face domain (huggingface.co) has no acceleration for CN networks; direct connections are dropped at the transport layer (measured 2026-09-01: curl https://huggingface.co/ times out at 8s, code=000).

The CN mirror hf-mirror.com is stable (same test: 200, 0.6s).

Key mechanism: every download entry point in huggingface_hub (hf_hub_download / snapshot_download / huggingface-cli / transformers.from_pretrained) honors the HF_ENDPOINT env var — change one env var, all code works via the mirror with zero changes.

That is the core value: no code edits, no dependency changes.

Step by step

1. First confirm it is a direct-connection problem (one-shot diagnosis):

   curl -s -o /dev/null -w '%{http_code} %{time_total}s
' --max-time 8 https://huggingface.co/
   # 000 / timeout = direct unreachable, go to step 2
   curl -s -o /dev/null -w '%{http_code} %{time_total}s
' --max-time 8 https://hf-mirror.com/
   # 200 = mirror available

1. Set HF_ENDPOINT and retry (no code changes). Still failing, check the specific error:

• cert/proxy errors → check proxy env vars (see proxy-env-var entry, case-sensitivity trap) and HF_HUB_DISABLE_XET=1 (newer versions use the Xet protocol by default; some networks need it disabled to fall back to plain HTTP).
• not found / 404 → wrong repo/file name; the mirror mirrors official structure, verify the path against the official URL.

1. Cache location: HF_HOME (default ~/.cache/huggingface) controls the download cache; delete it to re-download, unrelated to the mirror.
2. Offline: copy the downloaded HF_HOME directory to an offline machine and set the same HF_HOME — transformers loads from local cache first.

How to confirm it works

# 1. Env var active
echo $HF_ENDPOINT        # should print https://hf-mirror.com
# 2. Actual download succeeds (timing visible)
huggingface-cli download sshleifer/tiny-gpt2 config.json
# local path printed = success; second download hits cache and returns instantly

Other environments

• transformers / langchain / vllm and other upper-layer libs: they all call huggingface_hub internally, so HF_ENDPOINT works for all of them — set it once, benefit everywhere.
• ModelScope (Alibaba): works direct in China, no mirror needed; modelscope download --model Qwen/Qwen2.5-0.5B-Instruct-GGUF measured working (2026-08-30, 491MB/58.5s). For projects using both ecosystems: set HF_ENDPOINT on the HF side, leave ModelScope alone.
• Docker containers: containers do not inherit host env vars — pass docker run -e HF_ENDPOINT=https://hf-mirror.com or compose environment:.
• Windows: set HF_ENDPOINT=https://hf-mirror.com (cmd) or $env:HF_ENDPOINT="https://hf-mirror.com" (PowerShell), same behavior.

Verification evidence

• 2026-09-01 measured on this machine (WSL Ubuntu 26.04 no proxy, huggingface_hub 1.29.0): local repro log 2026-09-01
• curl https://huggingface.co/: 8s timeout code=000 (direct unreachable, proven);
• curl https://hf-mirror.com/: 200 / 0.6s (mirror available, proven);
• direct hf_hub_download(sshleifer/tiny-gpt2, config.json): hung 12s, killed by timeout (exit=124, proven);
• same call with HF_ENDPOINT=https://hf-mirror.com: success in 1.2s, 662 bytes (proven); zero code changes.