How to clear the Hugging Face cache safely

Use the current hf cache commands to inspect the cache before deleting anything. Remove a known repository or revision with hf cache rm; use hf cache prune for revisions that are no longer referenced. Do not treat the cache directory as a pile of independent files—snapshots can share the same blobs.

Why manual deletion is deceptively risky

The Hub cache is designed to avoid downloading identical content twice. Under the hub cache, a repository normally has refs, snapshots and blobs. A snapshot presents a revision as a usable directory, while its files may link back to shared content in blobs. Two revisions can therefore appear to contain the same large weight file without consuming two full copies.

That layout is efficient, but it makes “delete the biggest-looking folder” a poor rule. Removing a live blob by hand can break more than one snapshot. Removing one snapshot may free much less space than its apparent size because other revisions still reference the same content.

Measure the cache you are actually using

First find the active Hugging Face cache directory. HF_HOME, HF_HUB_CACHE and related variables may have moved it away from the default. Then ask the CLI for its view of the cache:

hf cache ls
hf cache ls --revisions

The first command lists cached repositories; the second exposes individual revisions. Use filters or sorting from the current CLI when the list is large. The decision you need is not simply “what is old?” but “which exact repository or revision can be fetched again, and which one supports current work?”

Remove a repository or revision deliberately

When you know an entire cached repository is disposable, pass its cache identifier to hf cache rm. The current documentation uses a repository identifier such as:

hf cache rm model/gpt2

For narrower cleanup, select the specific revision identifier reported by hf cache ls --revisions. Read the preview and confirmation carefully. The CLI can calculate what becomes unreferenced; a filesystem selection cannot explain those relationships to you.

Prune detached revisions, not your working set

hf cache prune targets revisions that are no longer referenced. It is the right tool for stale revision data left behind as branch or tag references change, but it is not a promise that every old model you no longer remember will vanish. Run it after inspecting the proposed removal, not as an automatic reflex at the end of every session.

hf cache prune

If the cache is managed by several users, containers or scheduled jobs, stop active downloads first. A cleanup performed while another process is materialising a snapshot creates needless ambiguity even when the cache implementation is designed to recover.

Verify what remains

1. Run hf cache ls again and record the new size.
2. Use hf cache verify <repo> for a retained repository you care about.
3. Start one real workflow that loads a retained model.
4. Watch for a fresh download: a model that silently re-fetches was not fully available locally.

A redownload is not always a failure—the cache is a cache—but it matters when you work offline, pin a particular revision or depend on an upstream file that may disappear.

Cache cleanup and long-term retention solve different problems

The Hub cache is optimised for reuse and refetching. It is not a curated record of why a model, tokenizer, configuration or adapter belonged together. Before clearing a hard-to-reproduce revision, identify the complete family needed to use it. For a PEFT adapter, that can include a compatible base model and configuration; for a training result, it may include more than the weights alone.

Tensor Archive belongs on that deliberate side of the line. Retain a completed local family, verify the archive and prove an exact restore. Then the cache can go back to being disposable infrastructure instead of an accidental museum.

Related guides

If the current cache is simply on the wrong disk, follow the separate guide to change the Hugging Face cache directory. If the library spans several runtimes, use the retention checklist before deciding what is merely replaceable cache state.