Jeton Hugging Face : comment le créer, le stocker et l'utiliser

Un token Hugging Face est un User Access Token qui authentifie votre machine, script ou job CI auprès du Hugging Face Hub. Vous en créez un dans les paramètres de votre compte sous l'onglet Access Tokens , choisissez un rôle (lire, write ou fine-grained), puis soit exécutez hf auth login et collez-le, soit définissez HF_TOKEN dans votre environnement. Les tokens ressemblent à hf_....

Ce que le token autorise réellement

Trois choses, en pratique : télécharger des fichiers depuis des dépôts privés ou gated, pousser des fichiers vers des dépôts que vous pouvez écrire, et appeler Fournisseurs d’inférence comme bearer token. Les poids publics des modèles n'ont besoin d'aucun token — hf download gpt2 config.json fonctionne sans authentification.

La documentation de Hugging Face décrit le token comme utilisable «à la place d'un mot de passe» pour git et l'authentification basique, ce qui est le bon modèle mental : c'est une credential, pas une API key liée à un produit.

Les trois types de tokens

Rôle	Accorde	L'utiliser pour
lire	Accès en lecture à chaque repo que vous pouvez déjà lire, incluant les repos privés que vous ou vos organisations possédez	Télécharger des poids gated, exécuter l'inférence, notebooks
write	Tout lire le fait, plus accès en écriture aux repos où vous pouvez écrire	Pousser des checkpoints, éditer des model cards, exécutions d'entraînement qui téléchargent
fine-grained	Uniquement les ressources spécifiques et permissions que vous cochez	Applications de production, CI, tout ce qui est partagé avec une équipe

Hugging Face recommande explicitement les tokens à granularité fine pour un usage en production, au motif que le rayon de blast s'il y a une fuite est plus petit et qu'il peut être partagé au sein d'une organisation sans exposer l'ensemble de votre compte. Un pattern de production typique : un membre de l'organisation demande l'accès à un modèle gated, puis crée un token à granularité fine avec accès en lecture à ce repo uniquement.

Créer un token, étape par étape

1. Connectez-vous, cliquez sur votre avatar (en haut à droite) → Settings.
2. Ouvrez le Access Tokens tab — URL directe huggingface.co/settings/tokens.
3. Cliquer New token.
4. Nommez-le d'après la machine ou l'application qui le conservera (laptop-read, ci-push), pas d'après vous-même. Un token par usage est la meilleure pratique documentée, de sorte que vous pouvez en révoquer un sans casser le reste.
5. Sélectionnez le rôle. Pour à granularité fine, cochez les permissions individuelles.
6. Copiez la valeur immédiatement. Plus tard, vous ne pouvez que la supprimer ou l'actualiser depuis la même page via Manage.

Si vous êtes sur une organisation Team ou Enterprise avec une politique de token, un token à granularité fine limité à cette organisation peut se retrouver dans un état Pending jusqu'à ce qu'un admin l'approuve — la liste des tokens affiche un sablier orange à côté, et les appels sur les ressources de l'organisation retournent 403 jusqu'à approbation.

Se connecter depuis le terminal

La CLI fournie avec huggingface_hub s'appelle hf. Installez et connectez-vous :

pip install huggingface_hub
hf auth login

Par défaut, cela exécute maintenant un flux de périphérique navigateur : il affiche une URL (https://huggingface.co/oauth/device) et un code court tel que ABCD-EFGH. Approuvez-le dans le navigateur et la CLI enregistre un token nommé oauth- qui s'actualise tant que vous continuez à l'utiliser. Choisir Paste an access token vous permet à la place de fournir un token que vous avez créé manuellement.

Note sur la nomenclature : les tutoriels plus anciens utilisent huggingface-cli login. L'ensemble des commandes a été réorganisé sous hf auth ..., et l'orthographe que votre machine accepte dépend de la huggingface_hub version installée — exécutez hf --help pour voir ce que vous avez réellement.

Commande	À quoi ça sert
hf auth login --token $HF_TOKEN	Connexion non interactive, sûre pour les scripts
hf auth login --token $HF_TOKEN --add-to-git-credential	Écrit également le token dans votre gestionnaire de credentials git
hf auth login --force	Se reconnecter même si déjà authentifié
hf auth whoami	Affiche votre nom d'utilisateur et vos organisations ; erreur si non connecté
hf auth list	Répertorie les noms de token stockés sur la machine
hf auth switch --token-name NAME	Bascule vers le token actif
hf auth token	Affiche le token actif sur stdout
hf auth logout --token-name NAME	Supprime un token stocké (omettez l'indicateur pour supprimer tous)
hf env	Affiche le chemin du token, s'il est enregistré, et les gestionnaires git configurés

Transmettez le token via $HF_TOKEN plutôt que de taper la chaîne littérale — la documentation met en garde contre le collage de tokens bruts dans les lignes de commande où l'historique du shell et les logs CI peuvent les capturer.

Où le token est stocké

Plusieurs tokens nommés vivent dans un stored_tokens fichier ; celui actuellement actif est reflété dans un fichier simple token fichier. Les deux se trouvent sous HF_HOME, qui par défaut pointe vers ~/.cache/huggingface.

Linux

~/.cache/huggingface/token et ~/.cache/huggingface/stored_tokens. Si XDG_CACHE_HOME est défini et HF_HOME ne l'est pas, la base devient $XDG_CACHE_HOME/huggingface à la place.

macOS

Identique à Linux : ~/.cache/huggingface/token. Hugging Face n'utilise pas ~/Library/Caches ici, donc ne le cherchez pas là.

Windows

Le chemin se résout à partir de votre répertoire personnel : C:\Users\<you>\.cache\huggingface\token. Deux particularités spécifiques à Windows à connaître. Premièrement, le cache des modèles utilise des liens symboliques, qui nécessitent le Mode Développeur ou un shell administrateur ; sans eux, vous recevez un avertissement et des fichiers dupliqués sur le disque, silencieux avec HF_HUB_DISABLE_SYMLINKS_WARNING=1. Deuxièmement, si vous pointez HF_HUB_CACHE vers un NAS partagé avec des machines Linux, réglez HF_HUB_DISABLE_SYMLINKS=1 — les liens symboliques écrits sur Linux ne sont pas fiablement traversables sur Windows.

Les variables d'environnement qui importent

Variable	Effet	Par défaut
HF_TOKEN	Fournit le jeton ; remplace le jeton stocké sur le disque	non définie
HF_TOKEN_PATH	D'où le fichier jeton est lu et écrit	$HF_HOME/token
HF_HOME	Dossier de base pour le jeton plus le cache	~/.cache/huggingface
HF_HUB_DISABLE_IMPLICIT_TOKEN	Empêche le jeton d'être attaché aux requêtes de lecture qui ne l'exigent pas ; il est alors envoyé uniquement pour les appels d'écriture	désactivé
HUGGING_FACE_HUB_TOKEN	Alias dépréciée — fonctionne toujours, mais n'a plus la priorité sur HF_TOKEN	—

Deux pièges. Ces variables sont lues au moment de l'import de huggingface_hub, donc en définir une après l'import n'a aucun effet — redémarrez le noyau. Et hf auth logout ne peut pas vous déconnecter d'un jeton fourni via HF_TOKEN; vous devez désactiver la variable.

Utiliser le token avec git

Le clonage de grands dépôts via HTTPS demande un mot de passe — fournissez le jeton, pas votre mot de passe de compte :

git clone https://huggingface.co/<user>/<repo>
# Username: your-hf-username
# Password: hf_...

Pour éviter de retaper, connectez-vous avec --add-to-git-credential, ce qui remet le jeton à votre assistant configuré (store sur Linux, Keychain sur macOS, Gestionnaire des identifiants Windows sur Windows). Confirmez ce qui est branché avec hf env, qui imprime une Configured git credential helpers ligne.

Utiliser le token pour l'inférence hébergée

Le même jeton est la credential bearer pour les Inference Providers, qui expose un point de terminaison compatible OpenAI à https://router.huggingface.co/v1:

curl https://router.huggingface.co/v1/chat/completions 
    -H "Authorization: Bearer $HF_TOKEN" 
    -H 'Content-Type: application/json' 
    -d '{"model": "openai/gpt-oss-120b", "messages": [{"role": "user", "content": "hello"}]}'

Pour ce chemin, un jeton à granularité fine avec la permission Make calls to Inference Providers est le mieux adapté. Sur la facturation, Hugging Face publie des crédits mensuels de 0,10 $ pour les comptes gratuits, 2,00 $ pour PRO, et 2,00 $ par siège pour les orgs Team et Enterprise, puis pay-as-you-go aux tarifs du fournisseur lui-même sans majoration HF. Les orgs Team et Enterprise peuvent centraliser la facturation en envoyant X-HF-Bill-To: my-org-name comme en-tête tandis que chaque membre conserve son propre jeton.

Ces crédits s'épuisent rapidement aux tarifs des modèles frontière — un modèle tarifé comme Claude Opus 5 à 5,00 $ en entrée / 25,00 $ en sortie par 1M de jetons consomme 2,00 $ pour environ 80k tokens en sortie. Les modèles open-weights sont d'un ordre de grandeur différent : Llama 3.3 70B coûte 0,10 $ en / 0,32 $ en sortie par 1M tokens, et Llama 3.1 8B 0,02 $ en / 0,03 $ en sortie. Évaluez le Calculateur de coûts d’API par rapport à votre volume de tokens avant de câbler un token dans quelque chose qui boucle.

Modèles gated : le token est nécessaire mais pas suffisant

Pour les dépôts gérés — la plupart des versions Llama et Gemma — un token valide ne confère que l'accès que vous avez déjà obtenu. Selon la documentation des modèles gérés de Hugging Face, la demande d'accès elle-même «ne peut se faire que depuis votre navigateur» : ouvrez la page du modèle connecté, complétez le formulaire, cliquez sur Agree. L'approbation est automatique ou manuelle, et les auteurs peuvent la révoquer plus tard sans préavis. C'est seulement après que hf auth login déverrouille le téléchargement dans un script. Généralement vous verrez un 401 quand aucun token n'est envoyé et un 403 quand le token est valide mais votre compte n'a pas accès.

Quand vous n'avez pas besoin d'un token du tout

Les poids publics non gérés se téléchargent sans identifiants, donc une pile purement locale n'a souvent besoin d'aucun token. Ollama récupère entièrement depuis son propre registre, et llama.cpp ou LM Studio peuvent récupérer les GGUFs publics anonymement. Ce qui décide de votre configuration, c'est la mémoire, pas l'authentification : Llama 3.1 8B a besoin d'environ 5 GB de VRAM à 4-bit et Llama 3.3 70B d'environ 40 GB, tandis que DeepSeek R1 veut environ 400 GB et Kimi K3 environ 1,4 TB — du territoire cluster. Vérifiez le vôtre par rapport à la calculatrice VRAM ou le tableau des besoins en VRAM par modèle.

Dépannage

Symptôme	Cause probable	Correctif
401 Unauthorized	Aucun token envoyé, ou il a été supprimé côté serveur	hf auth whoami; relancez hf auth login --force
403 sur un dépôt géré	Le token est bon ; le compte n'a pas accès	Demandez l'accès dans le navigateur sur la page du modèle
403 avec « révoqué par l'administrateur de l'organisation »	L'organisation d'entreprise a révoqué le token — permanent	Supprimez-le et créez-en un nouveau
Fonctionne en shell, échoue dans le notebook	HF_TOKEN défini après l'importation, ou un environnement de kernel différent	Redémarrez le kernel ; vérifiez avec hf env
Vos modèles privés manquent dans un listing	HF_HUB_DISABLE_IMPLICIT_TOKEN=1 est défini	Passez Le flag token=True explicitement, ou désactivez-le
Token de lecture rejeté par une organisation	La politique de l'organisation n'autorise que les tokens à grain fin	Créez un token à grain fin limité à cette organisation

Si un token fuit

Supprimez-le ou actualisez-le depuis l'onglet Access Tokens. Si vous trouvez un token de quelqu'un d'autre — dans un dépôt public, un Space, un log — vous pouvez l'invalider sans posséder le compte, via POST https://huggingface.co/api/credentials/revoke avec un corps JSON de {"credentials": ["hf_..."]}. Les tokens correspondants disparaissent immédiatement et le propriétaire reçoit un email. L'endpoint retourne toujours 202 Accepted que le token existe ou non, donc il ne peut pas être abusé pour tester si un token est actif. Pour CI, la réponse plus propre est de ne pas stocker un token long terme du tout : Trusted Publishers échange l'identité OIDC de votre fournisseur CI pour un token Hub court terme par exécution.

Questions fréquemment posées

Un token Hugging Face est-il gratuit ?

Oui. La création de tokens ne coûte rien sur aucun niveau de compte, et il n'y a pas de limite documentée au nombre que vous pouvez détenir. Les frais n'apparaissent que lorsqu'un token est utilisé contre du calcul payant — Inference Providers au-delà de vos crédits mensuels, Inference Endpoints, matériel Spaces amélioré ou Jobs.

Les tokens Hugging Face expirent-ils ?

Les tokens que vous créez manuellement dans les paramètres n'ont pas d'expiration — ils durent jusqu'à ce que vous les supprimiez ou les actualisiez. Les tokens créés par le flux de dispositif du navigateur lors de hf auth login sont l'exception : ils expirent, mais s'actualisent automatiquement tant que vous les utilisez.

Quelle est la différence entre lecture, écriture et grain fin ?

lire peut télécharger tout ce que vous pouvez déjà voir, y compris les dépôts privés. write ajoute l'accès en push. fine-grained commence de zéro et n'accorde que ce que vous cochez, c'est pourquoi Hugging Face le recommande pour la production et pourquoi certaines organisations rejettent purement et simplement les tokens lecture/écriture avec un 403.

Puis-je utiliser un token sur plusieurs machines ?

Techniquement oui, mais la meilleure pratique documentée est un token par machine ou application — ordinateur portable, notebook Colab, serveur d'inférence. Faire tourner un token partagé casse chaque consommateur à la fois ; faire tourner un token par machine n'en casse qu'un.

Ai-je besoin d'un token pour exécuter des modèles localement ?

Only for gated or private weights. Public ungated models download anonymously, and Ollama’s registry needs no credentials — see the Guide d'installation Ollama. Le fait que local ait du sens par rapport à une API est généralement une question d'économie ; la calculatrice auto-hébergement vs API donne un nombre de point mort.

Où dois-je mettre le token dans Google Colab ?

Utilisez le panneau des secrets de Colab (l'icône clé) pour le stocker en tant que HF_TOKEN plutôt que de le coder en dur dans une cellule, puis activez l'accès au notebook. Les notebooks sont committés et partagés beaucoup plus facilement que les fichiers source, et un token collé dans une cellule voyage avec la copie.

Sources

• Hugging Face Hub — Tokens d'accès utilisateur (rôles, bonnes pratiques, révocation d'un token divulgué, politiques de token d'organisation)
• huggingface_hub — Variables d'environnement (HF_TOKEN, HF_TOKEN_PATH, HF_HOME valeurs par défaut)
• huggingface_hub — Référence CLI (hf auth sous-commandes et drapeaux)
• Inference Providers — Tarification et facturation (crédits mensuels, X-HF-Bill-To)
• Hugging Face Hub — Modèles restreints (demandes d'accès, flux d'approbation par navigateur uniquement)

Les prix des modèles et les chiffres de VRAM proviennent de Base de données des modèles Convly. Comparez les capacités par rapport au coût sur Classement des grands modèles linguistiques (LLM).