Where apps hide your files

The Hugging Face cache folder

Updated 2026-10-28 · 5 min read

Every library that uses the Hugging Face Hub, from transformers to diffusers, shares one hidden cache in your home folder. It can quietly reach tens of gigabytes, and it has proper tools for cleaning it.

The default location

~/.cache/huggingface/hub

That is the default cache for models, datasets and spaces downloaded through huggingface_hub, which transformers, diffusers and most other Hub-aware libraries use under the hood. Its parent, ~/.cache/huggingface, is what the HF_HOME variable controls. In Finder, press ⇧⌘G, paste the path and press Return. From Terminal:

open ~/.cache/huggingface/hub

If that folder does not exist, either nothing has been downloaded through the Hub library on this Mac, or HF_HOME, HF_HUB_CACHE or XDG_CACHE_HOME is redirecting it. Check with echo $HF_HOME $HF_HUB_CACHE $XDG_CACHE_HOME in the same Terminal where you run Python.

How the folder is organised

Each repository gets one folder named with its type and its owner, with the slash replaced by two dashes:

hub/
  models--meta-llama--Llama-3.2-1B-Instruct/
    blobs/
    refs/
    snapshots/
  datasets--glue/

Inside each repository folder:

Folder	Purpose
blobs/	The real files, named by hash. This is where the gigabytes are.
snapshots/	One folder per revision, with the readable file names (config.json, model.safetensors) as symlinks pointing into blobs/.
refs/	Tiny files such as main recording which commit a branch name resolved to.
trees/	Cached file lists per commit, written by recent versions of the library.
.no_exist/	Empty marker files for optional files that do not exist upstream.

So when a tutorial says "the model is in the cache", the file you can actually open is under snapshots/<commit>/, and it is a symlink. Recent versions of the library can also keep a shared blobs/ folder at the top of the cache, so a file that appears in more than one repository is stored once; in that case an entry in a repository's own blobs/ folder is itself a link into the shared store.

Two other things live under ~/.cache/huggingface. A xet folder holds the hf_xet transfer layer's shard cache and upload staging data, and can be moved with HF_XET_CACHE. Libraries may also keep an assets folder. If you have logged in, your access token is saved as ~/.cache/huggingface/token by default, so never copy the whole directory to a shared drive or attach it to a support ticket.

See what is using the space

The hf command line tool that ships with huggingface_hub reports this without you doing arithmetic on symlinks:

hf cache ls

It lists each cached repository with its size and when it was last accessed, and accepts filters such as --filter "size>1GB" and --sort size. Older releases used huggingface-cli scan-cache for the same job, so if hf is not found, update the package or try that name. A plain du -sh ~/.cache/huggingface/hub gives the total, but trust the tool for per-model numbers.

Cleaning up safely

Use the library's own commands, which know which blobs are shared:

hf cache rm model/bert-base-cased --dry-run
hf cache prune

rm removes a repository or a single revision (--dry-run previews it, and it asks before deleting), and prune clears revisions no branch or tag points to, plus leftover .incomplete files from interrupted downloads. Removing a model does no permanent harm: it downloads again the next time code asks for it. What to avoid is deleting single files out of blobs/ in Finder, because the snapshot symlinks will then dangle and the library may report a broken cache.

The library also writes a CACHEDIR.TAG file in the cache, which tells backup tools that follow the Cache Directory Tagging Standard that the folder can be skipped.

Moving the cache to another drive

Set one of these before you start Python, because the library reads them when it is imported:

• HF_HOME moves the whole Hugging Face folder (hub cache, token, xet and the rest).
• HF_HUB_CACHE moves only the model and dataset cache.

In a Terminal session:

export HF_HOME=/Volumes/FastDrive/huggingface

Put the line in ~/.zshrc to make it stick for Terminal. Apps launched from the Dock, including some notebook and desktop tools, do not read ~/.zshrc, so they keep using the default unless you set the variable for them.

To keep what you have already downloaded, quit anything that is downloading and copy the folder with a tool that keeps symlinks as symlinks. This copies without deleting anything:

rsync -a ~/.cache/huggingface/ /Volumes/FastDrive/huggingface/

Check the new location with hf cache ls in a Terminal where HF_HOME is set, then move the old folder to the Trash in Finder. Tools that follow symlinks while copying turn every link into a full duplicate and can double the size.

Moving to a new Mac

Because everything is re-downloadable, the simplest route is not to move the cache at all. If you want to, copy ~/.cache/huggingface/hub across with the same rsync -a approach, then run hf cache ls on the new Mac to confirm it reads cleanly. Log in again on the new Mac rather than copying the token file.

Why Spotlight cannot see it

~/.cache is a hidden folder under your home directory, and Spotlight does not return results from hidden folders. The blob files are also hash names, so a search for a model name would find nothing even if they were indexed.

Tracking a model file down by name

The repository folder names carry the readable part, so search on those. Typing models-- into Everywhere lists every cached repository folder at once, and adding part of an owner name, such as meta-llama, narrows it to one; ⌘↵ reveals it in Finder. Everywhere matches file and folder names only, not the model card text inside, which is why the models--owner--name scheme is the thing to type.

Common questions

Where is the Hugging Face cache on a Mac?

By default at ~/.cache/huggingface/hub. Each repository has its own folder such as models--org--name with blobs, snapshots and refs inside.

How do I change the Hugging Face cache location?

Set HF_HOME to move the whole Hugging Face folder, or HF_HUB_CACHE to move only the model cache, before running your Python code. Apps started from the Dock do not read ~/.zshrc.

How do I clear the Hugging Face cache on macOS?

Run hf cache ls to see sizes, then hf cache rm <repo> for a specific model or hf cache prune for unreferenced leftovers. Deleted models re-download when needed.

Why are the files in snapshots shortcuts?

The library stores each file once in blobs and uses symlinks in snapshots so several revisions can share it. Open files from snapshots, delete through the hf tool.