Hugging Face のキャッシュディレクトリを変更する方法

Hugging Face のホームと既定キャッシュをまとめて移動する場合は HF_HOME を設定します。ダウンロード済み Hub リポジトリだけを移設する場合は HF_HUB_CACHE を設定します。ダウンロードを停止した状態で既存キャッシュをコピーし、使用するプロセスで変数を永続化し、何かを削除する前に保持済みモデルを検証します。

HF_HOME と HF_HUB_CACHE は同じ意味ではありません

Hugging Face が複数のキャッシュ変数を公開しているのは、ローカルデータがすべて同じではないからです。既定値は HF_HOME から導出され、XDG_CACHE_HOME で変更されない限り、通常は ~/.cache/huggingface です。

• HF_HOME は、ローカル保存されたトークン状態および既定のキャッシュサブディレクトリが使用する Hugging Face ホームを移動します。
• HF_HUB_CACHE は Hub リポジトリキャッシュ（モデル、データセット、Spaces）を移動します。既定値は $HF_HOME/hub です。
• HF_XET_CACHE は Xet のチャンクキャッシュを制御し、既定値は $HF_HOME/xet です。
• HF_ASSETS_CACHE は下流ライブラリのアセットを制御し、既定値は $HF_HOME/assets です。

問題がダウンロード済みモデルのストレージなら、HF_HUB_CACHE が最も範囲の狭い上書きです。Hugging Face のルート全体を別のディスクに自己完結させたいなら、HF_HOME の方が分かりやすくなります。ただし、認証情報やその他の状態もそのルートに移る可能性があることを忘れないでください。

保存先を選ぶ前に有効なパスを確認

Hugging Face キャッシュ場所ガイドを使い、既存の環境変数およびライブラリ固有の上書きを確認します。ノートブック、サービス、コンテナ、対話型シェルは同じ環境を継承しない場合があります。実際の作業内で表示されたパスは、その作業が参照しないシェルの値より有用です。

hf cache ls

# Python：この環境が解決した Hub キャッシュを確認
python -c "from huggingface_hub.constants import HF_HUB_CACHE; print(HF_HUB_CACHE)"

コピー前に進行中のダウンロードおよびトレーニングジョブを停止します。キャッシュにはスナップショットと共有ブロブが含まれます。別のプロセスが変更している最中に新しいリンクを追うより、安定したツリーをコピーする方が安全です。

適切な環境で新しいパスを永続化

一回限りのテストでは、現在のシェルで変数を設定します。通常利用では、作業を起動する環境設定（シェルプロファイル、サービスユニット、コンテナ定義、ノートブックカーネル、またはアプリケーションランチャー）に設定します。

# macOS または Linux：Hub リポジトリキャッシュだけを移動
export HF_HUB_CACHE="/mnt/ai-cache/huggingface/hub"

# または Hugging Face のホーム全体を移動
export HF_HOME="/mnt/ai-cache/huggingface"

# PowerShell のユーザー環境変数
[Environment]::SetEnvironmentVariable(
  "HF_HUB_CACHE",
  "D:\AI-Cache\huggingface\hub",
  "User"
)

永続変数を変更したら、アプリケーションを再起動してください。Python ライブラリはインポート時にキャッシュ定数を解決することがよくあります。プロセスの途中で環境を変更しても、進行中の作業は転送先を変更しない場合があります。

コピー、指定、検証、それから整理

1. 作業が必要とするリンクおよび権限に対応したファイルシステム上に保存先を作成します。
2. refs、snapshots、または blobs を並べ替えずに、古いキャッシュをコピーします。
3. 選択した環境変数を設定し、作業を再起動します。
4. hf cache ls --revisions を実行し、想定したリポジトリおよびリビジョンが表示されることを確認します。
5. 既知のモデルを一つオフラインで読み込むか、保持済みリポジトリには hf cache verify <repo> を使用します。
6. 新しく小容量のダウンロードを行い、ソースではなく保存先が変わったことを確認します。

少なくとも一回正常に再起動できるまでは元のキャッシュを保持してください。検証に失敗した場合、以前の変数に戻してコピーまたは権限を調査します。二つの不完全なキャッシュを手作業で結合して、失敗した移行を「修正」しないでください。

その後で初めて、古いキャッシュを消去するか判断する

保存先の動作を確認できたら、古いコピーは重複となる場合があります。新しいキャッシュ内の古いリポジトリまたはリビジョンも削除するなら、文書化された手順でHugging Face のキャッシュを安全に消去してください。移設と整理は別の操作です。組み合わせると、モデル欠落の原因となった操作を特定しにくくなります。

置き換え不能なモデルファミリーは、稼働中のキャッシュ外に意図的なアーカイブを保持してください。Tensor Archive は関連するローカル成果物を保持、検証し、完全に復元できます。Hub キャッシュを変更したり、コードが読み込むべきリビジョンを選んだりはしません。

関連するストレージの回答

負荷の原因が一つのキャッシュではなく複数のランタイムにある場合は、一つのベースモデルを多数のアダプターと整理する方法をお読みください。より広い保持・削除の判断には、ローカルモデルライブラリ保持チェックリストを使用してください。