How to change the Hugging Face cache directory

Set HF_HOME when you want to move the Hugging Face home and its default caches together. Set HF_HUB_CACHE when you only want to relocate downloaded Hub repositories. Copy the existing cache while downloads are stopped, make the variable persistent for the process that uses it, then verify a retained model before deleting anything.

HF_HOME and HF_HUB_CACHE are not interchangeable

Hugging Face exposes several cache variables because the local data is not all the same. The defaults are derived from HF_HOME, normally ~/.cache/huggingface unless XDG_CACHE_HOME changes it.

• HF_HOME moves the Hugging Face home used for locally stored token state and the default cache subdirectories.
• HF_HUB_CACHE moves the Hub repository cache—models, datasets and Spaces—whose default is $HF_HOME/hub.
• HF_XET_CACHE controls the Xet chunk cache, defaulting to $HF_HOME/xet.
• HF_ASSETS_CACHE controls downstream-library assets, defaulting to $HF_HOME/assets.

If your problem is downloaded model storage, HF_HUB_CACHE is the narrowest override. If you want one self-contained Hugging Face root on another disk, HF_HOME is easier to reason about—but remember that credentials and other state may then follow that root.

Inspect the active path before choosing a destination

Use the Hugging Face cache location guide to confirm existing environment variables and library-specific overrides. A notebook, service, container and interactive shell may not inherit the same environment. The path printed inside the actual workload is more useful than the value in a shell it never sees.

hf cache ls

# Python: see the Hub cache resolved by this environment
python -c "from huggingface_hub.constants import HF_HUB_CACHE; print(HF_HUB_CACHE)"

Stop active downloads and training jobs before copying. The cache contains snapshots and shared blobs; it is better to copy a stable tree than to chase new links while another process is changing it.

Make the new path persistent in the right environment

For a one-off test, set the variable in the current shell. For normal use, put it in the environment configuration that launches the workload: a shell profile, service unit, container definition, notebook kernel or application launcher.

# macOS or Linux: move only the Hub repository cache
export HF_HUB_CACHE="/mnt/ai-cache/huggingface/hub"

# Or move the whole Hugging Face home
export HF_HOME="/mnt/ai-cache/huggingface"

# PowerShell user environment variable
[Environment]::SetEnvironmentVariable(
  "HF_HUB_CACHE",
  "D:\AI-Cache\huggingface\hub",
  "User"
)

Restart the application after changing a persistent variable. Python libraries often resolve cache constants when imported; changing the environment halfway through a process may not redirect work already underway.

Copy, point, verify, then clean

1. Create the destination on a filesystem that supports the links and permissions your workloads require.
2. Copy the old cache into it without rearranging refs, snapshots or blobs.
3. Set the chosen environment variable and restart the workload.
4. Run hf cache ls --revisions and confirm the expected repository and revision appear.
5. Load one known model offline or use hf cache verify <repo> for a retained repository.
6. Perform a fresh small download and confirm the destination changes, not the source.

Keep the original cache through at least one clean restart. If verification fails, restore the previous variable and investigate the copy or permissions. Do not “fix” a failed migration by merging two partial caches manually.

Only then decide whether to clear the old cache

Once the destination is proven, the old copy may be redundant. If you also want to remove stale repositories or revisions inside the new cache, use the documented workflow to clear the Hugging Face cache safely. Relocation and pruning are different operations; combining them makes it harder to tell which action caused a missing model.

For irreplaceable model families, keep an intentional archive outside the live cache. Tensor Archive can retain related local artifacts, verify them and restore them exactly. It does not mutate the Hub cache or choose which revision your code should load.

Related storage answers

If the pressure comes from several runtimes rather than one cache, read how to organise one base model with many adapters. For a broader keep-or-delete decision, use the local model-library retention checklist.