Mac の Hugging Face キャッシュを確認して整理する
AskClean チーム · 更新日 2026-09-29
アプリが使うキャッシュを確認し、hf cache ls で一覧を調べ、hf cache rm --dry-run で明確な対象をプレビューします。オフラインで必要なモデルと自作データは残してください。共有 blob を手動で削除したり、HF_HOME 全体を消したりしないでください。
保存先と残すデータを確認する
一般的な Hub キャッシュは ~/.cache/huggingface/hub です。HF_HUB_CACHE はリポジトリの保存先、HF_HOME はより広いホーム領域を指定します。HF_HOME が未設定なら XDG_CACHE_HOME が標準の場所に影響し、アプリの cache_dir で変更されることもあります。GUI、ターミナル、notebook の環境を個別に確認します。HF_HOME には認証情報も含まれるため、全体の削除や内容の公開は避けてください。
微調整した checkpoint、adapter、tokenizer の変更、変換結果、非公開データ、プロジェクト設定は再取得できない場合があります。CACHEDIR.TAG 付きのキャッシュを除外するバックアップツールもあるので、必要なファイルが実際に保管されているか確認します。復元方法が不明なものは残し、アクセス日時だけで不要と判断しないでください。
省略されていない ID と警告を確認する
キャッシュを使うアプリ、ダウンロード、処理を停止します。hf cache ls --no-truncate に続いて hf cache ls --revisions --no-truncate --show-warnings を実行してください。検証した版では詳細な警告が標準で非表示です。独自の保存先には毎回同じ --cache-dir を指定します。読み取りや構造の問題を調べ、使用量と空き容量を記録し、非公開リポジトリの一覧は公開しないでください。
範囲をプレビューしてから削除する
hf cache rm には CLI の完全な ID を指定します。モデルでは model/ を残し、ディスク上の models-- で始まるフォルダ名を使わないでください。単一リビジョンには完全な hash を使い、所属リポジトリも確認します。まず --dry-run で対象の要約と推定容量を読みます。ファイル単位の一覧ではなく、リポジトリ指定はその全キャッシュリビジョンが対象です。
確認後に同じ対象と保存先で --dry-run を外し、最終確認のプロンプトは有効にしておきます。対象が変わったりプレビューが失敗したりしたら、削除を止めて原因を調べます。削除したファイルはごみ箱に入らず、復元にはバックアップか再取得権限が必要です。snapshot 間、構造によってはリポジトリ間でも blob を共有するため、キャッシュ管理機能に任せ、表示容量を単純合計しないでください。
prune とほかのキャッシュを区別する
検証した 2.0.0 の hf cache prune --dry-run は detached リビジョンと未完了ダウンロードをプレビューします。名前付き参照がなくてもプロジェクトがその版を固定している場合があります。各対象を確認し、進行中のダウンロードを止めてください。最初は明確な一対象から整理します。
HF_DATASETS_CACHE の生成データは Hub のダウンロードと別です。Xet 転送キャッシュや local_dir の出力も分けて確認し、出力先での変更を残します。分類の代わりに HF_HOME 全体を削除しないでください。
残したモデルで処理を確かめる
同じ方法で測定し直し、残したモデルとリビジョンを読み込んで既知の小さな処理を実行します。Python ライブラリをインポートできるだけでは不十分です。オフライン利用が必要なら実際にネットワークを切って確認します。失敗時は整理を止め、環境、保存先、必要なファイルを確認してから復元します。必要なモデルの削除と再ダウンロードを繰り返す場合は、対象や容量計画を見直します。
外付けドライブへ移す場合は容量、権限、シンボリックリンクへの対応を確認し、リンクと参照先を保ってコピーします。各アプリで新しい場所と必要なモデルを検証してから元のコピーを削除し、利用中はドライブを接続しておきます。
検証した範囲
2026-09-29 に huggingface_hub 2.0.0 と一時的な合成キャッシュを使い、オフラインで一覧、完全な ID、警告、dry-run を確認しました。プレビューはファイルを変更せず、古いリビジョンの削除後も現行版と共有データが残りました。実モデルの推論、ユーザーのキャッシュ、リポジトリ間の共有 blob の削除、移行は検証していません。容量削減の保証ではありません。手元の版は hf cache --help で確認してください。
削除前に確認すること
実際の保存先、用途、復元方法を確認してください。この表は自動削除の対象一覧ではなく、一定量の空き容量を保証するものでもありません。
| 対象 | 確認場所 | 削除の影響と保持条件 |
|---|---|---|
| リポジトリとリビジョン | hf cache ls --revisions | 対象範囲と再取得に必要なアクセスを確認します。 |
| 共有データ | blob / snapshot | 参照関係を管理機能に任せ、表示容量を単純合計しません。 |
| Detached リビジョン | hf cache prune --dry-run | プロジェクトが正確な版を指定している場合があります。 |
| 生成済みデータセット | HF_DATASETS_CACHE | 再生成には元データと処理時間が必要です。 |
| 独自モデルと成果物 | checkpoint / adapter | 原本を残し、バックアップに実体が含まれるか確認します。 |
| Hugging Face のホーム | HF_HOME | 認証情報も含むため、全体は削除しません。 |
よくある質問
detached なら不要なリビジョンですか？
いいえ。名前付き参照がなくても、プロジェクトが特定のリビジョンに固定されている場合があります。依存関係を調べてから判断します。
hf cache rm は微調整したモデルも消しますか？
選択した対象内にあれば削除される可能性があります。対象から外し、バックアップを検証してください。cache という名前は、内容が不要である証拠にはなりません。
参考資料