# Переменные окружения

`huggingface_hub` можно настроить с помощью переменных окружения.

Если вы не знакомы с переменными окружения, вот общие статьи о них [для macOS и Linux](https://linuxize.com/post/how-to-set-and-list-environment-variables-in-linux/) и для [Windows](https://phoenixnap.com/kb/windows-set-environment-variable).

На этой странице описаны все переменные окружения, специфичные для `huggingface_hub`, и их назначение.

> [!TIP]
> Все переменные окружения считываются при импорте `huggingface_hub`. Любые изменения, внесённые после этого, не будут учтены. Убедитесь, что вы задали переменные окружения до импорта `huggingface_hub`.

## Универсальный

### HF_INFERENCE_ENDPOINT

Для настройки базового URL inference api. Возможно, вам потребуется установить эту переменную, если ваша организация использует API Gateway, а не обращается напрямую к inference api.

По умолчанию `"https://api-inference.huggingface.co"`.

### HF_HOME

Для настройки того, где `huggingface_hub` будет локально хранить данные. В частности, в этой папке будут храниться ваш токен и кэш.

По умолчанию `"~/.cache/huggingface"`, если не задан [XDG_CACHE_HOME](#xdgcachehome).

### HF_HUB_CACHE

Чтобы настроить место локального кэширования репозиториев из Hub (моделей, наборов данных и пространств).

По умолчанию `"$HF_HOME/hub"` (например, `"~/.cache/huggingface/hub"` по умолчанию).

### HF_XET_CACHE

Настройка расположения локального кэша шардов и данных для загрузки в Xet. Дополнительные сведения см. в разделе [Кэширование Xet](../guides/manage-cache#xet-caching).

По умолчанию `"$HF_HOME/xet"` (например, `"~/.cache/huggingface/xet"` по умолчанию).

### HF_ASSETS_CACHE

Для настройки того, где локально будут кэшироваться [assets](../guides/manage-cache#caching-assets), создаваемые библиотеками нижнего уровня. К таким ресурсам могут относиться предобработанные данные, файлы, загруженные с GitHub, журналы и т. д.

По умолчанию `"$HF_HOME/assets"` (например, `"~/.cache/huggingface/assets"` по умолчанию).

### HF_TOKEN

Для настройки токена доступа пользователя для аутентификации в Hub. Если задано, это значение перезапишет токен, сохранённый на машине (в `$HF_TOKEN_PATH` или `"$HF_HOME/token"`, если первое не задано).

Для получения подробной информации об аутентификации обратитесь к [этому разделу](../quick-start#authentication).

### HF_TOKEN_PATH

Для настройки места, где `huggingface_hub` должен хранить User Access Token. По умолчанию — `"$HF_HOME/token"` (например, `~/.cache/huggingface/token` по умолчанию).

### HF_HUB_VERBOSITY

Установите уровень детализации журнала `huggingface_hub`. Должно быть одним из `{"debug", "info", "warning", "error", "critical"}`.

По умолчанию `"warning"`.

Подробнее см. в [справочнике по ведению журнала](../package_reference/utilities#huggingface_hub.utils.logging.get_verbosity).

### HF_HUB_ETAG_TIMEOUT

Целочисленное значение, определяющее количество секунд ожидания ответа сервера при получении последних метаданных из репозитория перед загрузкой файла. Если запрос завершается по таймауту, `huggingface_hub` по умолчанию использует файлы из локального кэша. Установка меньшего значения ускоряет рабочий процесс на машинах с медленным соединением, у которых файлы уже закэшированы. Более высокое значение гарантирует успешное выполнение вызова метаданных в большем числе случаев. По умолчанию — 10 с.

### HF_HUB_DOWNLOAD_TIMEOUT

Целочисленное значение, определяющее количество секунд ожидания ответа сервера при загрузке файла. Если запрос завершается по таймауту, возникает TimeoutError. Увеличение этого значения полезно на машинах с медленным соединением. Меньшее значение позволяет процессу быстрее завершиться с ошибкой в случае полного отсутствия сети. По умолчанию — 10 секунд.

## Xet 

### Другие переменные окружения Xet
* [`HF_HUB_DISABLE_XET`](../package_reference/environment_variables#hfhubdisablexet)
* [`HF_XET_CACHE`](../package_reference/environment_variables#hfxetcache)
* [`HF_XET_HIGH_PERFORMANCE`](../package_reference/environment_variables#hfxethighperformance)
* [`HF_XET_RECONSTRUCT_WRITE_SEQUENTIALLY`](../package_reference/environment_variables#hfxetreconstructwritesequentially)

### HF_XET_CHUNK_CACHE_SIZE_BYTES

Эта переменная больше не оказывает никакого влияния. `hf_xet` больше не использует локальный кэш чанков для загрузок, и установка этой переменной не включает его. Подробности см. в [xet-core#715](https://github.com/huggingface/xet-core/issues/715).

### HF_XET_SHARD_CACHE_SIZE_LIMIT

Для установки размера локального кэша Xet shard. Увеличение этого значения повышает эффективность загрузки, поскольку фрагменты, на которые ссылаются файлы в кэшированных shard, не загружаются повторно. Обратите внимание, что стандартное мягкое ограничение, как правило, достаточно для большинства рабочих нагрузок.

По умолчанию `16000000000` (16 ГБ).

### HF_XET_NUM_CONCURRENT_RANGE_GETS

Эта переменная больше не используется. Начиная с `hf_xet` 1.3.0, параллельность загрузок контролируется адаптивно.

## Логические значения

Следующие переменные окружения ожидают булево значение. Переменная будет считаться `True`, если её значение равно одному из `{"1", "ON", "YES", "TRUE"}` (без учёта регистра). Любое другое значение (или отсутствие значения) будет считаться `False`.

### HF_DEBUG

Если задано, уровень журнала для логгера `huggingface_hub` устанавливается в DEBUG. Кроме того, все запросы, выполняемые библиотеками HF, будут записываться в журнал в виде эквивалентных команд cURL для упрощения отладки и воспроизведения.

### HF_HUB_OFFLINE

Если установлено, HTTP-запросы к Hugging Face Hub не будут выполняться. При попытке загрузить файлы будут доступны только файлы из кэша. Если файл в кэше не обнаружен, будет выброшено исключение. Это полезно, если ваша сеть медленная и вам не важна последняя версия файла.

Если переменная окружения `HF_HUB_OFFLINE=1` установлена и вы вызываете любой метод [HfApi](/docs/huggingface_hub/main/ru/package_reference/hf_api#huggingface_hub.HfApi), будет выброшено исключение [OfflineModeIsEnabled](/docs/huggingface_hub/main/ru/package_reference/utilities#huggingface_hub.errors.OfflineModeIsEnabled).

**Примечание:** даже если последняя версия файла уже кэширована, вызов `hf_hub_download` всё равно инициирует HTTP-запрос для проверки наличия новой версии. Установка переменной `HF_HUB_OFFLINE=1` позволяет пропустить этот запрос, что ускоряет загрузку.

Если вы хотите проверить, включён ли офлайн-режим, вы можете использовать вспомогательную функцию [is_offline_mode()](/docs/huggingface_hub/main/ru/package_reference/utilities#huggingface_hub.is_offline_mode).

### HF_HUB_DISABLE_IMPLICIT_TOKEN

Аутентификация не является обязательной для каждого запроса к Hub. Например, для получения сведений о модели `"gpt2"` аутентификация не требуется. Однако, если пользователь [вошёл в систему](../package_reference/login), по умолчанию токен всегда отправляется, чтобы упростить работу с частными или защищёнными репозиториями (чтобы не получать ошибку HTTP 401 Unauthorized). В целях конфиденциальности вы можете отключить это поведение, установив `HF_HUB_DISABLE_IMPLICIT_TOKEN=1`. В этом случае токен будет отправляться только для вызовов с «доступом на запись» (например, при создании коммита).

**Примечание:** отключение неявной передачи токена может привести к неожиданным побочным эффектам. Например, если вы хотите получить список всех моделей на Hub, ваши приватные модели не будут отображены. В этом случае необходимо явно передать аргумент `token=True` в вашем скрипте.

### HF_HUB_DISABLE_PROGRESS_BARS

Для длительных задач `huggingface_hub` по умолчанию отображает индикатор прогресса (с использованием tqdm). Вы можете отключить все индикаторы прогресса сразу, установив `HF_HUB_DISABLE_PROGRESS_BARS=1`.

### HF_HUB_DISABLE_SYMLINKS

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

Примером использования является ситуация, когда общая сетевая папка (например, NAS) используется в качестве `HF_HUB_CACHE` на машинах с различными операционными системами. Символические ссылки, созданные в Linux, не всегда доступны в Windows, что приводит к ошибкам. Установка переменной `HF_HUB_DISABLE_SYMLINKS=1` позволяет избежать этой проблемы ценой отказа от дедупликации дискового пространства.

### HF_HUB_DISABLE_SYMLINKS_WARNING

Если вы работаете в Windows, рекомендуется включить режим разработчика или запускать `huggingface_hub` с правами администратора. В противном случае `huggingface_hub` не сможет создавать символьные ссылки в вашей кэш-системе. Вы сможете выполнять любые скрипты, но качество работы снизится, так как некоторые крупные файлы могут оказаться продублированными на вашем диске. Для уведомления об этом поведении выводится предупреждение. Чтобы отключить это предупреждение, установите переменную `HF_HUB_DISABLE_SYMLINKS_WARNING=1`.

Для получения дополнительных сведений см. [ограничения кэша](../guides/manage-cache#limitations).

### HF_HUB_DISABLE_EXPERIMENTAL_WARNING

Некоторые функции `huggingface_hub` являются экспериментальными. Это означает, что вы можете их использовать, но мы не гарантируем их поддержку в будущем. В частности, мы можем обновить API или поведение таких функций без этапа устаревания. При использовании экспериментальной функции выводится предупреждение, чтобы уведомить вас об этом. Если вы готовы самостоятельно отлаживать возможные проблемы, связанные с использованием экспериментальной функции, вы можете установить `HF_HUB_DISABLE_EXPERIMENTAL_WARNING=1`, чтобы отключить предупреждение.

Если вы используете экспериментальную функцию, пожалуйста, сообщите нам! Ваши отзывы помогут нам спроектировать и улучшить её.

### HF_HUB_DISABLE_TELEMETRY

По умолчанию некоторые данные собираются библиотеками HF (`transformers`, `datasets`, `gradio`,..) для мониторинга использования, отладки проблем и помощи в приоритизации функций. Каждая библиотека определяет собственную политику (т.е. какой тип использования отслеживать), но базовая реализация происходит в `huggingface_hub` (см. `send_telemetry`).

Вы можете установить переменную окружения `HF_HUB_DISABLE_TELEMETRY=1`, чтобы глобально отключить телеметрию.

### HF_HUB_DISABLE_UPDATE_CHECK

По умолчанию CLI `hf` при запуске проверяет наличие новой версии на PyPI (не чаще одного раза в 24 часа) и выводит в stderr однострочное жёлтое предупреждение, если новая версия доступна, рекомендуя выполнить `hf update`. Для dev- и pre-release-версий эта проверка уже не выполняется.

Также он проверяет (не чаще одного раза в 24 часа, исключительно локально), установлен ли навык `hf-cli` и сгенерирован ли он текущей версией, и при необходимости предлагает выполнить `hf skills add` / `hf skills update`. Проверка лишь выводит подсказку и никогда не изменяет ваши каталоги навыков.

Перед запуском установленной [расширения CLI](../guides/cli-extensions) система проверяет (не чаще одного раза в 24 часа для каждого расширения), доступна ли более новая версия на GitHub, и при наличии предлагает выполнить `hf extensions update <name>`. Команда `hf extensions list` использует ту же проверку для своей колонки `LATEST`.

Установите `HF_HUB_DISABLE_UPDATE_CHECK=1`, чтобы пропустить эти запросы и отключить все подобные подсказки. Это полезно в офлайн-средах CI или если вы предпочитаете менее «шумный» вывод в терминале.

### HF_HUB_DISABLE_XET

Установите, чтобы отключить использование `hf-xet`, даже если он доступен в вашем окружении Python. Это необходимо, так как `hf-xet` используется автоматически при обнаружении, и данный параметр позволяет явно отключить его применение. Если вы отключаете Xet, пожалуйста, рассмотрите возможность [создания заявки с включением диагностической информации](https://github.com/huggingface/xet-core?tab=readme-ov-file#issues-diagnostics--debugging), чтобы помочь нам понять, почему Xet не работает у вас.

### HF_HUB_ENABLE_HF_TRANSFER

> [!WARNING]
> Это устаревшая переменная окружения. Теперь, когда Hugging Face Hub полностью работает на базе хранилища Xet, все передачи файлов выполняются через бинарный пакет `hf-xet`. Он обеспечивает эффективную передачу данных с использованием стратегии дедупликации на основе чанков и бесшовно интегрируется с `huggingface_hub`. Это означает, что `hf_transfer` больше не может использоваться. Если вас интересует более высокая производительность, ознакомьтесь с разделом [`HF_XET_HIGH_PERFORMANCE`](#hf_xet_high_performance)

### HF_HUB_DISABLE_SHARED_BLOBS

Установите значение `1`, чтобы отключить общий хранилище блобов для кэша. По умолчанию успешно загруженные файлы Xet сохраняются в `<CACHE_DIR>/blobs/<prefix>/<xet_hash>` и подключаются через символьные ссылки в кэши репозиториев, благодаря чему идентичные файлы хранятся на диске только один раз для всех репозиториев и могут переиспользоваться без повторной загрузки. Эта оптимизация включена по умолчанию, но отключается, если Xet недоступен (например, если задано `HF_HUB_DISABLE_XET=1`) или если локально не поддерживаются символьные ссылки. В таких случаях система без предупреждений переходит на обычное локальное хранение в репозитории. Подробности см. в [руководстве по кэшированию](../guides/manage-cache#shared-blobs-across-repos).

### HF_XET_HIGH_PERFORMANCE

Настройте `hf-xet` на работу с повышенными параметрами, чтобы максимально использовать сетевые и дисковые ресурсы машины. Включение режима высокой производительности попытается насытить сетевую пропускную способность этого компьютера и задействовать все ядра ЦП для параллельной загрузки и выгрузки данных.

Рассмотрите это как аналог переменной окружения `HF_HUB_ENABLE_HF_TRANSFER=1` из предыдущих версий, но применённой к `hf-xet`.

Чтобы узнать больше о преимуществах хранилища Xet и `hf_xet`, обратитесь к этому [разделу](https://huggingface.co/docs/hub/xet/index).

### HF_XET_RECONSTRUCT_WRITE_SEQUENTIALLY

Эта переменная больше не используется. Начиная с `hf_xet` 1.3.0, файлы всегда записываются на локальный диск последовательно (см. [модуль записи файлов в v1.3.0](https://github.com/huggingface/xet-core/blob/v1.3.0/file_reconstruction/src/data_writer/data_writer.rs#L76-L91)).

## Устаревшие переменные окружения

Чтобы стандартизовать все переменные окружения в экосистеме Hugging Face, некоторые переменные были помечены как устаревшие. Хотя они по-прежнему работают, они больше не имеют приоритета над своими заменами. В таблице ниже перечислены устаревшие переменные и соответствующие им альтернативы:

| Устаревшая переменная         | Замена        |
| --------------------------- | ------------------ |
| `HUGGINGFACE_HUB_CACHE`     | `HF_HUB_CACHE`     |
| `HUGGINGFACE_ASSETS_CACHE`  | `HF_ASSETS_CACHE`  |
| `HUGGING_FACE_HUB_TOKEN`    | `HF_TOKEN`         |

## Из внешних инструментов

Некоторые переменные окружения не являются специфичными для `huggingface_hub`, но всё равно учитываются, если они заданы.

### DO_NOT_TRACK

Логическое значение. Эквивалентно `HF_HUB_DISABLE_TELEMETRY`. Если установлено в true, телеметрия глобально отключается в экосистеме Python Hugging Face (`transformers`, `diffusers`, `gradio` и т. д.). Подробнее см. https://donottrack.sh/.

### NO_COLOR

Логическое значение. Если установлено, CLI `hf` не будет выводить цвета ANSI. См. [no-color.org](https://no-color.org/).

### XDG_CACHE_HOME

Используется только в том случае, если `HF_HOME` не задан!

Это способ по умолчанию для настройки того, куда на машинах с Linux следует записывать [некритичные пользовательские данные (кэш)](https://wiki.archlinux.org/title/XDG_Base_Directory).

Если `HF_HOME` не задан, домашним каталогом по умолчанию будет `"$XDG_CACHE_HOME/huggingface"` вместо `"~/.cache/huggingface"`.