Hub Python Library documentation
Variables d'environnement
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 et sur Windows.
Cette page vous guide à travers toutes les variables d'environnement spécifiques à huggingface_hub et leur signification.
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’importerhuggingface_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://huggingface.co/proxy/api-inference.huggingface.co".
HF_HOME
Pour configurer l’endroit où huggingface_hub stockera localement les données. En particulier, votre jeton et le cache seront stockés dans ce dossier.
Défaut : "~/.cache/huggingface", sauf si XDG_CACHE_HOME 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 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 créés par les bibliothèques en aval seront 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.
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.
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_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 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, une exception 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().
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é, 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 nécessitant un « accès en écriture » (par exemple : créer un commit).
Remarque : désactiver l’envoi implicite du jeton peut avoir des effets secondaires inattendus. Par exemple, si vous souhaitez lister tous les modèles du Hub, vos modèles privés ne seront pas listés. Vous devrez 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 lorsque 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.
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 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 afin de nous aider à comprendre pourquoi Xet ne fonctionne pas chez vous.
HF_HUB_ENABLE_HF_TRANSFER
Cette variable d’environnement est 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 quehf_transferne peut plus être utilisé. Si vous êtes intéressé par des performances supérieures, consultez la sectionHF_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 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.
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).
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.). Consultez 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.
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 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".