Installation

Avant de commencer, vous devez configurer votre environnement en installant les paquets appropriés.

huggingface_hub est testé sur Python 3.10+.

Installer avec pip

Il est vivement recommandé d'installer huggingface_hub dans un environnement virtuel. Si vous n'êtes pas familier avec les environnements virtuels Python, consultez ce guide. Un environnement virtuel facilite la gestion de différents projets et permet d'éviter les problèmes de compatibilité entre les dépendances.

Commencez par créer un environnement virtuel dans le répertoire de votre projet :

python -m venv .venv

Activez l'environnement virtuel. Sur Linux et macOS :

source .venv/bin/activate

Activer l'environnement virtuel sur Windows :

.venv/Scripts/activate

Vous êtes maintenant prêt à installer huggingface_hub depuis le registre PyPi :

pip install --upgrade huggingface_hub

Une fois terminé, vérifiez que check installation fonctionne correctement.

Installer les dépendances facultatives

Certaines dépendances de huggingface_hub sont facultatives car elles ne sont pas nécessaires pour exécuter les fonctionnalités principales de huggingface_hub. Toutefois, certaines fonctionnalités de huggingface_hub peuvent ne pas être disponibles si les dépendances facultatives ne sont pas installées.

Vous pouvez installer les dépendances facultatives via pip :

# Install dependencies for both torch-specific and MCP-specific features.
pip install 'huggingface_hub[mcp,torch]'

Voici la liste des dépendances facultatives de huggingface_hub :

• fastai, torch : dépendances pour exécuter les fonctionnalités spécifiques au framework.
• dev : dépendances pour contribuer à la bibliothèque. Inclut testing (pour exécuter les tests), typing (pour exécuter le vérificateur de types) et quality (pour exécuter les linters).

Installer à partir du code source

Dans certains cas, il est intéressant d’installer huggingface_hub directement depuis le code source. Cela permet d’utiliser la version main la plus récente plutôt que la dernière version stable. La version main est utile pour rester à jour avec les derniers développements, par exemple si un bug a été corrigé depuis la dernière publication officielle mais qu’une nouvelle version n’a pas encore été déployée.

However, this means the main version may not always be stable. We strive to keep the main version operational, and most issues are usually resolved within a few hours or a day. If you run into a problem, please open an Issue so we can fix it even sooner!

pip install git+https://github.com/huggingface/huggingface_hub

Lors de l’installation à partir du code source, vous pouvez également spécifier une branche particulière. Cela est utile si vous souhaitez tester une nouvelle fonctionnalité ou un correctif de bug qui n’a pas encore été fusionné :

pip install git+https://github.com/huggingface/huggingface_hub@my-feature-branch

Une fois terminé, vérifiez que check installation fonctionne correctement.

Installation modifiable

L'installation à partir du code source vous permet de configurer une installation modifiable. Il s'agit d'une installation plus avancée si vous prévoyez de contribuer à huggingface_hub et devez tester des modifications dans le code. Vous devez cloner une copie locale de huggingface_hub sur votre machine.

# First, clone repo locally
git clone https://github.com/huggingface/huggingface_hub.git

# Then, install with -e flag
cd huggingface_hub
pip install -e .

Ces commandes associent le dossier dans lequel vous avez cloné le dépôt à vos chemins de bibliothèques Python. Python recherchera désormais dans le dossier cloné en plus des chemins de bibliothèques habituels. Par exemple, si vos paquets Python sont généralement installés dans ./.venv/lib/python3.13/site-packages/, Python recherchera également dans le dossier que vous avez cloné ./huggingface_hub/.

Installer le CLI Hugging Face

Utilisez nos installateurs en une ligne pour configurer le CLI hf sans toucher à votre environnement Python :

Sur macOS et Linux :

curl -LsSf https://hf.co/cli/install.sh | bash

Sous Windows :

powershell -ExecutionPolicy ByPass -c "irm https://hf.co/cli/install.ps1 | iex"

Pour mettre à jour une installation existante, exécutez hf update — il détecte la méthode d’installation de hf (installateur autonome, Homebrew ou pip) et exécute la commande correspondante.

Installer avec conda

Si vous êtes plus familier avec ce dernier, vous pouvez installer huggingface_hub en utilisant le canal conda-forge :

conda install -c conda-forge huggingface_hub

Une fois terminé, vérifiez que check installation fonctionne correctement.

Vérifier l'installation

Une fois installé, vérifiez que huggingface_hub fonctionne correctement en exécutant la commande suivante :

python -c "from huggingface_hub import model_info; print(model_info('gpt2'))"

Cette commande récupère des informations sur le modèle gpt2 depuis le Hub. La sortie doit ressembler à ceci :

Model Name: gpt2
Tags: ['pytorch', 'tf', 'jax', 'tflite', 'rust', 'safetensors', 'gpt2', 'text-generation', 'en', 'doi:10.57967/hf/0039', 'transformers', 'exbert', 'license:mit', 'has_space']
Task: text-generation

Limitations de Windows

Dans le cadre de notre objectif de démocratiser le bon ML partout, nous avons conçu huggingface_hub comme une bibliothèque multiplateforme, et en particulier pour qu'elle fonctionne correctement sur les systèmes basés sur Unix et Windows. Toutefois, il existe quelques cas où huggingface_hub présente certaines limitations lorsqu'elle est exécutée sur Windows. Voici une liste exhaustive des problèmes connus. N'hésitez pas à nous signaler tout problème non documenté en ouvrant un ticket sur Github.

• Le système de cache de huggingface_hub s’appuie sur des liens symboliques pour mettre efficacement en cache les fichiers téléchargés depuis le Hub. Sur Windows, vous devez activer le mode développeur ou exécuter votre script en tant qu’administrateur pour autoriser les liens symboliques. S’ils ne sont pas activés, le système de cache fonctionne toujours, mais de manière non optimisée. Veuillez consulter la section limites du cache pour plus de détails.
• Les chemins de fichiers sur le Hub peuvent contenir des caractères spéciaux (par exemple "path/to?/my/file"). Windows est plus restrictif quant aux caractères spéciaux, ce qui rend impossible le téléchargement de ces fichiers sur Windows. Heureusement, il s’agit d’un cas rare. Veuillez contacter le propriétaire du dépôt si vous pensez qu’il s’agit d’une erreur, ou nous contacter pour trouver une solution.

Étapes suivantes

Une fois huggingface_hub correctement installé sur votre machine, vous pouvez configurer les variables d’environnement ou consulter l’un de nos guides pour commencer.