Network / downloads

HuggingFace download is extremely slow or stalls

Q: How do you fix "HuggingFace download is extremely slow or stalls"?

**Use the HF Xet protocol** (faster than the default Git LFS for new repos): ```bash hf download --xet ``` **Try a mirror.** HF-Mirror.com is a Chinese-friendly proxy: ```bash export HF_ENDPOINT=https://hf-mirror.com hf download meta-llama/Llama-3.1-8B-Instruct ``` **Use Ollama's curated mirror** for popular models (often faster + auto-quantized): ```bash ollama pull llama3.1:8b ``` **Resume failed downloads.** `hf download` resumes automatically if interrupted. If it stalls but doesn't error, kill with Ctrl-C and re-run — it picks up from the last completed shard. **Increase parallel download workers:** ```bash export HF_HUB_DOWNLOAD_TIMEOUT=300 hf download --max-workers 8 ``` **Off-peak hours** (your local 3-7 AM) typically saturate available bandwidth. If you're on a metered connection at home, consider running pulls overnight.

(downloads at 100 KB/s instead of saturating bandwidth)

By Fredoline Eruo · Last verified Jun 12, 2026

Cause

HF's CDN has regional inconsistencies — some regions get throttled to 1-5 MB/s, especially during peak hours or for new mega-models that haven't been cached locally yet. Asia and parts of Africa hit this most.

Solution

Use the HF Xet protocol (faster than the default Git LFS for new repos):

hf download <model> --xet

Try a mirror. HF-Mirror.com is a Chinese-friendly proxy:

export HF_ENDPOINT=https://hf-mirror.com
hf download meta-llama/Llama-3.1-8B-Instruct

Use Ollama's curated mirror for popular models (often faster + auto-quantized):

ollama pull llama3.1:8b

Resume failed downloads. hf download resumes automatically if interrupted. If it stalls but doesn't error, kill with Ctrl-C and re-run — it picks up from the last completed shard.

Increase parallel download workers:

export HF_HUB_DOWNLOAD_TIMEOUT=300
hf download <model> --max-workers 8

Off-peak hours (your local 3-7 AM) typically saturate available bandwidth. If you're on a metered connection at home, consider running pulls overnight.

Related errors

Did this fix it?

If your case was different, email Contact support with what you saw and we'll update the page. If it worked but took different commands on your platform, we want to know that too.