Vérification

pip (Python)

pip install requests et la bibliothèque est là. C'est toute l'histoire, jusqu'à ce que vous découvriez sur un serveur avec trois versions de Python que vous avez mis quelque chose dans le mauvais environnement.

Cet article traite de pip tel que vous le rencontrez sur un serveur Linux : quelle version vous avez besoin, comment installer des paquets sans détruire votre Python système, et comment rendre un environnement reproductible pour qu'un déploiement ne dépende pas de ce qui se trouve par hasard sur votre machine.

Prérequis

• Python 3.8 ou supérieur. Sur les systèmes plus anciens, pip fonctionne encore, mais les versions actuelles de pip (24.x) exigent au moins Python 3.8.
• pip 24.x. Vérifiez avec pip --version. Sur Debian et Ubuntu, pip n'est pas toujours présent par défaut dans le Python système ; vous l'installez via python3-pip ou via ensurepip.
• Accès à un terminal et, pour les modifications système, sudo.
• Pour installer des paquets qui compilent contre des bibliothèques C (NumPy, lxml) : build-essential, python3-dev et les paquets -dev pertinents de la bibliothèque en question.

Sur Debian 12 et Ubuntu 24.04, la règle de la PEP 668 s'applique : vous ne pouvez plus installer aveuglément dans le Python système. Ce n'est pas un bug, c'est une protection contre vous-même. La solution se trouve plus loin.

Étapes

1. Vérifiez quel pip vous appelez

Exécutez :

which pip pip3
pip --version
pip3 --version

Sur les systèmes avec plusieurs versions de Python, pip et pip3 ne pointent pas toujours vers le même interpréteur. pip peut être lié à Python 2 sur des distributions plus anciennes, ou à un Python que vous avez installé via pyenv.

Le plus sûr est de toujours appeler pip via l'interpréteur :

python3 -m pip --version

Ainsi, vous êtes certain que le paquet arrive dans l'environnement de ce Python spécifique. Si pip et python3 -m pip affichent des versions différentes, vous avez un problème qui vous fera mal plus tard.

2. Mettez pip à jour

Un pip obsolète ne peut pas traiter les wheels modernes et échoue parfois avec des messages d'erreur qui pointent vers le mauvais problème.

python3 -m pip install --upgrade pip

Sur Debian et Ubuntu avec un Python géré par le système, vous obtenez ici error: externally-managed-environment. C'est la PEP 668. Vous avez alors trois options, et elles coûtent toutes quelque chose.

La première est d'ajouter --break-system-packages. Cela fonctionne, et votre Python système se retrouve dans un état que la prochaine mise à niveau de la distribution ne pourra plus réparer. La deuxième est d'utiliser pipx pour les applications que vous voulez exécuter comme commande. La troisième, et la bonne pour le développement, est un environnement virtuel. Nous y venons.

3. Créez un environnement virtuel par projet

Un environnement virtuel est un dossier avec son propre interpréteur Python et son propre site-packages. Les paquets que vous y installez ne touchent pas au reste du système.

cd /chemin/vers/votre/projet
python3 -m venv .venv
source .venv/bin/activate

Après source, (.venv) s'affiche devant votre invite. À partir de ce moment, python pointe vers l'interpréteur dans .venv et pip installe là.

Ce que cela coûte : vous devez réactiver l'environnement chaque fois que vous ouvrez un nouveau shell. Si vous l'oubliez, vous installez dans le Python global et vous cherchez pendant une demi-heure un paquet qui « est pourtant installé ».

Mettez .venv/ dans votre .gitignore. Traîner cent mégaoctets de binaires dans un dépôt n'est pas une bonne habitude.

4. Installez un paquet

Avec l'environnement actif :

python3 -m pip install requests

pip cherche le paquet sur PyPI, prend la version la plus récente compatible avec votre Python, télécharge la wheel et installe aussi toutes les dépendances.

Si vous voulez une version spécifique, épinglez-la :

python3 -m pip install "Django==4.2.0"

Sans épinglage, vous obtenez la version la plus récente. C'est parfait pour une expérience et une mauvaise idée pour la production. Une dépendance qui récupère la version 2.1 aujourd'hui et la 3.0 demain peut casser votre build sans que vous ayez modifié quoi que ce soit.

5. Consultez ce qui est installé

python3 -m pip list
python3 -m pip show requests

pip list affiche tous les paquets de l'environnement actif avec leurs versions. pip show donne des détails sur un paquet : version, auteur, emplacement et les dépendances dont il a besoin.

Cet emplacement est important. Si un chemin pointe vers /usr/lib/python3/ alors que vous pensiez travailler dans un venv, votre environnement n'est pas actif.

6. Figez vos dépendances dans un fichier requirements

python3 -m pip freeze > requirements.txt

Cela écrit chaque paquet installé avec sa version exacte dans requirements.txt. Un autre développeur ou un runner CI peut reconstruire le même environnement avec :

python3 -m pip install -r requirements.txt

pip freeze reprend tout ce qui se trouve dans l'environnement, y compris les paquets que vous n'avez jamais installés explicitement mais qui sont arrivés comme dépendances. C'est exactement ce que vous voulez pour la reproductibilité, et exactement ce qui vous irrite si vous voulez une liste épurée.

Si vous ne voulez que vos dépendances directes avec des contraintes de version souples, écrivez requirements.txt à la main :

Django==4.2.0
requests>=2.28.0
numpy~=1.24.0

== signifie exact, >= signifie au moins, ~= signifie compatible dans la même version mineure. Ce dernier est le plus utile pour les bibliothèques où vous voulez les corrections de bugs mais pas les breaking changes.

7. Installez directement depuis Git

Pendant le développement, vous voulez parfois un paquet qui n'est pas encore sur PyPI.

python3 -m pip install "git+https://github.com/psf/requests.git@v2.31.0"

Le @v2.31.0 épingle un tag ou un commit. Sans cet épinglage, pip récupère la branche par défaut et vous obtenez ce qui s'y trouve à ce moment-là. Pour une expérience, cela n'a pas d'importance, pour un déploiement, si.

Attention : pip clone le dépôt et construit le paquet localement. Si vous n'avez ni Git ni les outils de build sur le serveur, cela échoue avec un message d'erreur qui vous envoie au mauvais endroit.

8. Installez depuis un fichier local

python3 -m pip install ./mon_paquet-1.0.0-py3-none-any.whl

Une wheel est un binaire préconstruit. L'installation est rapide et ne nécessite pas de compilateur. Une archive source tar.gz fonctionne aussi, mais pip construit alors le paquet sur place et vous avez besoin des dépendances de build.

Pour un serveur air-gapped ou un runner CI sans accès internet, c'est la route à suivre. Vous construisez la wheel sur une machine avec réseau et vous la copiez.

Vérification

Vérifiez que tout est là où vous l'attendez :

python3 -m pip check
python3 -m pip list --format=freeze | head -20

pip check signale les dépendances manquantes ou conflictuelles. Si la commande reste silencieuse, il n'y a rien à signaler. Si vous obtenez No broken requirements found, c'est la confirmation.

Testez ensuite que le paquet est vraiment importable depuis le même interpréteur :

python3 -c "import requests; print(requests.__version__)"

Si cela affiche un numéro de version, le paquet est dans le bon environnement. Si cela affiche ModuleNotFoundError, vous avez installé dans un autre Python que celui que vous appelez maintenant.

Problèmes fréquents

error: externally-managed-environment

Debian 12 et Ubuntu 24.04 bloquent les installations dans le Python système. Utilisez un environnement virtuel (étape 3). Si vous voulez rendre une commande isolée comme black ou httpie disponible à l'échelle du système, utilisez pipx install black. Cela place chaque outil dans son propre environnement et garde votre Python système propre.

ModuleNotFoundError après une installation réussie

Vous avez installé avec un pip différent du Python que vous appelez. Vérifiez avec which python3 et python3 -m pip --version si les deux pointent vers le même environnement. Cela arrive presque toujours parce que le venv n'était pas actif pendant l'installation.

Exigences de version conflictuelles entre deux paquets

pip installe ce que vous demandez et ne signale le conflit que lorsqu'il est trop tard. pip check montre le problème, mais ne le résout pas. Pour les arbres de dépendances complexes, pip-tools ou poetry sont le meilleur choix ; ils calculent l'ensemble complet avant que quoi que ce soit ne soit installé. pip reste sous ces deux outils le moteur qui fait le travail.

pip ne gère pas les versions de Python et ne résout pas les conflits de dépendances pour vous. Il installe ce que vous demandez, dans l'environnement que vous indiquez, et c'est exactement assez pour comprendre pourquoi un build fonctionne sur votre machine et pas sur le serveur.