要約：クイックフィックス
ダウンロードの途中でストレージが不足するのは非常にストレスです。最も手っ取り早い解決策は、ダウンロード先を十分な空き容量があるドライブに変更することです。Pythonスクリプトを開始する前に、ターミナルで次のコマンドを実行してください。
export HF_HOME="/path/to/your/large/disk/huggingface"
あるいは、Hugging Faceライブラリをインポートする前に、Pythonスクリプト内で直接パスを設定することもできます。
import os
os.environ["HF_HOME"] = "/path/to/your/large/disk/huggingface"
エラーが発生する理由
最近のAIモデルは巨大です。from_pretrained()を呼び出すと、TransformersやDiffusersなどのライブラリは、標準的なブートドライブを簡単に圧迫してしまうほどの重みファイルをダウンロードします。ベースとなるBERTモデルは約400MB程度ですが、**Llama 3-8B (15GB)やStable Diffusion XL (6.5GB)**のような人気モデルは、かなりの容量を必要とします。
デフォルトでは、Hugging Faceはこれらのファイルをホームディレクトリ内に保存します。
- Linux/macOS:
~/.cache/huggingface - Windows:
C:\Users\username\.cache\huggingface
このエラーは、メインドライブ（通常はルートパーティション /）が上限に達したときに発生します。Dockerコンテナ、20GB程度の小さなブートディスクを持つクラウドVM、あるいはホームディレクトリのクォータ（割当量）が厳しいHPCクラスターなどで頻繁に発生する問題です。
ステップバイステップの解決策
1. キャッシュの場所を変更する（推奨）
キャッシュを外部ボリュームやデータパーティション（/mnt/data/など）に移動することが、最も持続的な解決策です。Hugging FaceはHF_HOME環境変数を参照してデータの保存場所を決定します。
オプションA：恒久的な変更（Linux/macOS）
~/.bashrcまたは~/.zshrcファイルを開き、次の行を追記します。
export HF_HOME="/mnt/external_drive/hf_cache"
source ~/.bashrcを実行して変更を適用します。
オプションB：スクリプト内での一時的な変更 共有マシンを使用している場合など、特定のプロジェクトに対してのみパスを変更したい場合があります。その場合は、スクリプトの最上部で環境変数を設定します。
import os
# transformersやdiffusersをインポートする前に設定する必要があります
os.environ["HF_HOME"] = "/mnt/data/huggingface_cache"
from transformers import AutoModel
model = AutoModel.from_pretrained("bert-base-uncased")
2. 既存のモデルの重みをクリーンアップする
古いバージョンのモデルや、失敗したダウンロードファイルがドライブを圧迫している可能性があります。huggingface-cliには、これらのファイルを特定して削除するためのツールが組み込まれています。
# CLIが未インストールの場合はインストールします
pip install -U "huggingface_hub[cli]"
# 対話型の削除ツールを起動します
huggingface-cli delete-cache
このツールはキャッシュされているモデルとそのサイズの一覧を表示します。削除したいバージョンを正確に選択して、数ギガバイトのスペースを解放できます。
3. シンボリックリンクを使用する
制限の厳しい本番環境などでは、環境変数を簡単に変更できないことがあります。そのような場合は、既存のフォルダを移動し、シンボリックリンクを使ってシステムを誘導します。
# 1. 大容量ディスクにディレクトリを作成
mkdir -p /mnt/large_disk/huggingface_cache
# 2. 既存のファイルを新しい場所に移動
mv ~/.cache/huggingface/* /mnt/large_disk/huggingface_cache/
# 3. 古いパスから新しい場所へリンクを貼る
rm -rf ~/.cache/huggingface
ln -s /mnt/large_disk/huggingface_cache ~/.cache/huggingface
4. Dockerコンテナのストレージ問題を解決する
Dockerコンテナは、書き込み可能なレイヤーのサイズが制限されている（多くの場合10GBや20GB）ことがよくあります。コンテナがいっぱいになるのを防ぐため、ホストのディレクトリをボリュームとしてマウントします。
docker run -it \
-v /home/user/my_large_disk:/cache_dir \
-e HF_HOME=/cache_dir \
my_ai_image
確認：解決したか？
ライブラリが実際に新しいパスを使用しているか確認しましょう。ターミナルでdf -hを使用して、各パーティションのディスク使用状況をリアルタイムで監視してください。
Pythonでパスを確認する： 次のスニペットを実行して、Hugging Faceが現在どこを参照しているかを確認します。
from huggingface_hub import constants
print(f"有効なHFキャッシュディレクトリ: {constants.HF_HUB_CACHE}")
出力結果に新しいディレクトリが反映されていれば、OSErrorは解決されるはずです。