在 Mac 上檢查和清理 Hugging Face 快取

確認快取位置和必須保留的成果

常見 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 的快取。無法確認還原方式時先保留，也不要只憑存取時間判斷模型已無用。

用完整識別碼盤點並顯示警告

關閉使用該快取的應用程式、下載和工作。先執行 hf cache ls --no-truncate，再執行 hf cache ls --revisions --no-truncate --show-warnings；已確認版本預設隱藏詳細警告。自訂快取的所有命令必須使用相同 --cache-dir。解決無法讀取或結構異常的問題，記錄目錄用量和可用空間，私有儲存庫清單不要公開。

先預覽，再確認刪除

hf cache rm 的儲存庫目標使用 CLI 的完整 ID，模型保留 model/ 前綴，不能用磁碟上的 models-- 目錄名代替；若只刪除單一 revision，請使用完整 hash 並確認所屬儲存庫。先加 --dry-run，確認目標摘要與空間估計。它不是逐一列出檔案的清單，儲存庫目標會覆蓋其全部快取 revision。

範圍確認後才對相同目標與目錄移除 --dry-run，並保留確認提示。目標意外變化或預覽失敗時，停止刪除並查明原因。刪除直接生效，不進廢紙簍；還原需要備份或重新下載及持續存取權限。snapshot 和部分跨儲存庫的儲存結構會共用 blob，交給快取管理器處理，不能把顯示大小簡單相加。

謹慎使用 prune，並區分其他快取

hf cache prune --dry-run 在已確認的 2.0.0 版本中預覽 detached revision 與未完成下載。沒有具名參照不代表專案沒有固定使用該 revision；逐項確認，並停止正在進行的下載。第一次清理宜先處理一個明確目標。

HF_DATASETS_CACHE 管理的衍生資料與 Hub 下載不同；Xet 傳輸快取和 local_dir 匯出也要單獨處理。匯出目錄中的本機修改應保留。不要用刪除整個 HF_HOME 目錄來代替分類檢查。

驗證模型仍能使用

按相同方式重新測量，再載入保留的模型和 revision，執行預期結果已知的小型工作；只成功匯入 Python 函式庫不夠。需要離線使用時，請實際中斷網路連線進行驗證。失敗先停止清理，確認應用程式環境、路徑和所需檔案，再在確認存取權限與空間後還原。反覆下載同一必需模型說明清理目標或容量安排需要調整。

遷移外接磁碟時檢查空間、權限和符號連結支援，複製時保留連結及其目標；設定每個應用程式並驗證所需模型後才刪除原始檔，使用時保持磁碟連接。

驗證範圍

2026-09-29 使用 huggingface_hub 2.0.0 做了離線暫時建立的合成測試快取檢查：盤點、完整 ID、警告和 dry-run 可用，預覽不改檔案，刪除舊 revision 保留目前 revision 與共用資料。沒有驗證真實模型推論、使用者快取、跨儲存庫共用 blob 清理或遷移，不據此承諾可釋放多少空間。先用 hf cache --help 確認本機版本。

刪除前要確認甚麼

先確認實際路徑、用途和還原方式。下表不是自動刪除清單，也不承諾能釋放固定容量。

常見問題