Hugging Face CLI

Какую задачу решает

Консольная программа сервиса Hugging Face, где авторы выкладывают открытые модели и наборы данных. Агент скачивает нужный файл или весь репозиторий модели по имени, заранее показывает, сколько придётся качать, и кладёт файлы в папку проекта или в общий кэш. Открытые модели скачиваются без входа. Вход по документации нужен, чтобы выкладывать свои файлы и скачивать модели с закрытым доступом. Для такой модели человек ещё принимает условия на её странице, а часть авторов одобряет заявки вручную.

• Скачивает один файл, несколько файлов по шаблону (--include) или весь репозиторий модели в папку, которую назвал агент (--local-dir).
• Показывает размер до скачивания (--dry-run). В прогоне команда назвала 77.7M для модели whisper.cpp и файл модели не скачала.
• Если файл уже скачан и на Hugging Face не менялся, повторный запуск его заново не качает. В прогоне повтор занял 829 мс вместо 2 943 мс, файл остался тем же до байта.
• Ведёт общий кэш моделей: hf cache ls показывает, что лежит и сколько весит, hf cache verify сверяет контрольные суммы, hf cache rm удаляет.

Пример результата

Установить агентом

Установи программу «Hugging Face CLI». Работай по шагам и после каждого коротко говори, что сделал.

Что это за программа (каталог smyslokod.ru, официальные источники сверены 16.10.2026):
- официальный сайт: https://huggingface.co
- исходный код: https://github.com/huggingface/huggingface_hub
- инструкция по установке: https://huggingface.co/docs/huggingface_hub/guides/cli
- актуальная версия на 16.10.2026: 2.2.0
- лицензия: Apache-2.0
- для работы нужно (обязательно): Python 3.10 или новее - программа написана на Python. Установщик с hf.co ищет его в системе, Homebrew ставит свой вместе с формулой
- для работы нужно (в отдельных случаях): Учётная запись Hugging Face - только для моделей с закрытым доступом и чтобы выкладывать свои файлы, открытые модели скачиваются без входа
- для работы нужно (в отдельных случаях): Homebrew - только для установки на Mac через brew

Правила:
1. Ничего не устанавливай и не меняй, пока я не скажу «да» на твой план.
2. Ставь только способами из этого промпта. Сторонние сборки, скрипты с форумов и из чужих репозиториев не бери.
3. Мои проекты не трогай: не меняй их файлы, виртуальные окружения и списки зависимостей (package.json, requirements.txt, pyproject.toml).
4. Если ставишь из PyPI (пакет huggingface_hub), то только в отдельное окружение: uv tool install или pipx. В окружение проекта и в системный Python не ставь.
5. Команды с sudo, правку профиля оболочки (~/.zshrc, ~/.bashrc) и переменной PATH делай только после моего отдельного «да» на каждую.
6. Не проси у меня пароли и ключи и не выводи их. Если нужен пароль администратора, дай команду, я выполню её сам.
7. Перед скачиванием покажи человеку размер через --dry-run и жди «да».
8. Ставь командой из карточки: на Linux и Mac с --exclude-skill и --no-modify-path, на Windows с -ExcludeSkill и -NoModifyPath. Навык и PATH добавляй только по отдельному «да».
9. Не входи в учётную запись Hugging Face и не проси ключ в чат. Команду hf auth login человек запускает сам.
10. hf cache rm, hf upload, hf repos delete, hf repos delete-files, hf buckets sync --delete и hf jobs run запускай только после «да» человека на каждую команду.
11. Сохраняй модели в папку, которую назвал человек (--local-dir), и сверяй sha256 файла с тем, что показывает Hugging Face.

Шаги:
0. Определи, где ты работаешь: мой компьютер, сервер или контейнер. Какая система и процессор, какие менеджеры пакетов есть (Homebrew, apt, winget, uv, pipx). Ставить нужно туда, где ты сам запускаешь команды.
   - на компьютере: скачать модель для локальной работы, например файл GGUF или модель распознавания речи.
   - на сервере: в прогоне скачивание открытых файлов шло в терминале без окон, вопросов и входа. Вход и удаление кэша по умолчанию спрашивают человека.
   - в контейнере: мы проверяли в контейнере Ubuntu 24.04 от root, установка заняла 14 секунд.
1. Проверь, не стоит ли программа уже: hf version ; which -a hf. Если стоит и запускается, ничего не ставь и переходи к шагу 5.
2. Проверь, что есть всё нужное для работы: Python 3.10 или новее. Чего нет, внеси в план отдельным пунктом. Проверь свободное место на диске: нужно Окружение программы в ~/.hf-cli заняло 35 539 149 байт на Ubuntu 24.04 с Python 3.12.3. Место под модели считай отдельно, размер до скачивания показывает --dry-run: в прогоне ggml-tiny.bin занял 77 691 713 байт. Сколько займёт Homebrew вместе с Python, мы не мерили..
3. Составь план: каким одним способом из списка ниже будешь ставить, что появится на диске и сколько места займёт, что поменяется в системе и как потом удалить. Покажи план и жди моего «да».
   Способы из официальных источников:
   - macOS и Linux, установщик с hf.co: curl -LsSf https://hf.co/cli/install.sh | bash -s -- --exclude-skill --no-modify-path (Тот же установщик, что для Linux, и папки те же, но на Mac мы его не проверяли)
   - macOS, Homebrew: brew install hf (Формула того же проекта, ведёт на документацию Hugging Face, на 16.10.2026 ставит 2.2.0 и тянет за собой Python и git-lfs. Мы её не проверяли)
   - Windows, установщик с hf.co: powershell -ExecutionPolicy ByPass -c "& ([scriptblock]::Create((irm https://hf.co/cli/install.ps1))) -ExcludeSkill -NoModifyPath" (Команда из документации с двумя ключами установщика: -ExcludeSkill отключает навык для агентов, -NoModifyPath не даёт дописать папку в PATH пользователя. Окружение ляжет в %USERPROFILE%\.hf-cli, программа в %USERPROFILE%\.local\bin\hf.exe, запускать её по полному пути или добавить папку в PATH. На Windows мы не проверяли)
4. Установи по согласованному плану. Если что-то идёт не так, как в плане, остановись и спроси.
5. Проверь результат:
   - hf version: программа запускается без ошибки;
   - Во временной папке скачай файл модели ggml-tiny.bin из открытого репозитория ggerganov/whisper.cpp: сначала узнай размер через --dry-run, потом скачай в папку models и сверь sha256 с тем, что отдаёт Hugging Face. Проверь повторный запуск, шаблон --include, кэш (ls, verify, rm), режим без сети и ошибки на закрытой модели и несуществующем файле. Делай это во временной папке и не трогай мои файлы.
     curl -LsSf https://hf.co/cli/install.sh | bash -s -- --exclude-skill --no-modify-path
     export PATH=$HOME/.local/bin:$PATH
     hf version
     hf download ggerganov/whisper.cpp ggml-tiny.bin --local-dir models --dry-run
     hf download ggerganov/whisper.cpp ggml-tiny.bin --local-dir models -q
     sha256sum models/ggml-tiny.bin
     curl -sL "https://huggingface.co/api/models/ggerganov/whisper.cpp?blobs=true" -o hub-model.json
     python3 -c "import json,hashlib; s=[x for x in json.load(open('hub-model.json'))['siblings'] if x['rfilename']=='ggml-tiny.bin'][0]; assert s['lfs']['sha256']==hashlib.sha256(open('models/ggml-tiny.bin','rb').read()).hexdigest(); print('HUB_SHA_MATCH')"
     hf download ggerganov/whisper.cpp ggml-tiny.bin --local-dir models
     hf download Qwen/Qwen2.5-0.5B-Instruct-GGUF --include "*.md" --include "LICENSE" --local-dir qwen-docs
     hf download ggerganov/whisper.cpp ggml-tiny-q5_1.bin -q
     hf download ggerganov/whisper.cpp ggml-tiny-q5_1.bin --format json
     hf cache ls
     hf cache verify ggerganov/whisper.cpp
     HF_HUB_OFFLINE=1 hf download ggerganov/whisper.cpp ggml-tiny-q5_1.bin
     HF_HUB_OFFLINE=1 hf download ggerganov/whisper.cpp ggml-base.bin
     hf cache rm model/ggerganov/whisper.cpp -y
     hf download google/gemma-2-2b-it config.json --local-dir gated
     hf download ggerganov/whisper.cpp no-such-file.bin --local-dir models
     hf auth whoami
     rm -rf ~/.hf-cli ~/.local/bin/hf ~/.cache/huggingface
   - если ты работаешь в папке моего проекта, покажи git status: от установки в проекте не должно появиться изменений.
6. Итог одним сообщением: что установлено, какой версии и куда, сколько места заняло, что поменялось в системе и как всё удалить (macOS и Linux, установщик с hf.co: rm -rf ~/.hf-cli ~/.local/bin/hf; macOS, Homebrew: brew uninstall hf; macOS и Linux, скачанные модели и ключ доступа, по желанию: rm -rf ~/.cache/huggingface; Windows, установщик с hf.co: Remove-Item -Recurse -Force $env:USERPROFILE\.hf-cli; Remove-Item -Force $env:USERPROFILE\.local\bin\hf.exe; Remove-Item -Force -ErrorAction SilentlyContinue $env:USERPROFILE\.local\bin\hf-script.py).

Если на любом шаге ошибка, не чини наугад: покажи текст ошибки и скажи, что, по-твоему, случилось. Частые проблемы: https://smyslokod.ru/cli/hugging-face-cli#problemy

Промпт собран из официальных инструкций, сверенных 16.10.2026. Агент сначала проверит, что уже стоит, покажет план с местом на диске и способом удаления и без твоего «да» ничего не поставит.

Как ставят вручную

Способы из официальных источников, у каждого ссылка на первоисточник.

• macOS и Linux · установщик с hf.co · источник

  curl -LsSf https://hf.co/cli/install.sh | bash -s -- --exclude-skill --no-modify-path

  Тот же установщик, что для Linux, и папки те же, но на Mac мы его не проверяли

• macOS · Homebrew · источник

  brew install hf

  Формула того же проекта, ведёт на документацию Hugging Face, на 16.10.2026 ставит 2.2.0 и тянет за собой Python и git-lfs. Мы её не проверяли

• Windows · установщик с hf.co · источник

  powershell -ExecutionPolicy ByPass -c "& ([scriptblock]::Create((irm https://hf.co/cli/install.ps1))) -ExcludeSkill -NoModifyPath"

  Команда из документации с двумя ключами установщика: -ExcludeSkill отключает навык для агентов, -NoModifyPath не даёт дописать папку в PATH пользователя. Окружение ляжет в %USERPROFILE%\.hf-cli, программа в %USERPROFILE%\.local\bin\hf.exe, запускать её по полному пути или добавить папку в PATH. На Windows мы не проверяли

Как удалить

• macOS и Linux, установщик с hf.co: rm -rf ~/.hf-cli ~/.local/bin/hf
• macOS, Homebrew: brew uninstall hf
• macOS и Linux, скачанные модели и ключ доступа, по желанию: rm -rf ~/.cache/huggingface
• Windows, установщик с hf.co: Remove-Item -Recurse -Force $env:USERPROFILE\.hf-cli; Remove-Item -Force $env:USERPROFILE\.local\bin\hf.exe; Remove-Item -Force -ErrorAction SilentlyContinue $env:USERPROFILE\.local\bin\hf-script.py

Что нужно для работы

• Python 3.10 или новее (обязательно) - программа написана на Python. Установщик с hf.co ищет его в системе, Homebrew ставит свой вместе с формулой
• Учётная запись Hugging Face (в отдельных случаях) - только для моделей с закрытым доступом и чтобы выкладывать свои файлы, открытые модели скачиваются без входа
• Homebrew (в отдельных случаях) - только для установки на Mac через brew

Системы

• macOS - ставится тем же установщиком с hf.co или через Homebrew. На Mac мы не проверяли.
• Windows - свой установщик для PowerShell. По документации кэш на Windows работает хуже без режима разработчика: файлы могут лежать на диске дважды. На Windows мы не проверяли.
• Linux - мы проверяли на Ubuntu 24.04 x86-64 установщик с hf.co, ему нужен Python 3.10 или новее.

Где запускать

Ставить нужно туда, где работает агент: на твой компьютер, сервер или в контейнер.

• На компьютере - скачать модель для локальной работы, например файл GGUF или модель распознавания речи.
• На сервере - в прогоне скачивание открытых файлов шло в терминале без окон, вопросов и входа. Вход и удаление кэша по умолчанию спрашивают человека.
• В контейнере - мы проверяли в контейнере Ubuntu 24.04 от root, установка заняла 14 секунд.

Сколько ресурсов нужно

Место на диске

Окружение программы в ~/.hf-cli заняло 35 539 149 байт на Ubuntu 24.04 с Python 3.12.3. Место под модели считай отдельно, размер до скачивания показывает --dry-run: в прогоне ggml-tiny.bin занял 77 691 713 байт. Сколько займёт Homebrew вместе с Python, мы не мерили.

Память

Память мы не мерили. По справке ключ --max-workers задаёт число потоков скачивания, по умолчанию 8.

Сеть

Сеть нужна для установки и скачивания. В прогоне установщик ходил к hf.co, huggingface.co (Amazon CloudFront), pypi.org и files.pythonhosted.org. Скачивание шло через huggingface.co и серверы хранилища Hugging Face на Amazon Web Services во Франции и США, плюс DNS контейнера 127.0.0.11. С HF_HUB_OFFLINE=1 программа взяла файл из кэша и не открыла ни одного соединения. Из России мы не проверяли, песочница стоит во Франции.

Без входа Hugging Face ограничивает число запросов с одного адреса за 5 минут, по странице лимитов на сентябрь 2025 года это 3 000 запросов к файлам (Resolvers) и 500 запросов к API за пятиминутное окно. Там же сказано, что лимиты без входа могут меняться.

Лицензия и платные замены

Лицензия Apache-2.0. Пользоваться можно бесплатно, и лично, и в работе компании. Кто распространяет изменённые копии, сохраняет текст лицензии и пометки об изменениях. У каждой модели на Hugging Face своя лицензия, её смотрят на странице модели. Текст лицензии

Цена: Бесплатно. Программа бесплатная, лицензия Apache-2.0. Открытые модели Hugging Face раздаёт бесплатно. Платные услуги сервиса (вычисления Jobs, тариф PRO с большими лимитами) программе для скачивания не нужны.

Платные замены

Платную замену мы не указываем: эту программу бесплатно выпускает сам Hugging Face, на чьём сервисе лежат модели, а открытые модели в прогоне скачались без оплаты и входа.

Бесплатные замены

• curl по прямой ссылке - Файл открытой модели можно скачать по ссылке вида huggingface.co/<репозиторий>/resolve/main/<файл>. Размер заранее, шаблоны, кэш и сверку суммы придётся делать вручную.
• Ollama - Сама скачивает модели из своего реестра и запускает их. Подойдёт, если нужна готовая модель для общения, а файл сам по себе не нужен.

О чём помнить

• Безопасность. Агент запускает hf в терминале сам (exec). Программа пишет скачанные файлы в папку из --local-dir или в кэш ~/.cache/huggingface (write). Читает файлы, которые ей передали для выкладки, кэш и скачанные файлы, когда сверяет их суммы (read). Команда hf cache rm удаляет модели из кэша и без входа (acts). После входа команды hf upload с ключом --delete, hf repos delete, hf repos delete-files и hf buckets sync --delete удаляют файлы и репозитории на Hugging Face, а hf jobs run тратит оплаченные заранее деньги на вычисления (acts). Ключ доступа после hf auth login лежит в ~/.cache/huggingface/token, hf auth logout его стирает.
• Установщик без ключей ставит навык hf-cli для агентов в ~/.agents/skills и ~/.claude/skills и дописывает PATH в профиль оболочки, если папки программы в PATH ещё нет. Команды из карточки это отключают: на Linux и Mac ключи --exclude-skill и --no-modify-path, на Windows -ExcludeSkill и -NoModifyPath. Если навык нужен, установщик сам ставит его командой hf skills add hf-cli --global --force.
• При запуске программа проверяет, не вышла ли новая версия, не чаще раза в 24 часа: у установленной через Homebrew спрашивает brew, у остальных PyPI. Список программ-агентов, по которому она узнаёт, кто её запустил, она берёт с Hugging Face и обновляет тоже не чаще раза в 24 часа. В прогоне так появились ~/.cache/huggingface/.agent_harnesses.json и .check_for_update_done. Проверку версии отключает HF_HUB_DISABLE_UPDATE_CHECK=1, а все запросы к Hugging Face отключает HF_HUB_OFFLINE=1, тогда работает только кэш.
• Удаление программы не трогает ~/.cache/huggingface: там остаются скачанные модели и, если человек входил, ключ доступа. Ключ стирает hf auth logout до удаления программы, а всю папку по желанию удаляет rm -rf ~/.cache/huggingface.
• У каждой модели своя лицензия: у ggerganov/whisper.cpp MIT, у Qwen/Qwen2.5-0.5B-Instruct-GGUF Apache-2.0. Часть моделей закрыта до согласия с условиями на сайте, программа без входа их не скачает.
• С --local-dir программа заводит в этой папке служебную папку .cache/huggingface с отметками о скачанном. По документации эти отметки нужны, чтобы при повторном запуске не качать файл, который уже на месте.

Частые проблемы

Проверка

✓ Проверено 16.10.2026: Ubuntu 24.04 (x86_64) в одноразовом контейнере Docker на сервере, от root, Python 3.12.3: hf 2.2.0 из установщика с hf.co с ключами --exclude-skill и --no-modify-path.

«Проверено» ставим, только когда сами поставили программу и прогнали её на задаче. Сверка ссылок и вывод версии так не называются.

Похожие программы

• OllamaСвободная программа, которая запускает языковые модели у вас на компьютере или сервере. С локальной моделью агент разбирает счета и письма без отправки текста в облако.