在 Mac 上检查和清理 Hugging Face 缓存

确认缓存位置和必须保留的成果

常见 Hub 缓存是 ~/.cache/huggingface/hub。HF_HUB_CACHE 指定仓库缓存，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 核对本机版本。

删除前要核对什么

先确认实际路径、用途和恢复方式。下表不是自动删除清单，也不承诺能释放固定容量。

常见问题