#
Installation

Avant de commencer, vous allez avoir besoin de préparer votre environnement en installant les packages appropriés.

`huggingface_hub` est testée sur Python 3.8+.

##
Installation avec pip

Il est fortement recommandé d’installer `huggingface_hub` dans un environnement virtuel. Si vous n’êtes pas familier avec les environnements virtuels Python, suivez ce guide. Un environnement virtuel sera utile lorsque vous devrez gérer des plusieurs projets en parallèle afin d’éviter les problèmes de compatibilité entre les différentes dépendances.

Commencez par créer un environnement virtuel à l’emplacement de votre projet:

    python -m venv .env

Activez l’environnement virtuel sur Linux et macOS:

    source .env/bin/activate

Activez l’environnement virtuel sur Windows:

    .env/Scripts/activate

Maintenant, vous êtes prêts à installer `hugginface_hub` depuis PyPi:

    pip install --upgrade huggingface_hub

Une fois l’installation terminée, rendez-vous à la section vérification pour s’assurer que tout fonctionne correctement.

###
Installation des dépendances optionnelles

Certaines dépendances de `huggingface_hub` sont optionnelles car elles ne sont pas nécessaire pour faire marcher les fonctionnalités principales de `huggingface_hub`. Toutefois, certaines fonctionnalités de `huggingface_hub` ne seront pas disponibles si les dépendances optionnelles ne sont pas installées

Vous pouvez installer des dépendances optionnelles via `pip`:

    #Installation des dépendances pour les fonctionnalités spécifiques à Tensorflow.
    #/!\ Attention : cette commande n'est pas équivalente à `pip install tensorflow`.
    pip install 'huggingface_hub[tensorflow]'

    #Installation des dépendances spécifiques à Pytorch et au CLI.
    pip install 'huggingface_hub[cli,torch]'

Voici une liste des dépendances optionnelles dans `huggingface_hub`:

- `cli` fournit une interface d’invite de commande plus pratique pour `huggingface_hub`.
- `fastai`, `torch` et `tensorflow` sont des dépendances pour utiliser des fonctionnalités spécifiques à un framework.
- `dev` permet de contribuer à la librairie. Cette dépendance inclut `testing` (pour lancer des tests), `typing` (pour lancer le vérifieur de type) et `quality` (pour lancer des linters).

###
Installation depuis le code source

Dans certains cas, il est intéressant d’installer `huggingface_hub` directement depuis le code source. Ceci vous permet d’utiliser la version `main`, contenant les dernières mises à jour, plutôt que d’utiliser la dernière version stable. La version `main` est utile pour rester à jour sur les derniers développements, par exemple si un bug est corrigé depuis la dernière version officielle mais que la nouvelle version n’a pas encore été faite.

Toutefois, cela signifie que la version `main` peut ne pas être stable. Nous travaillons afin de rendre la version `main` aussi stable que possible, et la plupart des problèmes sont résolus en quelques heures ou jours. Si vous avez un problème, ouvrez une issue afin que nous puissions la régler au plus vite !

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

Lorsque vous installez depuis le code source, vous pouvez préciser la branche depuis laquelle installer. Cela permet de tester une nouvelle fonctionnalité ou un bug-fix qui n’a pas encore été merge:

    pip install git+https://github.com/huggingface/huggingface_hub@ma-branche

Une fois l’installation terminée, rendez-vous à la section vérification pour s’assurer que tout fonctionne correctement.

###
Installation éditable

L’installation depuis le code source vous permet de mettre en place une installation éditable. Cette installation sert surtout si vous comptez contribuer à `huggingface_hub` et que vous avez besoin de tester rapidement des changements dans le code. Pour cela, vous devez cloner le projet `huggingface_hub` sur votre machine.

    # Commencez par cloner le dépôt en local
    git clone https://github.com/huggingface/huggingface_hub.git

    # Ensuite, installez-le avec le flag -e
    cd huggingface_hub
    pip install -e .

Python regardera maintenant à l’intérieur du dossier dans lequel vous avez cloné le dépôt en plus des chemins de librairie classiques. Par exemple, si vos packages Python sont installés dans `./.venv/lib/python3.13/site-packages/`, Python regardera aussi dans le dossier que vous avez cloné `./huggingface_hub/`.

##
Installation avec conda

Si vous avez plutôt l’habitude d’utiliser conda, vous pouvez installer `huggingface_hub` en utilisant le channel conda-forge:

    conda install -c conda-forge huggingface_hub

Une fois l’installation terminée, rendez-vous à la section vérification pour s’assurer que tout fonctionne correctement.

##
Vérification de l’installation

Une fois installée, vérifiez que `huggingface_hub` marche correctement en lançant la commande suivante:

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

Cette commande va récupérer des informations sur le modèle gpt2 depuis le Hub. La sortie devrait ressembler à ça:

    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

##
Les limitations Windows

Afin de démocratiser le machine learning au plus grand nombre, nous avons développé `huggingface_hub` de manière cross-platform et en particulier, pour qu’elle fonctionne sur une maximum de systèmes d’exploitation différents. Toutefois `huggingface_hub` connaît dans certains cas des limitations sur Windows. Nous avons listé ci-dessous les problèmes connus. N’hésitez pas à nous signaler si vous rencontrez un problème non documenté en ouvrant une issue sur Github.

- Le cache de `huggingface_hub` a besoin des symlinks pour mettre en cache les fichiers installés depuis le Hub. Sur windows, vous devez activer le mode développeur pour lancer ou lancer votre script en tant qu’administrateur afin de faire fonctionner les symlinks. S’ils ne sont pas activés, le système de cache fonctionnera toujours mais de manière sous-optimale. Consultez les limitations du cache pour plus de détails.
- Les noms de fichiers sur le Hub peuvent avoir des caractères spéciaux (par exemple `"path/to?/my/file"`). Windows est plus restrictif sur les caractères spéciaux ce qui rend ces fichiers ininstallables sur Windows. Heureusement c’est un cas assez rare. Contactez le propriétaire du dépôt si vous pensez que c’est une erreur ou contactez nous pour que nous cherchions une solution.

##
Prochaines étapes

Une fois que `huggingface_hub` est installé correctement sur votre machine, vous aurez peut-être besoin de configurer les variables d’environnement ou de lire un de nos guides pour vous lancer.

< > Update on GitHub