The Hugging Face cache lives under a folder called HF_HOME, by default ~/.cache/huggingface, and holds downloaded models in refs, blobs and snapshots subfolders. Anyone who can write there can change what your code loads next, so treat it like a dependency directory and not like a temp folder.
Layout in plain words
The huggingface_hub documentation describes a shared cache with a root, by default ~/.cache/huggingface/hub, that you can move with the cache_dir argument or with the HF_HOME or HF_HUB_CACHE environment variables. Models, datasets, spaces and kernels share that root, and each repo gets its own folder named by type and owner.
Inside a repo folder there are three parts:
| Folder | What it holds |
|---|---|
| refs | Files named for a reference such as main, each containing the commit identifier that reference pointed to when last fetched |
| blobs | The actual downloaded files, each named by its hash |
| snapshots | One folder per known revision, containing symlinks to the blobs |
This design avoids downloading the same file twice across revisions. It also means a load of the main reference reads the refs file, finds a commit, and follows symlinks into blobs.
Why write access matters
Two facts from the documentation combine badly. First, loading a model reads files from this cache. Second, HF_HOME is also where your access token is stored by default, according to the environment variable reference: it is where "your token and the cache will be stored."
If a build job caches the whole HF_HOME folder between runs, a later job restores both the model files and the token. Anyone who can influence that cache, for example a pull request from a fork in some CI setups, may be able to plant files or read the token. Whether that is possible depends on your CI system, so check it rather than assume.
Hardening steps
- Set HF_HOME to a path outside the shared workspace for each job, and do not persist it across untrusted jobs.
- Keep the token out of the cache folder. The reference lists HF_TOKEN and HF_TOKEN_PATH as ways to supply it, so you can avoid writing a token file under HF_HOME.
- In production, make the cache read only after the approved model is in place.
- Verify files before use. The documentation mentions an hf cache verify command; see its reference for options.
- Delete what you no longer need. The same docs describe hf cache rm and hf cache prune for cleanup.
Reading the cache like an auditor
List repos in the cache and compare each refs file with the commit hash your approval record names. A mismatch means a different revision than you approved is present on disk. For files, the blob name is a hash, which gives you something concrete to compare against your inventory.
Quick check
Is the cache just a performance feature?
It also decides what your code loads. Whoever can write to it can change that, so control write access.
Where does the Hub token live by default?
Under HF_HOME, the same tree as the cache, unless you set HF_TOKEN or HF_TOKEN_PATH.
Safeguard's policies and gates can require review when dependency definitions change, and asset discovery helps find where models and tools are running. See the free scan for a first look at a repository.
Sources
Last reviewed: 19 October 2026.
