← All notes

Answer: huggingface_hub uses a local file-based cache, the central cache shared across libraries that depend on the Hub. The default is ~/.cache/huggingface/hub, customizable with HF_HOME or HF_HUB_CACHE. Run hf cache ls to explore what is stored locally.

Layout per repo

• refs: files naming the latest revision of each reference; refs/main holds the commit identifier of the current head.
• blobs: the actual downloaded files, each named by its hash.
• snapshots: one folder per known revision, containing symlinks to the blobs.

A file isn't downloaded twice if it already exists and wasn't updated; an updated file is downloaded while the previous file is kept.

Location variables

• HF_HOME defaults to ~/.cache/huggingface; the token defaults to $HF_HOME/token.
• HF_HUB_CACHE defaults to $HF_HOME/hub.
• HF_HUB_OFFLINE=1 skips the HTTP check that hf_hub_download makes even when the latest file is cached.

Cleanup

Use hf cache rm to permanently delete repositories or revisions; hf cache prune removes shared files that no cached repo uses.

Artifacts

• Topic packet: huggingface

See also

• hf-hub-download-files
• hf-datasets-cache
• huggingface-hf-cli

Claims

• id: C1 claim: The Hub cache is shared across libraries. source: S1 evidence: "designed to be the central cache shared across libraries that depend on the Hub."

• id: C2 claim: Blob files are named by hash. source: S1 evidence: "The name of each file is their hash."

• id: C3 claim: HF_HUB_CACHE defaults under HF_HOME. source: S2 evidence: "Defaults to \"$HF_HOME/hub\" (e.g. \"~/.cache/huggingface/hub\" by default)."

• id: C4 claim: HF_HUB_OFFLINE=1 skips the freshness call. source: S2 evidence: "will skip this call which speeds up your loading time."

• id: C5 claim: hf cache rm deletes repos or revisions. source: S1 evidence: "to permanently delete repositories or revisions from your cache."

Sources

• [S1] Understand caching. Hugging Face docs. https://huggingface.co/docs/huggingface_hub/guides/manage-cache . License: Apache-2.0 (huggingface docs repos). Accessed 2026-11-09.

• [S2] Environment variables. Hugging Face docs. https://huggingface.co/docs/huggingface_hub/package_reference/environment_variables . License: Apache-2.0 (huggingface docs repos). Accessed 2026-11-09.

License: this note is CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/). Summary by iinventedlight (AI-assisted). Sources: Hugging Face docs (huggingface/transformers, huggingface/huggingface_hub, huggingface/diffusers on GitHub), Apache License 2.0 (https://www.apache.org/licenses/LICENSE-2.0). Text was condensed and changed from the originals.

@misc{iil_note_36v9wm8f,
  author = {{iinventedlight}},
  title = {{The Hugging Face Hub cache: layout, location, cleanup}},
  howpublished = {iinventedlight Library},
  year = {2026},
  date = {2026-11-09},
  url = {https://iinventedlight.com/library/notes/hf-hub-cache-management/},
  note = {Permanent ID iil:note:36v9wm8f. License: CC-BY-4.0.},
}

Markdown

Spotted a mistake? Use the MCP feedback tool or email hello@iinventedlight.com.

For language models and agents: start at /llms.txt | /agents.md | /.well-known/agent-library.json. This page in Markdown: /library/notes/hf-hub-cache-management.md.