如何在 Mac 上安全清理 Hugging Face 缓存
AskClean 团队 · 更新于 2026-11-02
要在 Mac 上回收 Hugging Face 缓存占用的空间,先确认应用实际使用的是哪个缓存,用 hf cache ls 盘点,再用 hf cache rm --dry-run 预览某个具体的仓库或 revision。离线要用的模型和你自己的成果要保留;不要手动删除共享的 blob,也不要整个删除 HF_HOME 文件夹。

找到实际使用的缓存,先保护你自己的成果
常见的 Hub 缓存位置是 ~/.cache/huggingface/hub。HF_HUB_CACHE 直接指定 Hub 仓库缓存,HF_HOME 改变的是范围更大的 Hugging Face 主目录;未设置 HF_HOME 时,XDG_CACHE_HOME 也会影响默认位置;应用还可以用 cache_dir 参数另选位置。图形界面应用、终端和 notebook 可能使用不同的环境设置,要分别检查。HF_HOME 里可能有认证信息,不要为了清模型下载而把整个目录删掉,也不要公开其中的内容。
微调得到的 checkpoint、adapter、修改过的 tokenizer、转换结果、私有数据和项目配置,可能无法重新下载。动手前先备份并确认备份可用;有些备份工具会跳过带 CACHEDIR.TAG 标记的缓存目录。不确定怎样恢复的项目先保留,也不要只凭访问时间就认定某个模型已经没用。
用完整标识盘点,并显示警告
先关闭正在使用该缓存的应用、下载和任务。运行 hf cache ls --no-truncate 列出完整的仓库标识,再运行 hf cache ls --revisions --no-truncate --show-warnings 查看完整的 revision 哈希和缓存中的问题——在核对过的版本里,详细警告默认是隐藏的。使用自定义缓存时,每条命令都要带上相同的 --cache-dir。删除之前先解决无法读取或结构异常的条目,记下目录大小和可用空间;私有仓库的清单不要外传。
先预览,再确认删除
hf cache rm 的仓库目标要用 CLI 显示的完整 ID:模型仓库保留 model/ 前缀,不能用磁盘上以 models-- 开头的文件夹名代替;只删一个 revision 时,使用完整的哈希,并核对它属于哪个仓库。先加上 --dry-run,确认目标摘要和预计释放的空间。预览不是逐个文件的清单;以整个仓库为目标,会删除它缓存的所有 revision。
确认范围后,对同一个目标、同一个缓存目录,去掉 --dry-run 再运行一次,并保留确认提示。目标意外变化或预览失败时,停下来排查原因。删除会直接生效,不会移到废纸篓;恢复需要备份,或者在仍有访问权限的情况下重新下载。snapshot 之间、以及某些布局下的不同仓库之间会共享 blob,请交给缓存管理器处理,也不要把显示的大小直接相加。
谨慎使用 prune,并把其他缓存分开处理
在核对过的 2.0.0 版本中,hf cache prune --dry-run 会预览 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 核对本机的版本。
删除前要核对什么
每一类都要单独检查。下表说明需要保留或恢复的内容,不是自动删除清单,也不承诺能腾出固定的空间。
| 项目 | 在哪里检查 | 删除前要确认什么 |
|---|---|---|
| 仓库或 revision | hf cache ls --revisions | 确认准确的删除范围;恢复可能需要重新下载,并且仍能访问同一个仓库。 |
| 共享的 blob 和 snapshot | 已确认的 Hub 缓存 | 交给缓存管理器处理;不同 revision、某些布局下甚至不同仓库会共用同一批文件。 |
| detached revision | hf cache prune --dry-run | 即使缓存里没有命名引用,项目仍可能按确切的版本使用它。 |
| 生成的数据集缓存 | HF_DATASETS_CACHE | 和 Hub 下载分开;重建需要源数据和处理时间。 |
| 自己的 checkpoint、adapter 和源文件 | 你的项目和备份位置 | 保留原件,并确认备份确实包含这些文件,尤其是存放在缓存目录下的。 |
| Hugging Face 主目录和认证信息 | HF_HOME | 不要为了删除模型缓存而整个删除这个目录。 |
常见问题
可以直接删除 Mac 上的 ~/.cache/huggingface 吗?
不要把整个目录当成可以随手丢弃的东西。先找到实际使用的 Hub 缓存,保留认证信息和你自己的成果,再用已安装版本的 hf cache 命令预览具体的仓库或 revision。
detached revision 就是没用的版本吗?
不是。即使缓存里没有命名引用,项目仍可能固定使用某个完整的 revision;核对项目的依赖后再清理。
hf cache rm 会删掉我微调的模型吗?
如果你的文件位于选中的缓存条目里,就可能被一起删除。先把它们移出删除范围并确认备份可用;文件夹名叫 cache,不代表里面的内容都可以丢弃。
参考来源