AskClean

Mac の Hugging Face キャッシュを安全に削除する方法

AskClean チーム · 更新日 2026-11-02

Mac で Hugging Face キャッシュの容量を空けるには、まずアプリが実際に使っているキャッシュを特定し、hf cache ls で中身を確認してから、hf cache rm --dry-run で削除するリポジトリやリビジョンをプレビューします。オフラインで必要なモデルと自作のデータは残してください。共有 blob を手作業で消したり、HF_HOME フォルダ全体をむやみに削除したりしないでください。

モデルのリビジョンが共有データにつながり、プロジェクトファイルが別に保管されている概念図
複数のリビジョンが同じファイルを共有することがあります。独自のチェックポイントやプロジェクトは別に保管します。概念図です。

保存先と残すデータを確認する

一般的な Hub キャッシュは ~/.cache/huggingface/hub です。HF_HUB_CACHE は Hub のリポジトリキャッシュの場所を直接指定し、HF_HOME は Hugging Face のホームディレクトリ全体を変更します。HF_HOME が未設定なら XDG_CACHE_HOME が既定の場所に影響し、アプリの cache_dir 引数で別の場所が選ばれることもあります。GUI アプリ、ノートブックのカーネル、コマンドラインのプロジェクトは環境設定が異なる場合があるため、それぞれを起動する環境で確認してください。既定の Hub フォルダが空でも、Mac にモデルがないとは限りません。HF_HOME には認証情報が入っていることもあるため、モデルのダウンロードを消す目的でフォルダ全体を削除したり、中身をそのまま共有したりしないでください。

モデルを削除する前に、どのアプリや Python 環境がそれを使うか、プロジェクトがどのリビジョンを必要とするか、オフラインで使うかを確認します。微調整したチェックポイント、アダプター、トークナイザーの変更、変換結果、非公開のデータセット、ノートブック、プロンプト、プロジェクト設定は、再ダウンロードしても戻らないため、整理の前にバックアップしてください。CACHEDIR.TAG の付いたキャッシュを除外するバックアップツールもあるため、必要なファイルが実際にバックアップに含まれているか確かめてください。復元してアプリを再び動かす方法が分からないものはいったん残し、用途の分かっている小さなキャッシュから始めます。アクセス日時が古いというだけで不要と判断しないでください。

リポジトリとリビジョンを一覧で確認する

キャッシュを使っているアプリ、ダウンロード、ジョブを止めてから、hf cache ls --no-truncate を実行し、続けて hf cache ls --revisions --no-truncate --show-warnings を実行します。検証したバージョンでは、詳細な警告は既定で表示されません。独自の保存先を使う場合は、すべてのコマンドに同じ --cache-dir を指定します。読み取れないエントリや整合性のないエントリの警告は、削除の前に調べてください。スキャンが完了しても、すべてのファイルが認識されたとは限りません。作業前のフォルダサイズと空き容量を記録し、非公開のプロジェクトが分かる出力は外部に公開しないでください。

範囲をプレビューしてから削除する

hf cache rm には、一覧に表示された完全なリポジトリ ID かリビジョンのハッシュを 1 つ指定し、まず --dry-run を付けて実行します。モデルのリポジトリでは、CLI が表示する model/ の接頭辞を残してください。ディスク上の models-- で始まるフォルダ名は、同じ識別子ではありません。1 つのリビジョンだけを削除するときは完全なハッシュを使い、どのリポジトリに属するかも確認します。プレビューに表示されるのは対象の概要と削減容量の見積もりで、ファイル単位の一覧ではありません。リポジトリを指定すると、キャッシュされたすべてのリビジョンが対象になります。

範囲を確認したら、同じ対象と保存先のまま --dry-run を外して実行します。最終確認のプロンプトは有効にしておきます。対象が予想外に変わったり、プレビューが失敗したりしたら、削除をやめて原因を調べてください。スナップショット同士、構成によってはリポジトリ同士でも blob を共有するため、共有ファイルの扱いはキャッシュ管理機能に任せ、表示された容量を単純に合計しないでください。削除したファイルはゴミ箱に入らず、元に戻すにはバックアップか再ダウンロードが必要です。非公開、アクセス制限付き、公開終了、ローカルで変更済み、オフラインで必要なモデルは、確認が済むまでバックアップを残してください。

prune とほかのキャッシュを区別する

検証した 2.0.0 の CLI では、hf cache prune --dry-run で detached リビジョンと未完了のダウンロードをプレビューできます。名前付きの参照がないリビジョンでも、プロジェクトがその正確なリビジョンを指定している場合があります。候補をすべて確認し、ダウンロード中の処理を止めてから判断してください。開発用 Mac での最初の整理は、広く一掃するより、明確な対象を 1 つ削除するほうが結果を評価しやすくなります。

HF_DATASETS_CACHE にある Datasets の加工済みデータは、Hub のダウンロードとは別です。Xet の転送キャッシュや、local_dir で保存したファイルも別に確認し、その保存先で加えた変更は残してください。再ダウンロードしても、手元の編集は戻りません。分類する代わりに HF_HOME 全体を削除しないでください。

残したモデルで処理を確かめる

同じ方法で使用量と空き容量を測り直し、残すと決めたモデルとリビジョンを読み込んで、結果の分かっている小さな処理を実行します。Python のライブラリをインポートできるだけでは、モデルのファイルを確認したことになりません。オフラインで使う必要があるなら、実際にネットワークを切って確認してください。確認に失敗したら整理を止め、アプリが確認した環境を使っているか、削除したファイルを必要としていないかを調べてから、バックアップを戻すか必要なリビジョンを再ダウンロードします。必要なモデルの削除と再ダウンロードを繰り返すようなら、対象の選び方、容量、キャッシュの置き場所を見直します。

外付けドライブへ移す場合は、空き容量、アクセス権、シンボリックリンクへの対応を確認し、リンクと参照先の両方を保ったままコピーします。各アプリで新しい場所と必要なモデルを確認してから元のコピーを削除し、それらのアプリを使うときはドライブを接続しておきます。

検証した範囲

2026-09-29 に、huggingface_hub 2.0.0 と一時的な合成キャッシュを使い、オフラインで一覧表示、完全な ID、警告、dry-run を確認しました。プレビューはファイルを変更せず、古いリビジョンを削除した後も、現行のリビジョンと共有データは残りました。実際のモデルのダウンロードや推論、利用者のキャッシュ、リポジトリ間で共有された blob の削除、ドライブへの移行は検証していません。空く容量を保証するものでもありません。お使いの環境では、まず hf cache --help でコマンドを確認してください。

AskClean を使うと、Mac のどこで容量が使われているかを確認できます。スキャンとプレビューは無料で、AI 分析とクリーンアップには Pro が必要です。ディスククリーンアップで確定した項目は、ゴミ箱に移動せず完全に削除されます。キャッシュされたリビジョンと共有ファイルの管理には Hugging Face の CLI を使い、自分のプロジェクトのデータはクリーンアップの対象に含めないでください。

作り直せるものと、残すべきもの

カテゴリごとに確認してください。この表は、残すべきものと復元に必要なものを説明するもので、自動削除の対象を示すものではありません。

対象確認する場所削除する前に確認すること
リポジトリとリビジョンhf cache ls --revisions選択した範囲を正確に確認します。復元するには、再ダウンロードと同じリポジトリへのアクセスが必要になることがあります。
共有 blob とスナップショット確認済みの Hub キャッシュキャッシュ管理機能を使います。リビジョン同士、構成によってはリポジトリ同士で、同じファイルを共有しています。
detached リビジョンhf cache prune --dry-runキャッシュに名前付きの参照がなくても、プロジェクトがその正確なリビジョンを必要とすることがあります。
生成済みのデータセットキャッシュHF_DATASETS_CACHE / Datasets のキャッシュ設定Hub のダウンロードとは別です。作り直すには、処理時間と元のデータが必要になることがあります。
独自のチェックポイント、アダプター、元データプロジェクトとバックアップの保存先原本は残します。特にキャッシュフォルダの下に置いている場合は、バックアップに含まれているかを確かめます。
Hugging Face のホームと認証情報HF_HOMEモデルのキャッシュを消すために、ホームディレクトリ全体を削除しないでください。

ローカルでの回帰テストには、ごく小さな合成キャッシュを使いました。そのサイズはベンチマークでも、実際に空く容量の見積もりでもありません。

よくある質問

Mac の ~/.cache/huggingface は削除できますか?

フォルダ全体を不要なものとして扱わないでください。使用中の Hub キャッシュを特定し、認証情報と自作のデータを残したうえで、インストールされている hf cache のコマンドで、対象のリポジトリやリビジョンを明示してプレビューします。

リビジョンを 1 つ削除しても、表示されたサイズほど空かないのはなぜですか?

リビジョン同士、構成によってはリポジトリ同士でも、ファイルを共有していることがあります。プレビューの見積もりを確認し、作業の前後でディスクの使用量と空き容量を比べてください。表示されたリビジョンのサイズを合計すると、同じファイルを重複して数えることがあります。

detached なら不要なリビジョンですか?

いいえ。キャッシュに名前付きの参照がなくても、プロジェクトがその正確なリビジョンを指定している場合があります。prune する前に、プロジェクトの要件を確認してください。

整理した後も、モデルをオフラインで使えますか?

使えるのは、残した完全なキャッシュファイルがある場合だけです。バックアップを削除したり、ネットワークのない環境で Mac を使ったりする前に、代表的なモデルをオフラインで読み込めるか確かめてください。

hf cache rm は微調整したモデルも削除しますか?

選択したキャッシュエントリの中に自作のファイルがあれば、削除されることがあります。チェックポイント、アダプター、変更したファイルは削除予定のエントリの外に置き、バックアップを確認してください。cache という名前のフォルダにも、大切な作業の唯一のコピーが入っていることがあります。

参考資料

モデルと開発者ストレージに関するほかのガイド