Downloading models without wasting a day

Fetching only what you need

A model repository holds several complete copies of the model: the original weights, sometimes a duplicate in an older format, sometimes several quants. Cloning it naively downloads all of them. The tooling lets you be specific:

pip install -U "huggingface_hub[cli]" hf_transfer
export HF_HUB_ENABLE_HF_TRANSFER=1

# just one quant from a GGUF repository
hf download bartowski/Qwen3-8B-GGUF \
  --include "*Q4_K_M*" --local-dir ~/models/qwen3-8b

# a full model, excluding a duplicate format
hf download Qwen/Qwen3-8B --exclude "*.pth" "*.msgpack" \
  --local-dir ~/models/Qwen3-8B

hf_transfer is a Rust downloader that parallelises across connections. On a fast link it is several times quicker; on a slow one it makes no difference and can be less resilient, so turn it off if you are seeing failures.

Downloads resume. If a 40 GB fetch dies at 80%, run the same command again rather than starting over.

Where files actually land

By default everything goes into a shared cache, typically ~/.cache/huggingface/hub, with content-addressed blobs and symlinks pointing at them. That is deliberate: two models sharing a tokeniser store it once, and re-downloading a revision you already have is free.

It also surprises people. --local-dir puts real files where you asked and, in recent versions, keeps them independent of the cache. Set HF_HOME to move the whole cache to a larger disk:

export HF_HOME=/mnt/big/hf

And clean up deliberately, because this directory grows without bound:

hf cache scan
hf cache delete

Ollama keeps its own store, usually ~/.ollama/models, in a layered format. ollama list and ollama rm manage it, and OLLAMA_MODELS relocates it.

Pin the revision

Model repositories are mutable. Weights get re-uploaded after a bug fix, templates get corrected, and occasionally a model is replaced with a different one under the same name. If a result matters, pin it:

hf download Qwen/Qwen3-8B --revision <commit-sha> --local-dir ./pinned

This is the difference between a reproducible setup and one that changes under you. It costs nothing at download time and saves the argument about whether the model changed or your prompt did.

Verify what arrived

Every file on the hub carries a hash, and the download tools check it. If you fetched by other means (a mirror, a colleague’s drive, a torrent) verify before running:

sha256sum model.gguf

A truncated GGUF often loads and then produces nonsense partway through, which is a confusing failure. Comparing one hash removes the possibility.

On a slow or metered connection

This is most of the world and the documentation rarely acknowledges it.

• Check the file size before starting. The repository lists it. A 4.9 GB file on a 5 Mbit connection is two and a half hours.
• Download the two small config files first and do the memory arithmetic. Two kilobytes to avoid five gigabytes of mistake.
• Prefer one quant. People download three tiers to compare and then never compare them.
• Use a mirror if the main host is slow or blocked from where you are. Regional mirrors exist and are configured with an environment variable, HF_ENDPOINT. Verify the hash afterwards.
• Move models between machines on a USB drive. A GGUF is a single self-contained file; copying it is legitimate and it works. Nothing needs to be re-downloaded.

When the connection is the problem

Two environment variables solve most download misery and almost nobody knows about them.

pip install hf_transfer
export HF_HUB_ENABLE_HF_TRANSFER=1   # multi-threaded, saturates a fast link
export HF_ENDPOINT=https://<mirror>  # route via a mirror where the hub is slow

The first replaces the default single-stream download with a parallel one. On a connection above roughly 200 Mbit/s the difference is several times faster, because the bottleneck was never the link. The trade is that its progress reporting is cruder and a failure is less informative, so turn it off when you are debugging a download rather than doing one.

The second matters in regions where the hub is slow or intermittently unreachable. Community mirrors exist and serve the same files; verify the checksums afterwards exactly as you would otherwise, because a mirror is a third party you have chosen to trust.

Both the hub client and curl -C - resume from where they stopped, so a 40 GB pull interrupted at 30 GB continues rather than restarts. Interrupt it deliberately if you need the bandwidth; nothing is lost.

Disk planning

A modest working set fills a disk faster than expected: an 8B at Q4 is 4.9 GB, a 14B is 8.5, a 32B is 19, a 70B is 42. Three models and two quants each is well over 100 GB.

Keep them on a drive with room to spare, know where the cache is, and scan it every few months. The alternative is discovering the problem when a system update fails for want of space, which is how most people learn where the cache lives.