# Variables d'environnement

`huggingface_hub` peut être configuré à l'aide de variables d'environnement.

Si vous n’êtes pas familier avec les variables d’environnement, voici des articles généraux à leur sujet [sur macOS et Linux](https://linuxize.com/post/how-to-set-and-list-environment-variables-in-linux/) et sur [Windows](https://phoenixnap.com/kb/windows-set-environment-variable).

Cette page vous guide à travers toutes les variables d'environnement spécifiques à `huggingface_hub` et leur signification.

> [!TIP]
> Toutes les variables d’environnement sont lues lors de l’importation de `huggingface_hub`. Toute modification effectuée par la suite ne sera pas prise en compte. Assurez-vous de définir vos variables d’environnement avant d’importer `huggingface_hub`.

## Générique

### HF_INFERENCE_ENDPOINT

Pour configurer l'URL de base de l'API d'inférence. Vous pouvez vouloir définir cette variable si votre organisation pointe vers une API Gateway plutôt que directement vers l'API d'inférence.

Défaut : `"https://api-inference.huggingface.co"`.

### HF_HOME

Pour configurer l’endroit où `huggingface_hub` stockera les données localement. En particulier, votre jeton et le cache seront stockés dans ce dossier.

Défaut : `"~/.cache/huggingface"`, sauf si [XDG_CACHE_HOME](#xdgcachehome) est défini.

### HF_HUB_CACHE

Pour configurer l’endroit où les dépôts du Hub seront mis en cache localement (modèles, jeux de données et espaces).

Défaut : `"$HF_HOME/hub"` (par exemple `"~/.cache/huggingface/hub"` par défaut).

### HF_XET_CACHE

Pour configurer l’endroit où Xet stocke localement son cache de shards et ses données de mise en file d’attente pour le téléversement. Consultez [Xet caching](../guides/manage-cache#xet-caching) pour plus de détails.

Défaut : `"$HF_HOME/xet"` (par exemple `"~/.cache/huggingface/xet"` par défaut).

### HF_ASSETS_CACHE

Pour configurer l’endroit où les [assets](../guides/manage-cache#caching-assets) créés par les bibliothèques en aval sont mis en cache localement. Ces assets peuvent être des données prétraitées, des fichiers téléchargés depuis GitHub, des journaux, etc.

Défaut : `"$HF_HOME/assets"` (par exemple `"~/.cache/huggingface/assets"` par défaut).

### HF_TOKEN

Pour configurer le jeton d’accès utilisateur afin de s’authentifier sur le Hub. Si définie, cette valeur écrasera le jeton stocké sur la machine (dans `$HF_TOKEN_PATH` ou `"$HF_HOME/token"` si le premier n’est pas défini).

Pour plus de détails sur l'authentification, consultez [cette section](../quick-start#authentication).

### HF_TOKEN_PATH

Pour configurer l’endroit où `huggingface_hub` doit stocker le jeton d’accès utilisateur. Par défaut, `"$HF_HOME/token"` (par exemple `~/.cache/huggingface/token` par défaut).

### HF_HUB_VERBOSITY

Définissez le niveau de verbosité du journaliseur de `huggingface_hub`. Doit être l'un des éléments de `{"debug", "info", "warning", "error", "critical"}`.

Défaut : `"warning"`.

Pour plus de détails, voir [référence de journalisation](../package_reference/utilities#huggingface_hub.utils.logging.get_verbosity).

### HF_HUB_ETAG_TIMEOUT

Valeur entière définissant le nombre de secondes à attendre la réponse du serveur lors de la récupération des métadonnées les plus récentes d’un dépôt avant de télécharger un fichier. En cas de dépassement du délai, `huggingface_hub` utilisera par défaut les fichiers mis en cache localement. Une valeur plus basse accélère le flux de travail sur les machines à connexion lente qui ont déjà des fichiers en cache. Une valeur plus élevée garantit que l’appel aux métadonnées réussit dans un plus grand nombre de cas. Valeur par défaut : 10 s.

### HF_HUB_DOWNLOAD_TIMEOUT

Valeur entière définissant le nombre de secondes à attendre la réponse du serveur lors du téléchargement d'un fichier. Si la demande expirée, une TimeoutError est levée. Définir une valeur plus élevée est bénéfique sur une machine avec une connexion lente. Une valeur plus petite permet au processus d'échouer plus rapidement en cas de panne réseau totale. Valeur par défaut : 10 s.

## Xet 

### Autres variables d’environnement 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

Cette variable n'a plus aucun effet. `hf_xet` n'utilise plus de cache local de chunks pour les téléchargements, et la définition de cette variable n'en active pas. Voir [xet-core#715](https://github.com/huggingface/xet-core/issues/715) pour plus de détails.

### HF_XET_SHARD_CACHE_SIZE_LIMIT

Pour définir la taille du cache de shards Xet localement. L’augmentation de cette valeur améliore l’efficacité des téléversements, car les chunks référencés dans les fichiers de shards en cache ne sont pas retéléversés. Notez que la limite douce par défaut est probablement suffisante pour la plupart des charges de travail.

Valeur par défaut : `16000000000` (16 Go).

### HF_XET_NUM_CONCURRENT_RANGE_GETS

Cette variable n'est plus utilisée. Depuis `hf_xet` 1.3.0, la concurrence des téléchargements est contrôlée de manière adaptative.

## Valeurs booléennes

Les variables d’environnement suivantes attendent une valeur booléenne. La variable sera considérée comme `True` si sa valeur est l’une de `{"1", "ON", "YES", "TRUE"}` (insensible à la casse). Toute autre valeur (ou une valeur non définie) sera considérée comme `False`.

### HF_DEBUG

Si défini, le niveau de journalisation de l’enregistreur `huggingface_hub` est réglé sur DEBUG. De plus, toutes les requêtes effectuées par les bibliothèques HF sont journalisées sous forme de commandes cURL équivalentes pour faciliter le débogage et la reproductibilité.

### HF_HUB_OFFLINE

Si défini, aucun appel HTTP ne sera effectué vers le Hugging Face Hub. Si vous tentez de télécharger des fichiers, seuls les fichiers en cache seront accédés. Si aucun fichier en cache n'est détecté, une erreur est levée. Cela est utile si votre réseau est lent et que vous n'avez pas besoin de la dernière version d'un fichier.

Si la variable d’environnement `HF_HUB_OFFLINE=1` est définie et que vous appelez une méthode de [HfApi](/docs/huggingface_hub/v2.4.0/fr/package_reference/hf_api#huggingface_hub.HfApi), une exception [OfflineModeIsEnabled](/docs/huggingface_hub/v2.4.0/fr/package_reference/utilities#huggingface_hub.errors.OfflineModeIsEnabled) est levée.

**Remarque :** même si la dernière version d'un fichier est mise en cache, l'appel de `hf_hub_download` déclenche toujours une requête HTTP pour vérifier qu'aucune nouvelle version n'est disponible. La configuration de `HF_HUB_OFFLINE=1` permet d'ignorer cet appel, ce qui accélère le temps de chargement.

Si vous souhaitez vérifier si le mode hors ligne est activé ou non, vous pouvez utiliser l'assistant [is_offline_mode()](/docs/huggingface_hub/v2.4.0/fr/package_reference/utilities#huggingface_hub.is_offline_mode).

### HF_HUB_DISABLE_IMPLICIT_TOKEN

L’authentification n’est pas obligatoire pour chaque requête adressée au Hub. Par exemple, demander les détails du modèle `"gpt2"` ne nécessite pas d’être authentifié. Toutefois, si un utilisateur est [connecté](../package_reference/login), le comportement par défaut consiste à toujours envoyer le jeton afin de faciliter l’expérience utilisateur (ne jamais recevoir d’erreur HTTP 401 Unauthorized) lors de l’accès à des dépôts privés ou à accès restreint. Pour des raisons de confidentialité, vous pouvez désactiver ce comportement en définissant `HF_HUB_DISABLE_IMPLICIT_TOKEN=1`. Dans ce cas, le jeton ne sera envoyé que pour les appels en « write-access » (par exemple : créer un commit).

**Remarque :** désactiver l’envoi implicite du jeton peut entraîner des effets secondaires inattendus. Par exemple, si vous souhaitez lister tous les modèles du Hub, vos modèles privés ne seront pas affichés. Vous devrez alors passer explicitement l’argument `token=True` dans votre script.

### HF_HUB_DISABLE_PROGRESS_BARS

Pour les tâches chronophages, `huggingface_hub` affiche une barre de progression par défaut (en utilisant tqdm). Vous pouvez désactiver toutes les barres de progression d'un coup en définissant `HF_HUB_DISABLE_PROGRESS_BARS=1`.

### HF_HUB_DISABLE_SYMLINKS

Si défini, `huggingface_hub` ne créera jamais de liens symboliques dans le cache. À la place, les fichiers seront dupliqués ou déplacés directement dans les répertoires de snapshot. Il s’agit d’une fonctionnalité destinée aux utilisateurs avancés, qui fait fonctionner le répertoire de cache en mode dégradé, où les fichiers volumineux finissent par être dupliqués sur votre disque dur.

Un exemple d’utilisation est le cas où un lecteur réseau partagé (par exemple un NAS) est utilisé comme `HF_HUB_CACHE` sur des machines exécutant différents systèmes d’exploitation. Les liens symboliques créés sous Linux ne sont pas toujours accessibles sous Windows, ce qui entraîne des erreurs. Définir `HF_HUB_DISABLE_SYMLINKS=1` évite ce problème au prix de la déduplication de l’espace disque.

### HF_HUB_DISABLE_SYMLINKS_WARNING

Si vous utilisez un système d’exploitation Windows, il est recommandé d’activer le mode développeur ou d’exécuter `huggingface_hub` en mode administrateur. Sinon, `huggingface_hub` ne sera pas en mesure de créer des liens symboliques dans votre système de cache. Vous pourrez exécuter n’importe quel script, mais votre expérience utilisateur sera dégradée car certains fichiers volumineux pourraient finir par être dupliqués sur votre disque dur. Un message d’avertissement est déclenché pour vous alerter sur ce comportement. Définissez `HF_HUB_DISABLE_SYMLINKS_WARNING=1` pour désactiver cet avertissement.

Pour plus de détails, voir [limitations de la cache](../guides/manage-cache#limitations).

### HF_HUB_DISABLE_EXPERIMENTAL_WARNING

Certain fonctionnalités de `huggingface_hub` sont expérimentales. Cela signifie que vous pouvez les utiliser, mais nous ne garantissons pas qu’elles seront maintenues à l’avenir. En particulier, nous pouvons mettre à jour l’API ou le comportement de ces fonctionnalités sans cycle de non-recommandation. Un message d’avertissement est déclenché lors de l’utilisation d’une fonctionnalité expérimentale pour vous en informer. Si vous êtes à l’aise pour déboguer d’éventuels problèmes liés à l’utilisation d’une fonctionnalité expérimentale, vous pouvez définir `HF_HUB_DISABLE_EXPERIMENTAL_WARNING=1` pour désactiver l’avertissement.

Si vous utilisez une fonctionnalité expérimentale, merci de nous le faire savoir ! Vos retours nous aident à la concevoir et à l'améliorer.

### HF_HUB_DISABLE_TELEMETRY

Par défaut, certaines données sont collectées par les bibliothèques HF (`transformers`, `datasets`, `gradio`,..) afin de suivre l’utilisation, de déboguer les problèmes et d’aider à prioriser les fonctionnalités. Chaque bibliothèque définit sa propre politique (c’est-à-dire quel type d’utilisation suivre), mais l’implémentation principale se trouve dans `huggingface_hub` (voir `send_telemetry`).

Vous pouvez définir `HF_HUB_DISABLE_TELEMETRY=1` en tant que variable d'environnement pour désactiver la télémétrie de manière globale.

### HF_HUB_DISABLE_UPDATE_CHECK

Par défaut, le CLI `hf` vérifie sur PyPI s'il existe une version plus récente au démarrage (au maximum une fois toutes les 24 heures) et affiche un avertissement jaune d'une ligne sur stderr lorsqu'une version est disponible, en suggérant `hf update`. La vérification est déjà inopérante sur les versions de développement et de prépublication.

Elle vérifie également (au plus une fois toutes les 24 heures, de manière purement locale) si la compétence `hf-cli` est installée et générée par la version en cours d’exécution, et suggère `hf skills add` / `hf skills update` le cas échéant. Cette vérification n’affiche qu’un indice et ne modifie jamais vos répertoires de compétences.

Avant d’exécuter une [extension CLI](../guides/cli-extensions) installée, il vérifie (au plus une fois toutes les 24 heures par extension) si un commit plus récent est disponible sur GitHub, et suggère `hf extensions update <name>` le cas échéant. `hf extensions list` utilise la même vérification pour sa colonne `LATEST`.

Définissez `HF_HUB_DISABLE_UPDATE_CHECK=1` pour ignorer ces requêtes et supprimer tous ces messages. Pratique dans les environnements CI hors ligne ou si vous préférez une sortie de shell plus sobre.

### HF_HUB_DISABLE_XET

À définir pour désactiver l’utilisation de `hf-xet`, même s’il est disponible dans votre environnement Python. En effet, `hf-xet` est utilisé automatiquement s’il est détecté ; cette option permet donc de désactiver explicitement son utilisation. Si vous désactivez Xet, veuillez envisager de [créer un ticket et d’y inclure les informations de diagnostic](https://github.com/huggingface/xet-core?tab=readme-ov-file#issues-diagnostics--debugging) afin de nous aider à comprendre pourquoi Xet ne fonctionne pas chez vous.

### HF_HUB_ENABLE_HF_TRANSFER

> [!WARNING]
> Il s’agit d’une variable d’environnement obsolète. Maintenant que le Hugging Face Hub est entièrement propulsé par le backend de stockage Xet, tous les transferts de fichiers passent par le paquet binaire `hf-xet`. Il offre des transferts efficaces grâce à une stratégie de déduplication par blocs et s’intègre parfaitement à `huggingface_hub`. Cela signifie que `hf_transfer` ne peut plus être utilisé. Si vous êtes intéressé par des performances supérieures, consultez la [section `HF_XET_HIGH_PERFORMANCE`](#hf_xet_high_performance)

### HF_HUB_DISABLE_SHARED_BLOBS

Définir à `1` pour désactiver le magasin de blobs partagé à l’échelle du cache. Par défaut, les fichiers Xet téléchargés avec succès sont stockés dans `<CACHE_DIR>/blobs/<prefix>/<xet_hash>` et liés symboliquement dans les caches des dépôts, de sorte que les fichiers identiques ne sont stockés sur disque qu’une seule fois entre les dépôts et peuvent être réutilisés sans nouveau téléchargement. Cette optimisation est activée par défaut, mais est désactivée si Xet n’est pas disponible (par exemple si `HF_HUB_DISABLE_XET=1` est défini) ou si les liens symboliques ne sont pas pris en charge localement. Dans ces cas, le système bascule silencieusement sur un stockage local au dépôt. Consultez le [guide de mise en cache](../guides/manage-cache#shared-blobs-across-repos) pour plus de détails.

### HF_XET_HIGH_PERFORMANCE

Définissez `hf-xet` pour fonctionner avec des paramètres accrus afin de maximiser les ressources réseau et disque de la machine. L’activation du mode haute performance tentera de saturer la bande passante réseau de cette machine et d’utiliser tous les cœurs CPU pour une activité de téléchargement/téléversement parallèle.

Considérez ceci comme l'équivalent de la variable d'environnement `HF_HUB_ENABLE_HF_TRANSFER=1` de la version précédente, mais appliquée à `hf-xet`.

Pour en savoir plus sur les avantages du stockage Xet et de `hf_xet`, consultez cette [section](https://huggingface.co/docs/hub/xet/index).

### HF_XET_RECONSTRUCT_WRITE_SEQUENTIALLY

Cette variable n’est plus utilisée. Depuis `hf_xet` 1.3.0, les fichiers sont toujours écrits sur le disque local de manière séquentielle (voir [l’écriture de fichiers dans la v1.3.0](https://github.com/huggingface/xet-core/blob/v1.3.0/file_reconstruction/src/data_writer/data_writer.rs#L76-L91)).

## Variables d'environnement obsolètes

Afin de standardiser toutes les variables d'environnement au sein de l'écosystème Hugging Face, certaines variables ont été marquées comme obsolètes. Bien qu'elles restent fonctionnelles, elles ne prennent plus le pas sur leurs remplaçants. Le tableau suivant détaille les variables obsolètes et leurs alternatives correspondantes :

| Variable obsolète         | Remplacement        |
| --------------------------- | ------------------ |
| `HUGGINGFACE_HUB_CACHE`     | `HF_HUB_CACHE`     |
| `HUGGINGFACE_ASSETS_CACHE`  | `HF_ASSETS_CACHE`  |
| `HUGGING_FACE_HUB_TOKEN`    | `HF_TOKEN`         |

## Depuis des outils externes

Certaines variables d'environnement ne sont pas spécifiques à `huggingface_hub` mais sont tout de même prises en compte lorsqu'elles sont définies.

### DO_NOT_TRACK

Valeur booléenne. Équivalent à `HF_HUB_DISABLE_TELEMETRY`. Lorsqu’elle est définie sur true, la télémétrie est désactivée globalement dans l’écosystème Python de Hugging Face (`transformers`, `diffusers`, `gradio`, etc.). Voir https://donottrack.sh/ pour plus de détails.

### NO_COLOR

Valeur booléenne. Si définie, l'interface en ligne de commande `hf` n'affichera aucune couleur ANSI. Voir [no-color.org](https://no-color.org/).

### XDG_CACHE_HOME

Utilisé uniquement lorsque `HF_HOME` n'est pas défini !

C'est la méthode par défaut pour configurer l'emplacement où [les données non essentielles (en cache) spécifiques à l'utilisateur doivent être écrites](https://wiki.archlinux.org/title/XDG_Base_Directory) sur les machines linux.

Si `HF_HOME` n'est pas défini, le répertoire par défaut sera `"$XDG_CACHE_HOME/huggingface"` au lieu de `"~/.cache/huggingface"`.