# Why HuggingFace model downloads are slow or stall partway through, and how to fix it > Source: https://netray.co/troubleshoot/huggingface-download-slow-or-stalled > Publisher: Netray (netray.co), AI and integration engineering for ERP and manufacturing systems. > Section: On-Prem AI Troubleshooting ## Short answer Slow or stalled HuggingFace downloads are usually caused by huggingface_hub's default transfer path not using parallel chunked downloads, a corporate proxy or firewall throttling or dropping long-lived connections, or genuinely insufficient bandwidth for a hundreds-of-gigabytes model. Enable hf_transfer for a much faster Rust-based parallel downloader, rely on the client's built-in resume behavior rather than restarting from zero, and for regulated or air-gapped sites, download once and mirror internally instead of pulling repeatedly over the internet. ## Error Title HuggingFace model download is extremely slow or stalls partway through ## Error Signature Download progress bar stops advancing and stays stuck at a partial percentage for minutes ## Alternate Signatures - requests.exceptions.ChunkedEncodingError: Connection broken during download - Downloading shards: very slow throughput, well under expected network speed - urllib3.exceptions.ReadTimeoutError during snapshot_download ## Category model-loading ## Stack - huggingface - transformers ## Affects Large multi-shard model downloads (tens to hundreds of GB) over standard huggingface_hub transfer, any network with variable bandwidth or corporate proxy interference ## Quick Fix ### Fastest path to a completed download **Steps:** Install and enable hf_transfer: pip install hf_transfer, then set HF_HUB_ENABLE_HF_TRANSFER=1 before running the download. Re-run the same download command; huggingface_hub resumes partially-downloaded files by default rather than starting over, so a stall is not wasted progress. If behind a corporate proxy, set HTTP_PROXY/HTTPS_PROXY environment variables explicitly and check whether the proxy has an idle-connection timeout shorter than your download. For very large models, use huggingface-cli download (or hf download) rather than a plain from_pretrained call, since the CLI is built for large, resumable, parallel transfers. For repeated internal deployments, download once to a staging host, verify checksums, then serve every other node from an internal mirror or artifact store instead of hitting huggingface.co repeatedly. ## Symptoms - Progress percentage advances very slowly compared to your known network bandwidth - Download appears to freeze entirely at a fixed byte count for an extended period before erroring or resuming - Throughput is fine for small files but degrades specifically on very large shard files - Repeated runs each restart from a low percentage rather than resuming near where the last attempt left off ## Causes ### Default huggingface_hub transfer path is single-connection and not using the accelerated hf_transfer downloader **Likelihood:** most-common **Explanation:** By default, huggingface_hub downloads files using standard Python HTTP requests, which do not fully utilize available bandwidth on high-latency or high-bandwidth links because they do not parallelize chunks of a single large file. The optional hf_transfer package is a Rust-based downloader that fetches multiple chunks of the same file concurrently, which can dramatically improve throughput especially on fast internet connections where the bottleneck was concurrency, not raw bandwidth. **Fix:** Install hf_transfer and set the HF_HUB_ENABLE_HF_TRANSFER=1 environment variable before starting the download; huggingface_hub automatically uses it once installed and enabled. **Commands:** - pip install hf_transfer - export HF_HUB_ENABLE_HF_TRANSFER=1 ### Corporate proxy, firewall, or DPI middlebox throttles or drops long-lived large HTTP transfers **Likelihood:** common **Explanation:** Enterprise network appliances frequently apply per-connection bandwidth caps, idle timeouts, or deep packet inspection that adds significant latency, all of which disproportionately affect very large, long-duration file transfers compared to typical short web requests. This produces the classic pattern of a download crawling or stalling entirely partway through a multi-gigabyte shard while smaller unrelated traffic works fine. **Fix:** Check with network/security teams for any egress bandwidth limits or timeout policies applied to huggingface.co traffic specifically, and where policy allows, request an allowlist exception or a dedicated egress path for model downloads. **Commands:** - curl -o /dev/null -w '%{speed_download}\n' https://huggingface.co/org/model/resolve/main/config.json ### Insufficient or shared network bandwidth genuinely cannot move a very large model in reasonable time **Likelihood:** occasional **Explanation:** A 70B or larger model in FP16 can be well over 140GB; on a shared office connection or a constrained cloud egress link, this can legitimately take hours regardless of client-side optimizations, especially if multiple engineers are downloading models simultaneously and competing for the same bandwidth. **Fix:** Schedule large downloads during off-peak hours, download once to a shared internal location rather than having every engineer or node pull independently, and consider a dedicated high-bandwidth download host if this is a recurring need. ### Disk I/O bottleneck on the write side makes it look like a network stall **Likelihood:** occasional **Explanation:** If the target disk is slow (network-attached storage with high latency, a nearly-full disk triggering filesystem overhead, or a spinning disk under contention from other processes), the download can appear stalled in the progress bar because the client is blocked writing already-received data rather than actually waiting on the network. **Fix:** Download to fast local storage (local NVMe rather than network mounts) and check disk I/O activity during a stall to distinguish a network problem from a storage problem. **Commands:** - iostat -x 2 ### DNS resolution or CDN edge routing issues intermittently degrading connection quality to huggingface.co's storage backend **Likelihood:** rare **Explanation:** HuggingFace serves large files through a CDN-backed storage layer; occasional edge node issues or DNS resolution inconsistencies can cause a specific download session to route through a degraded path, producing intermittent slowness that is not reproducible from a different network or at a different time. **Fix:** Retry from a different network or at a different time to rule out a transient routing issue, and check HuggingFace's status page for reported incidents before assuming a local misconfiguration. ## Diagnostics ### Confirm hf_transfer is actually active **Command:** python -c "import os; print(os.environ.get('HF_HUB_ENABLE_HF_TRANSFER'))" && python -c "import hf_transfer" **Interpretation:** If the environment variable is unset or hf_transfer fails to import, the accelerated downloader is not being used at all, which is the single most common fix left undone. ### Baseline raw network throughput independent of the Python client **Command:** curl -o /dev/null -w 'Speed: %{speed_download} bytes/sec\n' https://huggingface.co/org/model/resolve/main/model-00001-of-00004.safetensors **Interpretation:** This isolates whether the slowness is in huggingface_hub's client behavior or in the underlying network path itself, since curl bypasses the Python download logic entirely. ### Check disk write throughput during a stall **Command:** iostat -x 2 5 **Interpretation:** High disk utilization percentage with low throughput during a stall points to a storage bottleneck rather than a network problem, redirecting your troubleshooting toward disk performance instead. ## Prevention Make hf_transfer installation and the HF_HUB_ENABLE_HF_TRANSFER environment variable a standard part of your team's model-download setup or Docker image, not an ad hoc fix applied after the fact. For teams deploying to multiple internal nodes, maintain one internal model mirror or artifact registry so only one download from the internet is ever needed per model version. For air-gapped sites, plan model transfers as a scheduled, verified batch process (download, checksum, physically or securely transfer) rather than expecting live internet access from the production environment. Monitor and alert on download duration for routine model updates so a degrading trend is caught before it becomes a blocking incident during a time-sensitive deployment. ## When To Escalate If slow downloads are a recurring operational problem across many engineers or deployments rather than a one-off network blip, the fix is infrastructure: a properly resourced internal model mirror or artifact registry with verified, checksummed artifacts, sized for your actual model update cadence. That is a deliberate infrastructure investment, not something to keep working around per download. ## Faq ### Does hf_transfer work for uploads as well as downloads? **Answer:** Yes, hf_transfer accelerates both directions of large file transfer with the Hub, using the same environment variable, which is useful when pushing large fine-tuned checkpoints back to a private repo as well as pulling base models down. ### Will resuming a stalled download re-verify the parts that already downloaded? **Answer:** huggingface_hub's resume behavior checks existing partial file state and continues from where it left off using range requests; it is still good practice to verify the final file's checksum or size against the Hub's listing once the download completes, rather than assuming resume is always perfectly consistent. ### Is it better to use git clone or huggingface_hub for very large models? **Answer:** huggingface_hub (via snapshot_download or the huggingface-cli/hf download command) is generally preferred for large model repos, since it handles resumable, parallel downloads of LFS-backed binary content directly, whereas a plain git clone requires a correctly configured git-lfs setup and lacks the same resume ergonomics. ### Can I download only specific files instead of the entire model repo? **Answer:** Yes, snapshot_download accepts an allow_patterns argument to fetch only matching files (for example, only *.safetensors and the config/tokenizer files while skipping alternate formats like .bin or .gguf that might also be present in the same repo), which reduces unnecessary transfer for repos that ship multiple weight formats. ## Search terms huggingface download slow, huggingface download stuck, hf_transfer speed up download, huggingface resume download, snapshot_download slow, model download stalled --- Talk to an engineer: https://netray.co/contact?intent=erp_ai | Machine catalog: https://netray.co/agent/catalog.json