AskClean問淨

如何在 Mac 上清除 Hugging Face 快取

AskClean 團隊 · 更新於 2026-11-02

要在 Mac 上回收 Hugging Face 快取的空間,先找出應用程式實際使用的快取,用 hf cache ls 盤點,再以 hf cache rm --dry-run 預覽特定的儲存庫或 revision。離線需要的模型與你自己的成果都要保留;不要手動刪除共用的 blob,也不要盲目刪掉整個 HF_HOME 資料夾。

多個模型 revision 連到共用資料區塊、專案檔案另外存放的概念圖
多個 revision 可能共用相同的檔案;自己的 checkpoint 與專案成果請另外保留。此圖為概念示意。

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

常見的 Hub 快取位於 ~/.cache/huggingface/hub。HF_HUB_CACHE 直接指定 Hub 儲存庫快取;HF_HOME 改變的是範圍更廣的 Hugging Face 主目錄,未設定 HF_HOME 時,XDG_CACHE_HOME 也會影響預設位置;應用程式還可以用 cache_dir 參數指定其他位置。GUI App、notebook 核心與命令列專案可能使用不同的環境設定,請分別檢查;預設的 Hub 目錄是空的,也不代表 Mac 上沒有模型。HF_HOME 可能包含驗證資訊,所以不要為了清除模型下載而刪掉整個目錄;需要求助時,只分享去除敏感值的相關設定。

下載的基礎模型也許還能重新取得,但你自己產生的東西——微調後的 checkpoint、adapter、tokenizer 修改、轉換結果、私有資料集、notebook、提示詞與專案設定——可能只存在這台 Mac 上。回收任何模型相關的空間前,先備份並驗證;有些備份工具會跳過標有 CACHEDIR.TAG 的快取,請確認備份真的包含你需要的檔案。不知道怎麼還原、怎麼讓應用程式恢復運作的項目,就先保留;也不要只憑存取時間判斷模型已經沒用。

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

先關閉使用候選快取的應用程式、下載與工作。執行 hf cache ls --no-truncate 列出完整的儲存庫 ID,再執行 hf cache ls --revisions --no-truncate --show-warnings,查看完整的 revision hash 與快取問題;在測試過的版本中,詳細警告預設是隱藏的。若使用自訂的 Hub 快取,每個指令都要加上相同的 --cache-dir。revision 顯示的大小可能大於刪除後實際釋放的空間,因為 snapshot 之間會共用資料,把大小相加可能重複計算同一批檔案。刪除前先查明無法讀取或不一致的項目,並記下目錄用量與可用空間;如果輸出會透露機密專案,請勿公開。

先預覽,再確認刪除

從盤點結果挑一個完整的儲存庫 ID 或 revision hash,先加上 --dry-run 執行 hf cache rm。模型儲存庫要保留 CLI 顯示的 model/ 前綴,磁碟上以 models-- 開頭的資料夾名稱不是同一個識別碼;只刪單一 revision 時,請使用完整的 hash,並確認它屬於哪個儲存庫。預覽會顯示目標摘要與預估釋放的空間,但不是逐一列出檔案的清單;以儲存庫為目標會涵蓋它所有快取的 revision,只想刪一個版本,就要以 revision 為目標。

確認範圍後,對相同的目標與快取目錄拿掉 --dry-run 再執行一次,並保留確認提示做最後檢查。如果清單意外改變,先確認是不是有其他應用程式重新啟動或下載了資料;預覽失敗就停下來查明原因。共用的 blob 與 snapshot 參照請交給 Hugging Face 的快取管理器處理,在 Finder 裡刪除個別檔案,可能影響其他需要它的 revision。快取刪除會直接刪掉檔案,不會移到垃圾桶;要還原只能靠可用的備份或重新下載。檢查通過之前請保留備份,尤其是私有、需申請存取(gated)、已下架、在本機修改過或離線需要的模型。

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

在驗證過的 2.0.0 版 CLI 中,hf cache prune --dry-run 會預覽 detached revision 與未完成的下載。detached revision 在快取裡沒有具名參照,但你的專案可能仍指定使用那個確切的 revision,核准刪除前請先檢查專案。在開發用 Mac 上第一次清理時,明確刪除單一目標比大範圍掃除更容易評估;之後若要 prune,請對所有候選套用同樣的檢查,並先停止進行中的下載——未完成的檔案可能只是另一個工作還在下載。

Hugging Face Datasets 會把處理後的資料存在自己的快取裡;HF_DATASETS_CACHE 與 HF_HUB_CACHE 管的範圍不同,刪除 Hub 下載不一定會刪到 Arrow 資料或轉換結果。用 local_dir 下載的檔案存放在你或應用程式選定的位置,請和共用的 Hub 快取分開處理;你在裡面新增的指令碼或修改過的檔案要先保存,重新下載不會還原本機的修改。Xet 傳輸儲存也是另外一塊。不要用刪除整個 HF_HOME 目錄來取代逐類檢查。

確認留下的模型仍能正常運作

重新做一次盤點與磁碟測量,然後載入你打算保留的模型與 revision,執行一個結果已知的小任務;只成功匯入 Python 函式庫,並不代表模型檔案沒問題。需要離線使用時,請實際中斷網路連線測試。如果下次執行又重新下載同一個模型,代表這次清理可能刪到工作仍需要的資料,該重新檢討選擇、儲存容量或快取位置。檢查失敗就暫停清理:記下模型、revision、快取路徑與錯誤,確認應用程式用的是你檢查過的環境;在確認存取權限與可用空間後,還原備份或重新下載需要的 revision,問題解決前不要再刪其他項目。

如果常用的模型超出 Mac 的容量,外接磁碟可能有幫助。請檢查可用空間、權限與符號連結支援(snapshot 透過符號連結指向共用的 blob),複製時保留這些連結與它們指向的檔案;把每個應用程式設定到新位置,並在那裡測試所需模型之後,才刪除原始資料。這些應用程式需要時,磁碟都必須保持連接。

我們如何驗證這些指令

我們在 2026-09-29 以 huggingface_hub 2.0.0,在離線的暫存資料夾裡建立一個 Hub 格式的測試快取,內含兩個合成 revision、一個共用 blob,以及每個 revision 各自專屬的 blob。revision 盤點成功;rm 與 prune 的 dry run 都沒有改動測試資料;刪除舊 revision 時保留了目前的 revision 與共用資料,只刪掉舊版專屬的 blob。另一次離線檢查也確認,--show-warnings 會顯示刻意弄壞的快取項目,--no-truncate 會保留完整的 revision ID。這些檢查沒有測試真實的模型下載、推論、使用者的快取、搬到外接磁碟,或跨儲存庫共用 blob 的清理,也無法預測你的 Mac 能釋放多少 GB。請先在自己的環境執行 hf cache --help;如果版本提供的指令或選項不同,請依該版本的文件操作。

AskClean 可以幫你看出 Mac 的儲存空間用在哪裡,並把 Hugging Face 模型逐一列出。掃描與預覽免費,AI 分析與清理需要 Pro;磁碟清理會永久刪除你確認的項目。快取的 revision 與共用檔案請用 Hugging Face CLI 管理,也別把原始的專案成果放進清理選擇。

哪些可以重建,哪些必須保留

請逐類檢查。這張表說明需要保留或還原什麼,並不是把檔案標記為自動刪除。

項目檢查位置刪除前要確認什麼
Hub 儲存庫或 revisionhf cache ls --revisions確認確切的選取範圍。還原可能需要重新下載,也需要同一儲存庫的存取權限。
共用的 blob 與 snapshot已確認的 Hub 快取交給快取管理器處理;revision 之間、在某些結構下連儲存庫之間,都可能共用相同的檔案。
detached revisionhf cache prune --dry-run即使快取裡沒有具名參照,專案仍可能需要那個確切的 revision。
產生的資料集快取HF_DATASETS_CACHE / Datasets 快取設定與 Hub 下載分開;重建可能需要處理時間與來源資料。
自訂 checkpoint、adapter 與原始檔你的專案與備份位置保留你的原始成果;尤其存放在快取目錄底下時,要確認備份有包含它。
Hugging Face 主目錄與驗證狀態HF_HOME不要為了刪除模型快取項目,而刪掉整個主目錄。

本機回歸測試使用的是很小的合成快取;它的大小不是效能基準,也不代表實際能省下多少空間。

常見問題

可以刪除 Mac 上的 ~/.cache/huggingface 嗎?

不要把整個目錄當成可以丟棄的東西。先找出作用中的 Hub 快取,保留驗證狀態與原始成果,再用已安裝的 hf cache 介面預覽明確的儲存庫或 revision。

刪除一個 revision,為什麼釋放的空間比顯示的少?

revision 之間可能共用檔案,有些快取結構甚至跨儲存庫共用。請參考預覽的預估值,並比較刪除前後的磁碟用量與可用空間;把顯示的 revision 大小相加,可能重複計算相同的檔案。

detached revision 就代表沒有應用程式在用嗎?

不是。即使快取裡沒有具名參照,專案仍可能固定使用某個確切的 revision。prune 之前請先確認專案的需求。

清理之後,模型還能離線使用嗎?

只有保留下來、而且完整的快取檔案,才能支援需要它們的工作。移除備份或依賴這台機器離線工作之前,請先實際測試一次具代表性的離線載入。

hf cache rm 會刪掉我微調的模型嗎?

如果你的自訂檔案位於選取的快取項目裡,就會。請把 checkpoint、adapter 與修改過的檔案放在要刪除的項目之外,並確認它們的備份。資料夾名稱叫 cache,裡面仍可能是你重要成果的唯一副本。

參考來源

更多模型與開發者儲存空間指南