Why HuggingFace model downloads are slow or stall partway through, and how to fix it
Download progress bar stops advancing and stays stuck at a partial percentage for minutes
Also appears as
- requests.exceptions.ChunkedEncodingError: Connection broken during download
- Downloading shards: very slow throughput, well under expected network speed
- urllib3.exceptions.ReadTimeoutError during snapshot_download
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.
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
Fastest path to a completed download
- 1Install and enable hf_transfer: pip install hf_transfer, then set HF_HUB_ENABLE_HF_TRANSFER=1 before running the download.
- 2Re-run the same download command; huggingface_hub resumes partially-downloaded files by default rather than starting over, so a stall is not wasted progress.
- 3If 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.
- 4For 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.
- 5For 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.
How to confirm this is your problem
- 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
Root causes and fixes
Default huggingface_hub transfer path is single-connection and not using the accelerated hf_transfer downloader
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.
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
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.
curl -o /dev/null -w '%{speed_download}\n' https://huggingface.co/org/model/resolve/main/config.jsonInsufficient or shared network bandwidth genuinely cannot move a very large model in reasonable time
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
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.
iostat -x 2
DNS resolution or CDN edge routing issues intermittently degrading connection quality to huggingface.co's storage backend
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.
Diagnostic commands
Confirm hf_transfer is actually active
python -c "import os; print(os.environ.get('HF_HUB_ENABLE_HF_TRANSFER'))" && python -c "import hf_transfer"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
curl -o /dev/null -w 'Speed: %{speed_download} bytes/sec\n' https://huggingface.co/org/model/resolve/main/model-00001-of-00004.safetensorsThis 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
iostat -x 2 5
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.
Stopping it from happening again
- 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 this becomes an architecture problem
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.
Frequently asked questions
Does hf_transfer work for uploads as well as downloads?
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?
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?
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?
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.
Size it properly next time
Free calculators that prevent this class of failure before you provision hardware.
Air-Gapped LLM Deployment Checklist
A practical control checklist for deploying and maintaining large language models in a fully air-gapped environment, from initial staging through ongoing patching and drift detection.
Free ToolOn-Prem AI Deployment Checklist
A 30-point pre-deployment checklist covering use cases, hardware, security, model operations, and rollout for self-hosted enterprise LLMs.
Free ToolDocument Ingestion Pipeline Estimator
Estimate total pipeline time from document count, OCR share, and embedding throughput, so ingestion timelines stop being a guess in the project plan.
Related problems
safetensors header too large or invalid header error loading model weights
A safetensors HeaderTooLarge or InvalidHeaderDeserialization error means the file's first bytes are not the expected binary length-prefixed JSON header, almost always because the file on disk is not the actual model weights but a truncated partial download or a small Git LFS pointer text file that was never smudged into the real binary. The fix is to verify the file size matches what the Hub reports and re-download it properly, either with huggingface_hub or with git lfs pull, not to try to repair the file in place.
Corrupted model checkpoint fails to load or loads with garbage weights
A corrupted checkpoint means the bytes on disk do not match the original artifact the model author published, whether from an interrupted download, a bad copy between systems, disk-level bit rot, or a failed write during a save operation. There is no reliable way to repair a corrupted deep learning checkpoint; the fix is always to verify the file against a known-good hash or size and re-obtain a clean copy, then build a verification step into your pipeline so the same failure does not silently recur.
Model loading fails offline or in an air-gapped environment despite having local files
Passing a local path to from_pretrained does not guarantee an offline load, because transformers and related libraries (tokenizers, some model configs, auto-mapping code) can still issue background network calls to check for updates, fetch a referenced remote component, or resolve auto_map entries that point back at the original HuggingFace repo. The fix is to set HF_HUB_OFFLINE=1 and TRANSFORMERS_OFFLINE=1 explicitly, use a complete local snapshot directory (not just the weights file), and verify no config field still references a remote repo ID.
401/403 Unauthorized pulling a gated model from HuggingFace
A 401 or 403 on a gated HuggingFace repo means the request reached the Hub but was rejected for authorization, not because the model does not exist. The three real causes are: you have not accepted the model's license on the web page with the account tied to your token, the token exists but was created without read access to gated repos, or the token is valid but was never actually passed to the download call (no HF_TOKEN in the environment, no login run). Fix by accepting the license, generating a token with the right scope, and exporting it where the client library will find it.
GuideSecuring Model Weights in the Enterprise
Secure model weights end to end: custody controls, encryption at rest, access policies, and exfiltration prevention for regulated AI deployments.
GuideAir-Gapped LLM Deployment Patterns That Actually Work
Air-gapped LLM deployment patterns that work: offline model transfer, update workflows, monitoring without telemetry, and CMMC-ready architectures.
GuideAir-Gapped Model Updates: A Patching Guide
Air-gapped model updates for enterprise AI: secure transfer procedures, hash verification, and staged rollout so patches never introduce risk.
Still stuck, or tired of fighting your own infrastructure?
Netray deploys and operates on-prem AI for regulated manufacturers and defense suppliers. We have debugged this stack in production, on air-gapped networks, at scale.