Установка

Прежде чем начать, вам необходимо настроить окружение, установив соответствующие пакеты.

huggingface_hub тестируется на Python 3.10+.

Установка с помощью pip

Настоятельно рекомендуется устанавливать huggingface_hub в виртуальное окружение. Если вы не знакомы с виртуальными окружениями Python, ознакомьтесь с этим руководством. Виртуальное окружение упрощает управление различными проектами и позволяет избежать проблем совместимости между зависимостями.

Начните с создания виртуального окружения в каталоге вашего проекта:

python -m venv .venv

Активируйте виртуальное окружение. На Linux и macOS:

source .venv/bin/activate

Активация виртуального окружения в Windows:

.venv/Scripts/activate

Теперь вы готовы установить huggingface_hub из реестра PyPi:

pip install --upgrade huggingface_hub

После завершения проверьте установку на корректность работы.

Установка необязательных зависимостей

Некоторые зависимости huggingface_hub являются необязательными, так как они не требуются для работы основных функций huggingface_hub. Однако некоторые возможности huggingface_hub могут быть недоступны, если необязательные зависимости не установлены.

Вы можете установить необязательные зависимости с помощью pip:

# Install dependencies for both torch-specific and MCP-specific features.
pip install 'huggingface_hub[mcp,torch]'

Вот список необязательных зависимостей в huggingface_hub:

• fastai, torch: зависимости для запуска функций, специфичных для фреймворка.
• dev: зависимости для вклада в библиотеку. Включает testing (для запуска тестов), typing (для запуска проверки типов) и quality (для запуска линтеров).

Установка из исходного кода

В некоторых случаях имеет смысл установить huggingface_hub непосредственно из исходного кода. Это позволяет использовать самую свежую версию ветки main, а не последнюю стабильную. Версия main полезна для отслеживания последних изменений, например, если ошибка была исправлена после последнего официального релиза, но новый релиз ещё не выпущен.

Однако это означает, что версия main может быть не всегда стабильной. Мы стремимся поддерживать работоспособность версии main, и большинство проблем обычно решаются в течение нескольких часов или дня. Если вы столкнулись с проблемой, пожалуйста, создайте Issue, чтобы мы могли исправить её ещё быстрее!

pip install git+https://github.com/huggingface/huggingface_hub

При установке из исходного кода можно также указать конкретную ветку. Это полезно, если вы хотите протестировать новую функцию или исправление ошибки, которые ещё не были объединены в основную ветку:

pip install git+https://github.com/huggingface/huggingface_hub@my-feature-branch

После завершения проверьте установку на корректность работы.

Установка в режиме редактирования

Установка из исходного кода позволяет настроить редактируемую установку. Это более продвинутый вариант установки, если вы планируете вносить вклад в huggingface_hub и вам нужно тестировать изменения в коде. Вам нужно клонировать локальную копию huggingface_hub на ваш компьютер.

# First, clone repo locally
git clone https://github.com/huggingface/huggingface_hub.git

# Then, install with -e flag
cd huggingface_hub
pip install -e .

Эти команды свяжут папку, в которую вы клонировали репозиторий, с путями к вашим библиотекам Python. Теперь Python будет искать модули не только в стандартных путях библиотек, но и в папке, в которую вы клонировали репозиторий. Например, если ваши пакеты Python обычно установлены в ./.venv/lib/python3.13/site-packages/, Python также будет искать модули в папке, в которую вы клонировали ./huggingface_hub/.

Установка Hugging Face CLI

Используйте наши однострочные установщики, чтобы настроить CLI hf, не затрагивая ваше окружение Python:

На macOS и Linux:

curl -LsSf https://hf.co/cli/install.sh | bash

В Windows:

powershell -ExecutionPolicy ByPass -c "irm https://hf.co/cli/install.ps1 | iex"

Чтобы обновить существующую установку, выполните hf update — команда определяет, как был установлен hf (автономный установщик, Homebrew или pip), и запускает соответствующую команду.

Установка с помощью conda

Если вам удобнее, вы можете установить huggingface_hub с помощью канала conda-forge:

conda install -c conda-forge huggingface_hub

После завершения проверьте установку на корректность работы.

Проверка установки

После установки убедитесь, что huggingface_hub работает корректно, выполнив следующую команду:

python -c "from huggingface_hub import model_info; print(model_info('gpt2'))"

Эта команда получит информацию о модели gpt2 с Hub. Результат должен выглядеть так:

Model Name: gpt2
Tags: ['pytorch', 'tf', 'jax', 'tflite', 'rust', 'safetensors', 'gpt2', 'text-generation', 'en', 'doi:10.57967/hf/0039', 'transformers', 'exbert', 'license:mit', 'has_space']
Task: text-generation

Ограничения Windows

В рамках нашей цели сделать качественный ML доступным каждому мы создали huggingface_hub как кроссплатформенную библиотеку, которая в частности должна корректно работать как на Unix-системах, так и на Windows. Тем не менее, при запуске на Windows huggingface_hub имеет ряд ограничений. Ниже приведен исчерпывающий список известных проблем. Если вы столкнетесь с какой-либо не описанной проблемой, пожалуйста, сообщите нам, создав issue на Github.

• Система кэширования huggingface_hub использует символьные ссылки для эффективного кэширования файлов, загруженных с Hub. В Windows необходимо включить режим разработчика или запускать скрипт от имени администратора, чтобы разрешить создание символьных ссылок. Если они не активированы, система кэширования продолжает работать, но в неоптимизированном режиме. Подробности см. в разделе Ограничения кэша.
• Пути к файлам на Hub могут содержать специальные символы (например, "path/to?/my/file"). Windows предъявляет более строгие требования к специальным символам, из-за чего загрузка таких файлов на Windows невозможна. Надеемся, что это редкий случай. Если вы считаете, что это ошибка, обратитесь к владельцу репозитория или к нам, чтобы мы вместе нашли решение.

Дальнейшие шаги

После того как huggingface_hub будет корректно установлен на вашем компьютере, вы можете настроить переменные окружения или обратиться к одному из наших руководств, чтобы начать работу.