Hugging Face download slow? Every fix, ranked

If the advice you found says to install hf_transfer and export HF_HUB_ENABLE_HF_TRANSFER=1, that advice is outdated. Hugging Face's current documentation marks hf_transfer deprecated and its enabling variable ignored, because the Hub now serves large files through the Xet storage backend rather than Git LFS. The fix that tops most forum threads does nothing on a current install.

Slow Hugging Face downloads come from one of four things: a single browser connection, the Xet backend reassembling chunks on a slow disk, a rate-limit stall that looks like a freeze, or your own network and route. Two commands fix most of it. Download with the hf CLI instead of a browser tab, and log in first.

The ranked list, most likely fix first:

1. Use the CLI, not a browser tab. hf download pulls files in parallel and resumes where a browser starts over.
2. Log in. hf auth login moves you off the anonymous quota that is counted per IP address.
3. Tune Xet, or turn it off. HF_XET_HIGH_PERFORMANCE=1 raises concurrency; HF_HUB_DISABLE_XET=1 takes the non-Xet path.
4. Raise the timeout. HF_HUB_DOWNLOAD_TIMEOUT=30 triples the 10-second default.
5. Go parallel over HTTP. aria2c -x16 -s16 -c on one file's resolve URL.
6. Clean the cache. hf cache ls lists leftover partials, hf cache prune removes them.

Not sure which slowness you have? Skip to the decision block and match the symptom to the fix.

First, measure: is it you or is it them?

Before you change anything, get one number. Hugging Face publishes its own speed test at fast.hf.co, and the same documentation ships a speedtest extension for the hf CLI. Run the Hugging Face test, then any general speed test, on the same machine and connection.

Compare the numbers. If the general test lands near the speed you pay for and the Hugging Face test crawls, the problem sits on the path between you and the Hub, and the fixes below apply. If both crawl, fix your own network first. If the two disagree by the hour, you are watching route and load variance, which no client setting removes.

What actually makes Hugging Face downloads slow

Six mechanisms cover nearly every report. Each row names the symptom it produces, because the fix differs.

The redirects, the hostname list, and the blocked-host symptom are documented in Hugging Face's guide to downloading models; the quota mechanics, including the window length and the per-IP rule, are in the rate-limits page.

The fixes, ranked

1. Use the hf CLI, not a browser tab

For large repositories the browser is the slow way: one connection, no parallelism, and a failed download starts over. The hf CLI downloads files in parallel and keeps partial work. Install it with pip install -U "huggingface_hub", then pull a model by its repository id:

hf download Qwen/Qwen3-8B --local-dir Qwen_Qwen3-8B

Re-running the same command after an interruption resumes from the partial blobs already in the cache; there is no resume flag to pass.

2. Log in before you download

Anonymous download quota is counted per IP address, which means you share it with everyone behind the same NAT: an office, a campus, a cloud region. A logged-in session gets its own quota, which is why passing a token is the first fix in Hugging Face's own rate-limits guidance.

hf auth login

A rate limit usually shows up as a stall, not a message: the download starts fast, then sits at 0 B/s while huggingface_hub 1.2.0 and later quietly sleeps out the five-minute window and retries. If you are seeing 429, 403, or 418 errors instead of stalls, that is a different problem: Hugging Face errors 429, 403 and 418, decoded.

3. Tune Xet, or turn it off

Since huggingface_hub 0.32.0, installing the library also installs hf_xet, the Rust client for the Xet backend. Xet stores files as immutable chunks and reassembles them on download, fetching them by the file's LFS SHA256. Downloads run with adaptive concurrency, starting at 1 stream and scaling up to 64. Three variables change how that behaves on your machine.

High performance, when the machine can take it:

HF_XET_HIGH_PERFORMANCE=1 hf download Qwen/Qwen3-8B

This raises concurrency and buffer sizes to try to saturate your bandwidth and use every CPU core. Hugging Face aims it at machines with high bandwidth and at least 64 GB of RAM. On a small VPS it can make things worse, not better.

Sequential writes, for spinning disks:

HF_XET_RECONSTRUCT_WRITE_SEQUENTIALLY=1 hf download Qwen/Qwen3-8B

If chunk reassembly is hammering a hard drive, this writes the file back in order. The related HF_XET_NUM_CONCURRENT_RANGE_GETS defaults to 16 range requests; leave it alone unless the documentation sends you there.

Xet off, when Xet is the problem:

HF_HUB_DISABLE_XET=1 hf download Qwen/Qwen3-8B

Forum reports have traced speeds like 290 kB/s to Xet misbehaving on specific machines, and this variable forces the non-Xet path. The documentation asks anyone who sets it to file an issue; the team wants the reports.

4. Raise the download timeout

HF_HUB_DOWNLOAD_TIMEOUT defaults to 10 seconds. The CLI documentation shows the failure it produces, a ReadTimeout against a cdn-lfs hostname, and recommends raising it to 30:

HF_HUB_DOWNLOAD_TIMEOUT=30 hf download Qwen/Qwen3-8B

If timeouts persist at 30, the usual cause is a storage or CDN hostname your network blocks, since downloads redirect off huggingface.co to separate hosts. Hugging Face publishes the hostname list, plus a machine-readable .well-known/meta.json for scripting your own checks. On a locked-down network the fix is getting those hosts allowlisted, not routing around them.

5. Parallel HTTP with aria2c

When you want one file rather than a whole repository, hand aria2 the file's resolve URL:

aria2c -x16 -s16 -c "https://huggingface.co/Qwen/Qwen3-8B/resolve/main/model-00001-of-00005.safetensors"

-x sets connections per server, and its default is 1. -s splits the file. -c resumes a partially downloaded file, over HTTP and FTP only. Two caveats from the field: auto-file-renaming is on by default, so a re-run without -c can leave a .1 sibling next to the original instead of resuming, and every split is another request against the same rate limit, so the community guide that popularized this pattern warns to be careful not to hit it.

6. Cache hygiene

The cache stores each file once under a hash name and links it into per-revision snapshot folders. Three subcommands keep it healthy:

hf cache ls      # lists entries, flags leftover .incomplete files
hf cache prune   # removes those leftovers
hf cache verify  # checks cached files against the Hub's checksums

Point HF_HOME at your fastest disk, and keep about twice the model size free while a download runs. The 2x figure is community advice from forum checklists, not an official number, but it matches how the cache writes partials alongside finished blobs.

Which symptom do you have?

One table, symptom to fix; two rows hand off to sibling guides because the bottleneck is not download speed on the huggingface.co path.

How long should a model take? The math

Slow is a number, not a feeling. At N MB/s, one gigabyte takes about 1000 divided by N seconds. That one division tells you whether your download is broken or merely big.

The 1.9 MB/s row is a real user report: someone measured exactly that on a 19 GB file, which works out to about 2.8 hours, and wrote that it takes hours. The arithmetic agrees with them. Speeds like 10 MB/s falling to 500 kB/s mid-file, and caps around 10.4 MB/s, come from the same forum threads; treat them as reports, not promises.

The sizes come from this archive's signed manifest, which records Qwen_Qwen3-8B at 16.40 GB and Qwen_Qwen-Image at 57.70 GB. Both are in the catalog.

About hf_transfer, the advice everyone still gives

What hf_transfer was: a power-user tool for pushing past roughly 500 MB/s, with no progress bars, as its own README still describes it. That README has never mentioned the deprecation, which is a fair part of why the old advice keeps ranking: the posts were written before the storage switch, and the tool's own page never corrected them.

What to set instead: the environment variable reference is the authoritative list. For speed, the modern equivalent is HF_XET_HIGH_PERFORMANCE=1 on a machine with the RAM for it. For everything else, plain hf download already does adaptive concurrency from 1 to 64 streams.

Resuming without starting over

Interrupted hf downloads leave partial blobs behind. In the cache documentation's own words, .incomplete files are partial blobs left behind when a download is interrupted. The next run of the same command picks them up. So if a download dies at 60 percent, you do not start over: re-run the command.

When a partial goes bad, the symptom is a download that keeps failing at the same spot. hf cache prune clears the leftovers so the next attempt starts clean. Direct file URLs resume too: aria2c -c continues over HTTP, and wget -c does the same job.

One cost nobody warns you about: finding out where a resume stands can itself be slow; users report waiting half an hour to learn where the restart picks up. That is discovery work inside the client, not your bandwidth, and no variable in fix 3 or fix 4 removes it.

The structural fix: a download that resumes by design

Everything above tunes a download that still comes from one source. The other option is a transport built around the failure mode. A torrent client keeps every finished piece across restarts, fetches only what is missing, needs no account or token, and no request window counts against it.

The honest caveat is speed: it depends on seeders, so a torrent can beat a single HTTPS stream and can also lose to it. The promise is not faster. The promise is that no single server, quota, or account sits between you and the bytes.

That is the structure this archive runs on. Every payload was verified against upstream Hugging Face at fetch time, with the exact revision pinned, and the file list travels as a minisign-signed manifest you re-check client-side: per-file digests with the method labeled, sha256 for LFS files and sha1+size for git blobs. To prove the bytes before you load them: the verification walkthrough is the deep dive, the verify page the three-command version.

New to torrents as a distribution method? The legality and trust questions are covered in the AI model torrents guide, and the vocabulary you will meet, magnets and infohashes and seeding, in the magnet links and infohashes guide. Picking a client is on the help page, and the models themselves are in the catalog.

One ask when a download finishes: leave the client running. A finished torrent seeds automatically, a share ratio of 2.0 or better is the goal, and every seeder is someone else's fast download. What that sustains is on the contribute page, and if the model you need is not archived yet, requests is where to ask for it.