Как проверить и очистить кэш Hugging Face на Mac
Команда AskClean · Обновлено 2026-11-02
Чтобы освободить место, занятое кэшем Hugging Face на Mac, определите, какой кэш использует ваше приложение, изучите его командой hf cache ls и проверьте удаление конкретного репозитория или ревизии через hf cache rm --dry-run. Сохраните модели, нужные для работы без сети, и собственные результаты. Не удаляйте вслепую общие блобы или всю папку HF_HOME.

Найдите нужный кэш и сохраните свою работу
Обычно кэш Hub находится в ~/.cache/huggingface/hub. Переменная HF_HUB_CACHE задаёт путь непосредственно к кэшу репозиториев Hub, HF_HOME меняет весь домашний каталог Hugging Face, а если HF_HOME не задана, на путь по умолчанию может влиять XDG_CACHE_HOME. Приложение может выбрать и собственное место через аргумент cache_dir. Проверяйте окружение, в котором запускается приложение: графические программы, ядра Jupyter-ноутбуков и проекты в «Терминале» могут использовать разные настройки, а пустая папка по умолчанию ещё не значит, что моделей на Mac нет. В HF_HOME могут лежать и данные аутентификации, поэтому не удаляйте этот каталог целиком ради очистки моделей, а обращаясь за помощью, показывайте только нужные настройки без секретов.
Отделите скачанное от созданного вами: дообученные чекпоинты, адаптеры, изменения токенизатора, результаты конвертации, закрытые наборы данных, Jupyter-ноутбуки, промпты и настройки проекта нельзя просто скачать заново. Базовую модель обычно можно загрузить ещё раз, а локальный адаптер или рецепт конвертации может существовать только на этом Mac. Сделайте и проверьте резервную копию: некоторые программы резервного копирования пропускают каталоги кэша с файлом CACHEDIR.TAG. Если вы не знаете, как восстановить объект и снова запустить приложение, пока оставьте его; давняя дата последнего доступа сама по себе не доказывает, что модель не нужна.
Изучите репозитории и ревизии до выбора
Закройте приложения и остановите загрузки и задания, которые используют кэш. Выполните hf cache ls --no-truncate, чтобы увидеть полные идентификаторы репозиториев, а затем hf cache ls --revisions --no-truncate --show-warnings — для полных хешей ревизий и проблем кэша: в проверенной версии подробные предупреждения по умолчанию скрыты. Для нестандартного кэша передавайте каждой команде один и тот же --cache-dir. Показанный размер ревизии может быть больше, чем освободит её удаление: снимки и блобы бывают общими, и при сложении размеров одни и те же файлы считаются несколько раз. Разберитесь с предупреждениями о нечитаемых или несогласованных записях, запишите размер каталога и свободное место на диске и не публикуйте вывод, если в нём видны закрытые проекты.
Проверьте удаление в режиме предпросмотра
Передайте hf cache rm один полный идентификатор репозитория или хеш ревизии из своего списка и сначала добавьте --dry-run. Для репозитория модели сохраняйте префикс model/, который показывает CLI: имя папки на диске, начинающееся с models--, — это другой идентификатор. Для одной ревизии укажите её полный хеш и проверьте, к какому репозиторию она относится. Предпросмотр показывает сводку целей и оценку освобождаемого места, а не пофайловый список. Если указать репозиторий, удалятся все его кэшированные ревизии; чтобы удалить только одну, указывайте ревизию.
Проверив область, повторите ту же команду без --dry-run — с той же целью и тем же каталогом кэша — и не отключайте запрос подтверждения. Если список неожиданно изменился, проверьте, не перезапустилось ли другое приложение и не скачало ли оно данные; если предпросмотр завершился ошибкой, остановитесь и разберитесь. Кэш удаляется сразу, минуя Корзину: вернуть ревизию можно только из резервной копии или повторной загрузкой. Храните копию, пока проверки не пройдут, особенно для закрытых моделей, моделей с ограниченным доступом (gated), снятых с публикации, изменённых локально или нужных без сети. Общие блобы и ссылки снимков оставьте менеджеру кэша Hugging Face: удаление отдельных файлов в Finder может повредить другие ревизии.
Проверяйте всё, что предлагает prune, и не смешивайте кэши
В проверенной версии 2.0.0 команда hf cache prune --dry-run показывает отсоединённые (detached) ревизии и незавершённые загрузки. У отсоединённой ревизии нет именованной ссылки в кэше, но проект всё равно может запрашивать именно её, поэтому проверьте проекты, прежде чем удалять. Незавершённый файл может остаться от прерванной загрузки, а может принадлежать заданию, которое ещё работает, — сначала остановите активные загрузки. Для первой очистки одна явная цель понятнее массовой: удалите её, запустите затронутое приложение и снова измерьте место.
Hugging Face Datasets хранит обработанные данные, например Arrow-файлы, в своём кэше (HF_DATASETS_CACHE): очистка загрузок Hub его не затрагивает, а пересоздание потребует исходных данных и времени. Файлы, скачанные с явным local_dir, лежат в выбранной вами или приложением папке вместе с метаданными — рассматривайте её отдельно от общего кэша и сохраните внесённые правки: повторная загрузка их не вернёт. Хранилище передачи Xet тоже отдельное. Если после очистки ревизий Hub места всё ещё мало, проверяйте каждую из этих категорий по отдельности, а не удаляйте весь HF_HOME.
Проверьте, что нужные модели работают
Повторите инвентаризацию и измерения, затем загрузите модель и ревизию, которые решили оставить, и выполните небольшую задачу с заранее известным результатом: успешный импорт библиотеки Python не проверяет файлы модели. Если модель нужна без сети, проверьте её работу с отключённой сетью. Если при следующем запуске та же модель скачивается снова, очистка задела нужные данные — пересмотрите выбор, ёмкость диска или расположение кэша. Если проверка не прошла, приостановите очистку, запишите модель, ревизию, путь к кэшу и ошибку, проверьте окружение и восстановите копию или скачайте ревизию заново — и только потом удаляйте следующую запись.
Если нужные модели не помещаются на Mac, поможет внешний диск. Проверьте на нём свободное место, права доступа и поддержку символических ссылок, которыми снимки связаны с общими блобами. Копируйте ссылки вместе с файлами, на которые они указывают, настройте каждое приложение на новое расположение и проверьте его модели там, прежде чем удалять оригинал. Пока приложениям нужны эти модели, диск должен быть подключён.
Как мы проверяли команды
29 сентября 2026 года мы проверили команды с huggingface_hub 2.0.0 на временных синтетических кэшах без сети: список ревизий выводился, --show-warnings показал намеренно повреждённую запись, --no-truncate сохранил полный идентификатор, предпросмотр rm и prune не изменил файлы, а удаление старой ревизии сохранило текущую ревизию и общие данные и удалило только собственный блоб старой. Реальные загрузки моделей, инференс, пользовательские кэши, перенос на другой диск и очистка блобов, общих для нескольких репозиториев, не проверялись, поэтому сколько места освободится у вас, предсказать нельзя. Перед началом выполните hf cache --help: если в вашей версии другие команды или параметры, следуйте её документации.
Что можно восстановить, а что нужно сохранить
Проверяйте каждую категорию отдельно. Таблица объясняет, что нужно сохранить или как восстановить, но не отмечает файлы для автоматического удаления.
| Объект | Где проверить | Что проверить перед удалением |
|---|---|---|
| Репозиторий или ревизия Hub | hf cache ls --revisions | Проверьте, что именно выбрано. Для восстановления может понадобиться повторная загрузка и доступ к тому же репозиторию. |
| Общие блобы и снимки | Проверенный кэш Hub | Пользуйтесь менеджером кэша: ревизии, а в некоторых форматах и репозитории могут ссылаться на одни и те же файлы. |
| Отсоединённые ревизии | hf cache prune --dry-run | Проект может требовать именно эту ревизию, даже если в кэше на неё нет именованной ссылки. |
| Кэш обработанных наборов данных | HF_DATASETS_CACHE / настройки кэша Datasets | Хранится отдельно от загрузок Hub; пересоздание потребует времени на обработку и исходных данных. |
| Свои чекпоинты, адаптеры и исходники | Папки проекта и резервных копий | Сохраните свою работу и проверьте, что резервная копия её содержит, — особенно если она лежит внутри каталога кэша. |
| Домашний каталог Hugging Face и данные входа | HF_HOME | Не удаляйте весь каталог ради очистки кэша моделей. |
Частые вопросы
Можно ли удалить папку ~/.cache/huggingface целиком?
Не считайте всю папку одноразовой. Найдите активный кэш Hub, сохраните данные аутентификации и собственную работу, а затем проверьте удаление конкретных репозиториев или ревизий через установленный hf cache.
Может ли hf cache rm удалить мою дообученную модель?
Да, если ваши файлы лежат внутри выбранной записи кэша. Храните чекпоинты, адаптеры и изменённые файлы вне записей, которые собираетесь удалять, и проверьте их резервные копии: папка с названием cache вполне может содержать единственную копию важной работы.
Источники