Hugging Face cache paths: set variables before import
TL;DR: Set Hugging Face cache variables before starting the Python process that imports the Hub client. Inspect resolved paths in that same environment before downloading again. HF_HOME and HF_HUB_CACHE control different scopes, and changing a notebook cell after import can leave the process using its earlier configuration.
What you’ll have running after this guide:
- A small report of resolved Hub paths without printing authentication values.
- A reproducible check of early configuration versus a late environment change.
- A storage plan that distinguishes repository cache, Xet cache, and exported files.
Honest take: Verify the active cache path before paying for more disk or fetching another copy of model weights.
Why does Hugging Face keep using the old cache folder?
The Hub client reads its environment configuration at import time. Changing an environment variable after the relevant modules have loaded does not reconfigure their existing constants. The official environment-variable reference, checked November 13, 2026, states that variables should be set before import.
This is easy to encounter in notebooks, application servers, and persistent Python workers. You import a library, discover that the default disk is too small, set HF_HOME in a later cell, and assume the next operation moved. The shell or notebook environment may now contain the new string while the imported Hub module still holds the earlier path.
Inspect both the process boundary and the resolved constants. A new terminal command, an already-running notebook kernel, and a service launched by another account are different environments. A path printed by your login shell does not prove that the inference process uses that path.
The inspection below needs an existing Python environment with huggingface_hub installed. It performs no download and requires no GPU. Our local test used Hub client 2.4.0, whose release page and tagged source were checked that day. This is the tested version, not a claim that every reader must upgrade to it.
Which variable should you set for the storage you want to move?
Use HF_HUB_CACHE when the intended change is the repository cache location. Use HF_HOME deliberately when you want to change the Hub client’s broader home directory and its default child paths. The two variables are related but are not interchangeable names for one directory.
| Setting | Documented scope | Default relationship when not overridden |
|---|---|---|
HF_HOME | Hub client data home, including its default authentication-file location | Based on the user’s cache directory |
HF_HUB_CACHE | Cached Hub repositories | HF_HOME plus /hub |
HF_XET_CACHE | Xet shard cache and upload staging data | HF_HOME plus /xet |
HF_ASSETS_CACHE | Assets created by downstream libraries | HF_HOME plus /assets |
These relationships come from the current documentation and the 2.4.0 constants implementation. An explicitly configured repository-cache variable can continue to point elsewhere after you change HF_HOME. Check effective values instead of assuming the directory tree moved as a unit.
The authentication-file location matters for privacy. A broad Hub home directory can include private authentication material as well as caches. Do not copy that entire directory into a public project, container image, or shared report as if it contained only model files. The reporter below prints selected paths and an offline flag; it never reads or prints token contents.
How can you inspect the actual Python environment safely?
Run a short reporter with the same interpreter and launch configuration as the application you are diagnosing. A command run in another virtual environment can identify a different package version and different settings.
Save this as show_hf_paths.py:
import json
import sys
from huggingface_hub import __version__, constants
print(json.dumps({
"python": sys.executable,
"huggingface_hub": __version__,
"HF_HOME": constants.HF_HOME,
"HF_HUB_CACHE": constants.HF_HUB_CACHE,
"HF_XET_CACHE": constants.HF_XET_CACHE,
"HF_HUB_OFFLINE": constants.HF_HUB_OFFLINE,
}, indent=2))
Invoke it with your application’s Python interpreter:
/path/to/venv/bin/python show_hf_paths.py
The output includes the interpreter path, client version, selected resolved paths, and Hub offline flag. It does not scan the filesystem, load a model, or enumerate environment variables. Paths themselves can identify a local username or directory layout, so redact them if sharing a report outside your environment.
For a running notebook, execute the same reporter in the kernel to inspect what that process has already imported. Then compare it with a fresh process launched using the intended environment. Restarting a kernel loses its in-memory state; save work before doing so. Do not repeatedly reload internal modules and assume every importing library picked up the new values consistently.
How do you apply the setting before import?
Set the repository-cache location in the process launch environment, then start Python. This example selects only the Hub repository cache:
HF_HUB_CACHE=/absolute/private/model-cache \
/path/to/venv/bin/python show_hf_paths.py
The example path is a placeholder, not a directory this article creates or a promise of available disk space. Select an existing storage location appropriate for your account, permissions, and application. Confirm the report before any transfer. Setting this variable does not move existing files from the old cache.
For a broader home change, use a separate check:
HF_HOME=/absolute/private/hf-home \
/path/to/venv/bin/python show_hf_paths.py
If HF_HUB_CACHE is already explicitly set in that launch environment, it can override the derived repository path. Inspect configuration in your launcher or service definition rather than dumping all environment values to a log; unrelated variables may contain credentials. Apply equivalent settings through your own deployment process when launching a container or service.
An environment variable set in an interactive shell does not alter a service that is already running. The fix belongs at that service’s next deliberate launch boundary, followed by the same resolved-path check. Avoid changing a host-wide setting for every application when only one workload needs a different disk.
What did the import-order experiment show?
The local November 13 test used temporary path names and the actual installed Hub client 2.4.0. It imported the constants, changed the environment afterward, and compared that result with a fresh child process. No model weights, cached credentials, or network requests were involved.
The table uses FIRST and SECOND as labels for temporary absolute directories:
| Experiment | Resolved HF_HOME | Resolved repository cache |
|---|---|---|
Set HF_HOME=FIRST before import | FIRST | FIRST/hub |
Import with FIRST, then assign HF_HOME=SECOND | FIRST | FIRST/hub |
Launch a fresh process with HF_HOME=SECOND | SECOND | SECOND/hub |
Set HF_HOME=FIRST and an explicit Hub cache | FIRST | The explicit repository-cache path |
The explicit-cache case kept Xet’s derived path at FIRST/xet. This demonstrates why relocating the repository cache alone is not a claim that every part of the download stack now writes to the same disk. The test also confirmed that simply reporting these constants did not create the temporary cache directories.
Those results establish configuration behavior for the tested version. They are not a model download benchmark, evidence of a storage leak, or a promise that changing one setting will recover a particular amount of disk. Files already present elsewhere remain a separate inventory problem.
How does cache choice change your disk budget?
Separate cache reuse from independent exports and backups. The cache-management guide describes repository caches and their revisions. Shared cached content can reduce repeated storage within that layout, but another account, container volume, or separately configured location may not reuse the same files.
Use measured sizes for your own artifact set. If your selected files occupy a hypothetical 12 GB, keeping independent full copies in two unrelated directories requires 24 GB for those copies before additional cache or application overhead. Adding a third full copy makes that 36 GB. This is illustrative arithmetic, not the size of a model fetched in our test or a measurement of deduplicated physical blocks.
Before downloading again, ask whether the expected revision is already available in the intended cache, whether the application can access that location, and whether its launcher points there. A wrong path can turn an apparent cache miss into an unnecessary second transfer. Correct configuration does not guarantee a cache hit: the repository, revision, filename, and chosen layout still need to match.
Use the download dry-run guide to inspect a prospective transfer. The dry run belongs in the same environment you just verified. A dry run from a different virtual environment or account can answer a different storage question.
Is a local export the same as a shared cache?
A local export and a repository cache serve different purposes. The download guide distinguishes local_dir from cache-oriented downloads. Choosing a local destination does not mean every library will discover that export automatically, and changing HF_HUB_CACHE does not relocate an export you already created.
For a portable folder, inspect the actual files and link behavior. The snapshot-copy guide explains why copying only a cache snapshot can preserve links whose targets remain in the old location. A correct environment report does not repair those links or prove that a model folder is complete.
Keep reproducibility records independently of the directory name. Record the selected repository, full revision, required file set, and application environment. The offline backup guide covers that recovery boundary. Moving a cache and making a recoverable backup are different jobs.
Honest take: when should you avoid this approach?
Do not treat environment configuration as a filesystem migration, a model validator, or a complete offline guarantee. HF_HUB_OFFLINE describes the Hub client’s behavior; it does not block network access by every application component. A path report does not check write permissions, free space, model compatibility, or successful loading.
Avoid manually copying authentication material merely to make a new cache path look like the old home directory. Preserve private data through your established account procedures. A repository-only cache setting may be the smaller change when storage is the actual problem, but confirm your application’s full configuration before deploying it.
The Hub client is Apache 2.0 licensed. That license applies to the client code, not automatically to downloaded weights, datasets, or custom model code. Moving files does not change their terms.
For a disk-bound self-hosted setup, inspect first and transfer second. Confirm the active interpreter and resolved cache, decide which storage scope should change, and restart deliberately with the intended environment. Buy additional storage only after the resulting inventory shows that you actually need it.
Sources
- Environment variables and import timing — Hugging Face
- Cache management — Hugging Face
- Download destinations and cache options — Hugging Face
- Client 2.4.0 constants — tagged official source
- Client 2.4.0 release — Hugging Face
- Client Apache 2.0 license — Hugging Face
Last updated November 13, 2026. Official references and local import-order fixtures were checked on this date. No model weights were downloaded, no inference was run, and no hardware capacity or monetary saving was measured.
Was this article helpful?
Thanks for the feedback — it helps improve future articles.
Need hands-on help?
I offer 1-on-1 technical consulting for local AI setup, GPU selection, and AI coding tool configuration — same topics covered on this site.
Book a session — $49 / hour →What self-hosting actually costs
Real cost breakdowns for self-hosted AI: hardware floors, power, maintenance hours, and the honest comparison against paying for it. No spam, unsubscribe anytime.