Démarrage rapide

Le Hugging Face Hub est la référence pour partager des modèles de machine learning, des démos, des jeux de données et des métriques. La bibliothèque huggingface_hub vous aide à interagir avec le Hub sans quitter votre environnement de développement. Vous pouvez créer et gérer des dépôts facilement, télécharger et téléverser des fichiers, et obtenir des métadonnées utiles sur les modèles et les jeux de données depuis le Hub.

Installation

Pour commencer, installez la bibliothèque huggingface_hub :

pip install --upgrade huggingface_hub

Pour plus de détails, consultez le guide d'installation.

Le huggingface_hub est également livré avec une CLI hf qui vous permet d’interagir avec le Hub directement depuis le terminal. Si vous utilisez des agents IA (Claude Code, Codex, Cursor, …), installez le Skill pour permettre à votre agent d’utiliser la CLI :

Copié

# works with Claude Code, Codex, Cursor, OpenCode, Pi and any agent that loads skills from `.agents/skills`
hf skills add

Consultez le guide Hugging Face CLI for AI Agents pour plus de détails.

Télécharger les fichiers

Les dépôts sur le Hub sont gérés par le contrôle de version git, et les utilisateurs peuvent télécharger un fichier unique ou l’ensemble du dépôt. Vous pouvez utiliser la fonction hf_hub_download() pour télécharger des fichiers. Cette fonction télécharge et met en cache un fichier sur votre disque local. La prochaine fois que vous aurez besoin de ce fichier, il sera chargé depuis votre cache, vous n’aurez donc pas à le retélécharger.

Vous aurez besoin de l’identifiant du dépôt et du nom du fichier que vous souhaitez télécharger. Par exemple, pour télécharger le fichier de configuration du modèle Pegasus :

>>> from huggingface_hub import hf_hub_download
>>> hf_hub_download(repo_id="google/pegasus-xsum", filename="config.json")

Pour télécharger une version spécifique du fichier, utilisez le paramètre revision pour indiquer le nom de la branche, le tag ou l'identifiant de commit. Si vous choisissez d'utiliser l'identifiant de commit, il doit s'agir de l'identifiant complet et non de l'identifiant court de 7 caractères :

>>> from huggingface_hub import hf_hub_download
>>> hf_hub_download(
...     repo_id="google/pegasus-xsum",
...     filename="config.json",
...     revision="4d33b01d79672f27f001f6abade33f22d993b151"
... )

Pour plus de détails et d'options, consultez la référence de l'API de hf_hub_download().

Authentification

Dans de nombreux cas, vous devez être authentifié avec un compte Hugging Face pour interagir avec le Hub : télécharger des dépôts privés, téléverser des fichiers, créer des PR, etc. Créez un compte si vous n’en avez pas encore.

Commande de connexion

La façon la plus simple de s’authentifier est d’utiliser la commande login() :

hf auth login

Si vous êtes déjà connecté, la commande se termine immédiatement. Pour forcer une nouvelle connexion, utilisez hf auth login --force. Si vous n’êtes pas connecté, on vous demandera de vous connecter via votre navigateur : ouvrez l’URL affichée, saisissez le code court, approuvez la demande, puis un jeton d’accès est récupéré et enregistré dans votre répertoire HF_HOME (par défaut ~/.cache/huggingface/token). Le jeton expire après un certain temps, mais il est renouvelé automatiquement tant que vous continuez à l’utiliser. Tout script ou bibliothèque interagissant avec le Hub utilisera ce jeton lors de l’envoi de requêtes. Vous pouvez également coller un User Access Token généré depuis votre Settings page.

Les jetons d’accès utilisateur peuvent disposer des autorisations read ou write. Assurez-vous de disposer d’un jeton d’accès write si vous souhaitez créer ou modifier un dépôt. Sinon, il est préférable de générer un jeton read afin de réduire les risques en cas de fuite accidentelle de votre jeton.

Sinon, vous pouvez vous connecter de manière programmatique en utilisant login() dans un notebook ou un script :

>>> from huggingface_hub import login
>>> login()

Vous ne pouvez être connecté qu’à un seul compte à la fois. La connexion à un nouveau compte vous déconnecte automatiquement du précédent. Pour déterminer le compte actuellement actif, exécutez simplement la commande hf auth whoami.

Une fois connecté, toutes les requêtes vers le Hub – y compris les méthodes qui n’exigent pas nécessairement d’authentification – utiliseront par défaut votre jeton d’accès. Si vous souhaitez désactiver l’utilisation implicite de votre jeton, vous devez définir HF_HUB_DISABLE_IMPLICIT_TOKEN=1 en tant que variable d’environnement (voir référence).

Gérer plusieurs jetons localement

Vous pouvez enregistrer plusieurs jetons sur votre machine en vous connectant simplement avec la commande login() pour chaque jeton. Si vous devez basculer entre ces jetons localement, vous pouvez utiliser la commande auth switch :

hf auth switch

Cette commande vous invite à sélectionner un jeton par son nom à partir d'une liste de jetons enregistrés. Une fois sélectionné, le jeton choisi devient le jeton actif et sera utilisé pour toutes les interactions avec le Hub.

Vous pouvez lister tous les jetons d'accès disponibles sur votre machine avec hf auth list.

Variable d'environnement

La variable d’environnement HF_TOKEN peut également être utilisée pour vous authentifier. C’est particulièrement utile dans un Space où vous pouvez définir HF_TOKEN comme secret de Space.

NOUVEAU : Google Colaboratory vous permet de définir des clés privées pour vos notebooks. Définissez un secret HF_TOKEN pour être authentifié automatiquement !

L'authentification via une variable d'environnement ou un secret a la priorité sur le jeton stocké sur votre machine.

Paramètres de la méthode

Enfin, il est également possible de s'authentifier en passant votre jeton à toute méthode qui accepte token en tant que paramètre.

from huggingface_hub import whoami

user = whoami(token=...)

Cela est généralement déconseillé, sauf dans un environnement où vous ne souhaitez pas stocker votre jeton de manière permanente ou si vous devez gérer plusieurs jetons simultanément.

Veuillez faire preuve de prudence lors de la transmission de jetons en tant que paramètre. La meilleure pratique consiste toujours à charger le jeton depuis un coffre-fort sécurisé plutôt que de le coder en dur dans votre base de code ou votre notebook. Les jetons codés en dur présentent un risque majeur de fuite si vous partagez votre code par inadvertance.

Créer un dépôt

Une fois votre inscription et votre connexion effectuées, créez un dépôt à l’aide de la fonction create_repo() :

>>> from huggingface_hub import HfApi
>>> api = HfApi()
>>> api.create_repo(repo_id="super-cool-model")

Si vous souhaitez que votre dépôt soit privé, alors :

>>> from huggingface_hub import HfApi
>>> api = HfApi()
>>> api.create_repo(repo_id="super-cool-model", private=True)

Les dépôts privés ne seront visibles que par vous-même.

Pour créer un dépôt ou pousser du contenu vers le Hub, vous devez fournir un jeton d'accès utilisateur disposant de l'autorisation write. Vous pouvez choisir l'autorisation lors de la création du jeton sur votre page Paramètres.

Téléverser des fichiers

Utilisez la fonction upload_file() pour ajouter un fichier à votre nouvellement créé dépôt. Vous devez spécifier :

1. Le chemin du fichier à téléverser.
2. Le chemin du fichier dans le dépôt.
3. L'identifiant du dépôt où vous souhaitez ajouter le fichier.

>>> from huggingface_hub import HfApi
>>> api = HfApi()
>>> api.upload_file(
...     path_or_fileobj="/home/lysandre/dummy-test/README.md",
...     path_in_repo="README.md",
...     repo_id="lysandre/test-model",
... )

Pour téléverser plus d’un fichier à la fois, consultez le guide Upload qui vous présente plusieurs méthodes de téléversement de fichiers (avec ou sans git).

Étapes suivantes

La bibliothèque huggingface_hub offre aux utilisateurs un moyen simple d’interagir avec le Hub en Python. Pour en savoir plus sur la gestion de vos fichiers et dépôts sur le Hub, nous vous recommandons de consulter nos guides pratiques pour :

• Gérer votre dépôt.
• Télécharger des fichiers depuis le Hub.
• Téléverser des fichiers sur le Hub.
• Recherchez sur le Hub le modèle ou le jeu de données souhaité.
• Exécuter l’inférence sur plusieurs services pour les modèles hébergés sur le Hugging Face Hub.