TL;DR: The Quick Fix
Running out of storage mid-download is frustrating. The quickest fix is rerouting the download to a drive with more breathing room. Run this command in your terminal before starting your Python script:
export HF_HOME="/path/to/your/large/disk/huggingface"
Alternatively, set the path directly inside your Python script before importing any Hugging Face libraries:
import os
os.environ["HF_HOME"] = "/path/to/your/large/disk/huggingface"
Why This Error Happens
Modern AI models are massive. When you call from_pretrained(), libraries like Transformers or Diffusers download weights that can easily overwhelm a standard boot drive. While a base BERT model is only about 400MB, popular models like Llama 3-8B (15GB) or Stable Diffusion XL (6.5GB) require significant overhead.
By default, Hugging Face hides these files in your home directory:
- Linux/macOS:
~/.cache/huggingface - Windows:
C:\Users\username\.cache\huggingface
This error triggers when your primary drive—usually the root partition (/)—hits its limit. It's a frequent headache in Docker containers, cloud VMs with small 20GB boot disks, or HPC clusters with tight home directory quotas.
Step-by-Step Solutions
1. Change the Cache Location (Recommended)
Relocating the cache to an external volume or a data partition (like /mnt/data/) is the most sustainable fix. Hugging Face looks for the HF_HOME environment variable to decide where to store data.
Option A: Permanent Change (Linux/macOS)
Open your ~/.bashrc or ~/.zshrc file and append this line:
export HF_HOME="/mnt/external_drive/hf_cache"
Apply the changes by running source ~/.bashrc.
Option B: Temporary Script-Level Change If you are working on a shared machine, you might only want to change the path for one specific project. Set the environment variable at the very top of your script:
import os
# You must set this BEFORE importing transformers or diffusers
os.environ["HF_HOME"] = "/mnt/data/huggingface_cache"
from transformers import AutoModel
model = AutoModel.from_pretrained("bert-base-uncased")
2. Clean Up Existing Model Weights
You might have forgotten about old model versions or failed downloads cluttering your drive. The huggingface-cli includes a built-in tool to identify and purge these files.
# Install the CLI if you haven't already
pip install -U "huggingface_hub[cli]"
# Launch the interactive deletion tool
huggingface-cli delete-cache
This tool displays a list of cached models and their sizes. You can then select exactly which versions to delete to reclaim several gigabytes of space.
3. Using Symbolic Links
Sometimes you can't easily modify environment variables in a locked-down production environment. In these cases, move the existing folder and trick the system with a symbolic link.
# 1. Create a directory on the large disk
mkdir -p /mnt/large_disk/huggingface_cache
# 2. Move existing files to the new location
mv ~/.cache/huggingface/* /mnt/large_disk/huggingface_cache/
# 3. Link the old path to the new one
rm -rf ~/.cache/huggingface
ln -s /mnt/large_disk/huggingface_cache ~/.cache/huggingface
4. Fixing Docker Container Storage
Docker containers often have a limited "writable layer" size (frequently 10GB or 20GB). To avoid filling up the container, mount a host directory as a volume:
docker run -it \
-v /home/user/my_large_disk:/cache_dir \
-e HF_HOME=/cache_dir \
my_ai_image
Verification: Did It Work?
Check your work to ensure the library is actually using the new path. Use df -h in your terminal to monitor disk usage across your partitions in real-time.
Verify the path in Python: Run this snippet to see where Hugging Face is currently pointing:
from huggingface_hub import constants
print(f"Active HF cache directory: {constants.HF_HUB_CACHE}")
If the output reflects your new directory, the OSError should be resolved.