Hugging Face hf CLI cheat sheet: download, verify and clean up model caches

Use this page when you need to fetch, check or remove model files on a GPU host or in a pod. If a download is already failing with an error, start with the post on Hugging Face download failures instead.

Check what you have first:

hf version
hf env              # library version, Python, cache and token paths
hf cache --help     # confirms the cache subcommands on this build

Older builds may have huggingface-cli and huggingface-cli scan-cache rather than hf cache ls. Commands below follow the current documentation.

#Daily commands at a glance

#Authentication

hf auth login                        # prompts for a token; skips if already logged in
hf auth login --force                # log in again, for example to change token
hf auth whoami                       # user and organisations
hf auth list                         # stored tokens
hf auth switch                       # change the active stored token
hf auth logout                       # remove stored tokens

For hosts and pods, use HF_TOKEN from your secret manager rather than an interactive login:

kubectl -n inference create secret generic hf-token --from-literal=HF_TOKEN="$HF_TOKEN"
kubectl -n inference set env deploy/llm-server --from=secret/hf-token

Warning

HF_TOKEN overrides the stored token, and hf auth logout won't log you out while it's set. If whoami shows the wrong identity after a login, run unset HF_TOKEN.

#Downloading models

#Check the size first

hf download <org>/<model> --dry-run
df -h "${HF_HUB_CACHE:-$HOME/.cache/huggingface/hub}"

The dry run reports the file count and total size, and downloads nothing. Add the same --include and --exclude filters you plan to use so the figure is accurate.

#Pin a commit

Branch names move, so get the commit hash and download that:

curl -s -H "Authorization: Bearer $HF_TOKEN" \
  https://huggingface.co/api/models/<org>/<model> | jq -r .sha

hf download <org>/<model> --revision <sha>

#Common variations

# One file only
hf download <org>/<model> config.json --revision <sha>

# Weights and config, but no other formats
hf download <org>/<model> --revision <sha> \
  --include "*.safetensors" --include "*.json" --include "tokenizer*"

# Skip one family of files
hf download <org>/<model> --revision <sha> --exclude "*.bin"

# Into a custom cache on a data disk
hf download <org>/<model> --revision <sha> --cache-dir /models/hf-cache

# Into a plain folder (creates .cache/huggingface inside it)
hf download <org>/<model> --revision <sha> --local-dir /models/<model>

# Print only the final path, for scripts
MODEL_PATH=$(hf download <org>/<model> --revision <sha> --quiet)

#Cache or local directory?

#Inspecting the cache

hf cache ls
hf cache ls --revisions
hf cache ls --cache-dir /models/hf-cache

# Filters can be repeated
hf cache ls --filter "size>30g" --revisions
hf cache ls --filter "accessed>30d"
hf cache ls --sort size:desc --limit 10

# For scripts
hf cache ls --format json
hf cache ls --format csv
hf cache ls --filter "accessed>1y" -q    # IDs only

Inside a pod, if the image includes the CLI:

kubectl -n inference exec deploy/llm-server -- hf cache ls --revisions

The cache keeps its layout per repo:

$HF_HOME/hub/models--<org>--<model>/
  refs/        branch or tag -> commit hash
  blobs/       the file contents, named by hash
  snapshots/   <commit>/ with symlinks into blobs

Several snapshots can share one blob, so don't work out disk use by adding up the snapshots folders. On Windows without Developer Mode or admin rights, symlinks aren't available, so snapshots hold full copies and use more disk.

#Verifying files

Use this after a suspect download, a disk event, or a copy to a new volume. Run it from a host that can reach the Hub, and add --token for private repos.

hf cache verify <org>/<model> --revision <sha>

# A plain folder rather than the cache
hf cache verify <org>/<model> --revision <sha> --local-dir /models/<model>

# Strict mode: also fail on missing or extra files
hf cache verify <org>/<model> --revision <sha> \
  --fail-on-missing-files --fail-on-extra-files

It exits non-zero on a checksum mismatch, so you can use it as a pipeline gate. By default, missing and extra files only produce a warning, so use the strict flags in a gate.

#Freeing disk

Caution

Deleting from a cache that a running server reads from can crash it, and with HF_HUB_OFFLINE=1 it can't download the files again. Drain or scale down the consumers first. Always use --dry-run first.

#Remove a repo or a revision

hf cache rm model/<org>/<model> --dry-run
hf cache rm model/<org>/<model>

# A single revision
hf cache rm <revision-hash> --dry-run

# Custom cache, no prompt
hf cache rm model/<org>/<model> --cache-dir /models/hf-cache -y

# Everything not used in a year, after reviewing the list
hf cache ls --filter "accessed>1y" -q
hf cache rm $(hf cache ls --filter "accessed>1y" -q) --dry-run

Repo IDs need the type prefix (model/, dataset/, space/). Unknown revision hashes are ignored silently, so a typo looks like a success. Check the dry-run output.

#Prune unreferenced data

hf cache prune --dry-run
hf cache prune

Prune removes revisions no branch or tag points to, leftover .incomplete files, and blobs nothing references.

Warning

A revision you pinned by commit hash can count as unreferenced, for example once main has moved to a newer commit. Prune can then delete the exact revision your server uses. Read the dry-run list. If a revision in use appears there, don't run prune on that cache. Remove the revisions you don't need by hash with hf cache rm instead.

#Other space to check

du -sh "${HF_HOME:-$HOME/.cache/huggingface}"/*

The xet folder under HF_HOME holds the Xet transfer cache, and the Hugging Face docs say it's safe to delete to reclaim space. Don't run that while a download is in progress.

#Environment variables

Boolean variables count as true only for 1, ON, YES or TRUE.

Note

HF_HUB_ENABLE_HF_TRANSFER is deprecated, because transfers now go through hf-xet. Remove it from old manifests and use HF_XET_HIGH_PERFORMANCE if you need more speed. The older HUGGING_FACE_HUB_TOKEN and HUGGINGFACE_HUB_CACHE are replaced by HF_TOKEN and HF_HUB_CACHE.

#Prevent it next time

• Pre-stage from a pipeline. Run hf download and hf cache verify in a job with Hub access, then mount the volume read-only on serving pods with HF_HUB_OFFLINE=1.
• Pin the CLI too. Set the huggingface_hub version in your image, because subcommands and flags have changed between releases.
• Keep cleanup out of serving hosts' cron jobs. Prune during a change window, after draining, and keep the dry-run output in the change record.
• Alert on cache volume usage. Leave room for the next revision, because a rollout may need two revisions on disk at once.
• Keep the token out of command history. Read it from a secret manager instead of passing --token on the command line.