Where the hf CLI downloads models and how to move it

The hf CLI keeps downloaded models in one shared cache so several tools reuse a single copy. Knowing where that is lets you free space, move it to a bigger drive, or work offline.

1. Find the default cache path

The cache lives under HF_HOME, which defaults to ~/.cache/huggingface; repos go in its hub subfolder (HF_HUB_CACHE, default $HF_HOME/hub):

macOS / Linux: ~/.cache/huggingface/hub
Windows: C:\Users\<you>\.cache\huggingface\hub

Inside, each repo is a folder like models--bartowski--Llama-3.2-3B-Instruct-GGUF holding snapshots/, blobs/ and refs/. The snapshots folder has the files you actually use (symlinks to blobs, which holds the real data); refs records the latest commit per branch.

2. See the path with hf cache ls and hf env

hf cache ls

Lists every cached repo with its size, last-accessed time and refs. Add --revisions for per-snapshot detail.

hf env

Prints your setup, including the resolved cache directory. Trust this over any guess about the path.

3. Move the cache to another drive

Set HF_HOME before downloading. huggingface_hub reads it at import, so set it in your shell profile, not mid-script.

macOS / Linux:

export HF_HOME=/mnt/bigdrive/hf

All HF data (model cache plus token) now lands under that path.

Windows (PowerShell):

[Environment]::SetEnvironmentVariable("HF_HOME", "D:\hf", "User")

Sets it permanently for your user; reopen the terminal to pick it up. To move only the model cache and leave the token in place, set HF_HUB_CACHE instead. Details are in the official cache guide.

4. Clean old models and revisions

hf cache ls --filter "size>5G" --revisions
hf cache rm model/bartowski/Llama-3.2-3B-Instruct-GGUF
hf cache prune

ls --filter finds the big items; rm deletes a repo or a revision hash; prune clears unreferenced revisions and .incomplete leftovers from interrupted downloads. Add --dry-run to preview, or --yes to skip the prompt.

To drop a single GGUF quant without touching the rest:

hf cache rm hf://models/bartowski/Llama-3.2-3B-Instruct-GGUF/Llama-3.2-3B-Instruct-Q4_K_M.gguf

Removes that one file; it re-downloads next time it is needed.

5. Work offline

export HF_HUB_OFFLINE=1

PowerShell: $env:HF_HUB_OFFLINE = "1". Skips all Hub HTTP calls and serves only cached files; a missing file then raises an error instead of downloading.

If it fails:

hf env still shows the old path after setting HF_HOME — you set it only in the current shell, or after Python already imported the library. Set it in your profile and open a new terminal.
Windows warning cache-system uses symlinks ... not supported — enable Developer Mode or run as admin, or set HF_HUB_DISABLE_SYMLINKS=1 to copy files into snapshots instead.
hf cache rm reports the revision was not found — you passed a branch name. Pass a repo id (model/org/name) or a full revision hash from hf cache ls --revisions.

Next: download models with the hf CLI · upload a model or dataset · how much RAM or VRAM a model needs.