# 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.10+**. ## Installation avec pip Il est fortement recommandé d'installer `huggingface_hub` dans un [environnement virtuel](https://docs.python.org/3/library/venv.html). Si vous n'êtes pas familier avec les environnements virtuels Python, suivez ce [guide](https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/). 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: ```bash python -m venv .venv ``` Activez l'environnement virtuel sur Linux et macOS: ```bash source .venv/bin/activate ``` Activez l'environnement virtuel sur Windows: ```bash .venv/Scripts/activate ``` Maintenant, vous êtes prêts à installer `hugginface_hub` [depuis PyPi](https://pypi.org/project/huggingface-hub/): ```bash pip install --upgrade huggingface_hub ``` Une fois l'installation terminée, rendez-vous à la section [vérification](#verification-de-l-installation) pour s'assurer que tout fonctionne correctement. ### Installation des dépendances optionnelles Certaines dépendances de `huggingface_hub` sont [optionnelles](https://setuptools.pypa.io/en/latest/userguide/dependency_management.html#optional-dependencies) 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`: ```bash # Installation des dépendances spécifiques à Pytorch et à MCP. pip install 'huggingface_hub[mcp,torch]' ``` Voici une liste des dépendances optionnelles dans `huggingface_hub`: - `mcp`: fonctionnalités spécifiques à MCP pour `huggingface_hub`. - `fastai`, `torch` 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 ! ```bash 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: ```bash pip install git+https://github.com/huggingface/huggingface_hub@ma-branche ``` Une fois l'installation terminée, rendez-vous à la section [vérification](#verification-de-l-installation) pour s'assurer que tout fonctionne correctement. ### Installation éditable L'installation depuis le code source vous permet de mettre en place une [installation éditable](https://pip.pypa.io/en/stable/topics/local-project-installs/#editable-installs). 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. ```bash # 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](https://anaconda.org/conda-forge/huggingface_hub): ```bash conda install -c conda-forge huggingface_hub ``` Une fois l'installation terminée, rendez-vous à la section [vérification](#verification-de-l-installation) 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: ```bash 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](https://huggingface.co/gpt2) depuis le Hub. La sortie devrait ressembler à ça: ```text 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](https://github.com/huggingface/huggingface_hub/issues/new/choose). - 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](./guides/manage-cache#limitations) 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](https://learn.microsoft.com/en-us/windows/win32/intl/character-sets-used-in-file-names) 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](package_reference/environment_variables) ou de [lire un de nos guides](guides/overview) pour vous lancer.