Changing the Hugging Face Model Cache Directory (HF_HOME) to Prevent Disk Exhaustion (Error 904)
Are large weights eating up all your disk space? Learn how to override the Hugging Face cache folder configuration and store weights on high-capacity secondary drives.
Dealing with Disk Space Depletion from Large AI Models
Downloading open-weights models (such as stable diffusion, whisper, or llama-3) through Hugging Face compilers quickly fills up system drives. By default, Hugging Face saves downloaded repositories in a hidden user subdirectory (~/.cache/huggingface). On Windows, this is located on your OS drive which can rapidly trigger disk space alerts.
# Step 1: Override Directory Using HF_HOME Variable
You can re-route the downloads globally to a secondary partition or external storage drive by setting environment variables before launching your scripts.
For Linux/macOS:
Edit ~/.bashrc or ~/.zscrc and append:
``
export HF_HOME="/mnt/storage_drive/huggingface"
`
Run source ~/.bashrc to finalize the setting.
For Windows:
1. Open system settings and find "Edit system environment variables".
2. Under User Variables, clicked "New".
3. Set Variable Name to HF_HOME and Variable Value to D:\AI_Models\huggingface (or path to your larger storage drive).
# Step 2: Backwards Compatibility for Old Packages
Older packages might still look for the legacy variable. To be safe, set the older cache variable too:
# Step 3: Clean up and Transfer Existing Weights
Once variables are confirmed, you can securely cut the previous folder content and paste it into the new directory to avoid re-downloading existing model weights. Delete the previous cache from your boot partition to immediately recover dozens of gigabytes.