Download model weights fast on a cloud GPU

The shortest model download is the one you shrink first. Ask the Hub what a repository weighs with hf download --dry-run, fetch only the files you will load, keep the cache on a disk with room, and let the Hugging Face CLI do the parallel transfer. Every minute of waiting is billed at the GPU's hourly rate, and the disk you download to is deleted when the instance stops.

Install the hf CLI and set a token

curl -LsSf https://hf.co/cli/install.sh | bash
hf auth whoami

The Hugging Face CLI documentation, checked 1 October 2026, lists that installer as the recommended route, and pip install -U huggingface_hub inside a virtual environment works as well. The command is hf. It replaced huggingface-cli in huggingface_hub 0.34, and the 1.0 migration guide says the old name was removed, so a tutorial that prints huggingface-cli download is out of date. On a fresh Ubuntu VM the installer can tell you to run sudo apt install python3-venv first. It adds ~/.local/bin to your PATH through your shell startup file and prints the source command that applies the change.

Set a token even for public models. The CLI warns that unauthenticated requests get lower rate limits and slower downloads. Type it without echo, so it stays out of your shell history and off the disk:

read -rsp "Hugging Face token: " HF_TOKEN; export HF_TOKEN; echo

The HF_TOKEN variable overrides any stored token. The Hub's token documentation recommends one token per use, and fine-grained tokens for production use. A rented VM is shared infrastructure, so create a token with read access only for this instance and delete it when the instance is gone.

For a gated repository such as Llama, request access on the model page first. The Hub documents that requesting access can only be done from a browser, and without it the CLI answers Error: Access denied. This repository requires approval.

Ask the Hub what a download weighs with --dry-run

hf download openai/gpt-oss-120b --dry-run
hf download openai/gpt-oss-120b --exclude "original/*" --exclude "metal/*" --dry-run

On 1 October 2026 the first command reported about 196G for the whole repository, and the second about 65G. The repository holds three copies of the weights: the safetensors files at the root, a second set under original/, which the model card points to for the reference implementation, and a single model.bin under metal/. If you load the model with Transformers or vLLM, as the vLLM guide does, you need only the root files, and the unfiltered download would have spent two thirds of its time on files you never open.

I run --dry-run before any download larger than a few gigabytes. Compare the total with df -h . before you start. On QuantaCloud, Massed Compute and Hyperstack the disk is fixed by the offer, so a repository larger than the free space fails partway with No space left on device. Repositories get reorganised, so run the dry run yourself rather than trusting these numbers.

Download only the files you will load

# Safetensors weights and configs, without the extra copies
hf download openai/gpt-oss-120b --exclude "original/*" --exclude "metal/*"

# One quantization out of a GGUF repository
hf download unsloth/Qwen3.8-27B-GGUF Qwen3.8-27B-UD-Q4_K_M.gguf --local-dir ./models

The same dry run on the GGUF repository reported 33 files totalling 472.1G on 1 October 2026, and the one file named above is 16.5G. A repository of quantizations is a menu, so download the item you will run. --include and --exclude take glob patterns, and repeating the flag adds patterns.

Use the cache, which is the default, when a library such as Transformers or vLLM loads the model by name. Use --local-dir when a tool wants a plain path, such as a GGUF file for llama.cpp. The Hugging Face download guide explains the difference.

Put the cache where the space is: HF_HUB_CACHE

By default the cache is ~/.cache/huggingface/hub, inside the login user's home directory. Two variables move it. HF_HOME moves everything, including your token file and the Xet cache, and HF_HUB_CACHE moves only the downloaded repositories. Which disk has room depends on the provider:

On a volume, set HF_HUB_CACHE and leave HF_HOME alone, so the token file stays on the instance disk:

export HF_HUB_CACHE=/mnt/data/hf-cache
mkdir -p "$HF_HUB_CACHE"

A volume arrives unformatted, and you format and mount it yourself, as the stop guide shows. A cache is the right thing to keep on one, because losing it costs a download and nothing else. A volume is billed hourly for every hour it exists, attached or not, and it is deleted permanently, with no email, if your balance cannot pay for its next hour. To decide whether it is worth holding, run time hf download ... once, price that time at the GPU's hourly rate, and compare it with the volume's hourly rate on the volumes page multiplied by the hours you would keep it.

If vLLM runs in Docker, mount the same directory, or it downloads the model again into the container's own layer on the same disk. With the cache above, the mount is -v /mnt/data/hf-cache:/root/.cache/huggingface/hub.

Speed: Xet, parallel workers and the retired hf_transfer

Since huggingface_hub 0.32.0, installing the package also installs hf_xet, and the environment variable reference says all transfers go through it. It splits files into chunks and fetches ranges in parallel. One setting raises it further, and the documentation says it tries to saturate the machine's network bandwidth and use every CPU core:

HF_XET_HIGH_PERFORMANCE=1 hf download Qwen/Qwen3.8-27B

HF_XET_NUM_CONCURRENT_RANGE_GETS controls how many chunk ranges are fetched at once per file, with a default of 16, and --max-workers sets how many files download at once, with a default of 8. Many tutorials still tell you to install hf_transfer and set HF_HUB_ENABLE_HF_TRANSFER=1. The 1.0 migration guide says support for hf_transfer was removed and the variable is now ignored.

Speed depends on the provider's network and on the Hub, so the number to trust is your own. Prefix the command with time and divide the size by the seconds. Run long downloads inside tmux, as keeping jobs running after you disconnect explains. If a transfer stops, run the same command again. hf cache prune removes the partial .incomplete files if you give up on one.

Verify the files and never download twice

hf cache verify openai/gpt-oss-120b
hf cache ls
hf cache rm model/openai/gpt-oss-120b

hf cache verify checks the cached files against the checksums on the Hub. hf cache ls lists what the cache holds, and hf cache rm frees the space. The cache is keyed by repository and revision, so Transformers, diffusers and vLLM all reuse a model that hf download already placed there. Stopping the instance deletes the instance disk and any cache on it, and the next launch downloads again. The stop guide lists what to copy off first, and moving data to and from a cloud GPU covers your own datasets.

Five download failures and what they mean