# Установка

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

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

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

Настоятельно рекомендуется устанавливать `huggingface_hub` в [виртуальное окружение](https://docs.python.org/3/library/venv.html). Если вы не знакомы с виртуальными окружениями Python, ознакомьтесь с этим [руководством](https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/). Виртуальное окружение упрощает управление различными проектами и позволяет избежать проблем совместимости между зависимостями.

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

```bash
python -m venv .venv
```

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

```bash
source .venv/bin/activate
```

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

```bash
.venv/Scripts/activate
```

Теперь вы готовы установить `huggingface_hub` [из реестра PyPi](https://pypi.org/project/huggingface-hub/):

```bash
pip install --upgrade huggingface_hub
```

После завершения [проверьте установку](#check-installation) на корректность работы.

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

Некоторые зависимости `huggingface_hub` являются [необязательными](https://setuptools.pypa.io/en/latest/userguide/dependency_management.html#optional-dependencies), так как они не требуются для работы основных функций `huggingface_hub`. Однако некоторые функции `huggingface_hub` могут быть недоступны, если необязательные зависимости не установлены.

Вы можете установить необязательные зависимости с помощью `pip`:
```bash
# 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, чтобы мы могли исправить её ещё быстрее!

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

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

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

После завершения [проверьте установку](#check-installation) на корректность работы.

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

Установка из исходного кода позволяет настроить [редактируемую установку](https://pip.pypa.io/en/stable/topics/local-project-installs/#editable-installs). Это более продвинутый вариант установки, если вы планируете вносить вклад в `huggingface_hub` и вам нужно тестировать изменения в коде. Вам потребуется клонировать локальную копию `huggingface_hub` на ваш компьютер.

```bash
# 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:

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

В Windows:

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

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

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

Если вам удобнее, вы можете установить `huggingface_hub` с помощью [канала conda-forge](https://anaconda.org/conda-forge/huggingface_hub):

```bash
conda install -c conda-forge huggingface_hub
```

После завершения [проверьте установку](#check-installation) на корректность работы.

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

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

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

Эта команда получит информацию о модели [gpt2](https://huggingface.co/gpt2) с Hub. Результат должен выглядеть так:

```text
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](https://github.com/huggingface/huggingface_hub/issues/new/choose).

- Система кэширования `huggingface_hub` использует символьные ссылки для эффективного кэширования загруженных файлов
из Hub. В Windows необходимо активировать режим разработчика или запускать скрипт от имени администратора, чтобы разрешить использование символьных ссылок. Если они не активированы, система кэширования всё равно работает, но не в оптимальном режиме. Подробности см. в разделе [Ограничения кэша](./guides/manage-cache#limitations).
- Пути к файлам на Hub могут содержать специальные символы (например, `"path/to?/my/file"`). Windows
более строгие в отношении [специальных символов](https://learn.microsoft.com/en-us/windows/win32/intl/character-sets-used-in-file-names), что делает невозможным загрузку таких файлов в Windows. Надеемся, что это редкий случай. Если вы считаете, что это ошибка, свяжитесь с владельцем репозитория или с нами, чтобы мы вместе нашли решение.

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

После того как `huggingface_hub` будет корректно установлен на вашем компьютере, вы можете [настроить переменные окружения](package_reference/environment_variables) или [обратиться к одному из наших руководств](guides/overview), чтобы начать работу.