On clone un repo, on lance pip install -r requirements.txt, et rien ne fonctionne. Versions incompatibles, packages absents du dépôt, conflits silencieux entre deux bibliothèques. Le problème vient rarement de pip lui-même : il vient de la façon dont le fichier requirements.txt a été construit. Gérer ses dépendances Python proprement, c’est avant tout distinguer ce qu’on déclare de ce qu’on verrouille.
Pourquoi pip freeze produit un requirements.txt inutilisable
La commande pip freeze > requirements.txt est le réflexe le plus répandu. Elle capture la totalité des packages installés dans l’environnement, y compris les dépendances de second et troisième niveau. On se retrouve avec une liste de plusieurs dizaines de lignes pour un projet qui n’utilise que trois ou quatre bibliothèques directement.
A découvrir également : Comment configurer Roundcube OVH webmail pour un accès facile à vos emails
Le fichier devient opaque. Personne ne sait plus quels packages sont des choix du projet et lesquels ont été tirés automatiquement. Quand une mise à jour de sécurité concerne une sous-dépendance, on hésite à toucher quoi que ce soit par peur de casser la chaîne.
La pratique moderne consiste à séparer dépendances directes et dépendances verrouillées. On déclare dans un fichier source (souvent nommé requirements.in) uniquement les packages qu’on importe dans le code. Un outil génère ensuite le fichier verrouillé complet, avec les versions exactes et les sous-dépendances résolues. Cette approche est portée par pip-tools et, plus récemment, par uv.
Lire également : Ccleaner pro : avis et témoignages étonnants de ses utilisateurs
Structurer un projet Python avec requirements.in et pip-tools
Partons d’un cas concret : un projet Django avec quelques bibliothèques complémentaires. On crée un fichier requirements.in à la racine :
django>=4.2,<5.0djangorestframeworkcelery[redis]
Trois lignes, lisibles par n’importe qui dans l’équipe. On sait immédiatement ce que le projet utilise. Pas de bruit.
Générer le fichier verrouillé avec pip-compile
Après avoir installé pip-tools dans l’environnement virtuel (pip install pip-tools), on lance pip-compile requirements.in. La commande produit un requirements.txt complet, avec chaque version épinglée et des commentaires indiquant quelle dépendance a tiré quel package.
Ce fichier verrouillé est celui qu’on utilise pour l’installation : pip install -r requirements.txt. On le versionne dans Git. Quand on veut mettre à jour, on modifie requirements.in, on relance pip-compile --upgrade, et on vérifie le diff.
Ajouter des hashes pour sécuriser l’installation
La sécurité de la chaîne d’approvisionnement est un angle souvent ignoré dans les tutoriels pour débutants. L’option pip-compile --generate-hashes ajoute une empreinte cryptographique à chaque package dans le fichier verrouillé. À l’installation, pip vérifie que le package téléchargé correspond au hash déclaré. Si un paquet a été compromis sur PyPI entre-temps, l’installation échoue au lieu de continuer silencieusement.
On active la vérification côté pip avec pip install --require-hashes -r requirements.txt. C’est une précaution particulièrement utile en contexte professionnel ou pour des déploiements automatisés.
Environnement virtuel Python : le socle avant toute installation pip
Installer des packages sans environnement virtuel revient à mélanger les dépendances de tous ses projets dans un seul espace. Deux projets utilisant des versions différentes de Django entrent immédiatement en conflit.
La création d’un environnement est rapide :
python -m venv .venvcrée un environnement isolé dans le dossier.venvdu projetsource .venv/bin/activate(Linux/macOS) ou.venv\Scripts\activate(Windows) l’active dans le terminal courantpip install -r requirements.txtn’affecte que cet environnement, pas le système
On ajoute .venv/ au .gitignore pour ne pas versionner les binaires. Seuls les fichiers requirements sont versionnés, jamais l’environnement lui-même. Un nouveau contributeur recrée le sien en deux commandes.
Dépôt privé et options avancées dans requirements.txt
En entreprise, certains packages ne sont pas sur PyPI. Ils sont hébergés sur un dépôt interne (Artifactory, Cloudsmith, un simple serveur avec un index compatible). Le fichier requirements.txt peut porter cette information directement grâce à l’option --index-url ou --extra-index-url en première ligne.
Cette possibilité est rarement couverte dans les guides grand public, mais elle évite de devoir documenter une variable d’environnement séparée. Le fichier devient autoporteur : toute l’information d’installation tient dans un seul fichier.
pip, uv ou Poetry : quel outil pour installer ses packages Python
pip reste l’outil de référence, installé avec Python par défaut. Pour un projet simple ou un script ponctuel, il suffit largement. Avec pip-tools par-dessus, on couvre la majorité des besoins professionnels.
uv, développé par Astral (l’équipe derrière Ruff), se positionne comme un remplaçant plus rapide pour l’installation et le verrouillage des dépendances. Il reprend la logique de requirements.in et génère un fichier verrouillé, avec des temps de résolution nettement réduits. Les retours varient sur la maturité de l’outil en production, mais l’adoption progresse vite.
Poetry adopte une approche différente : un fichier pyproject.toml centralise la configuration du projet, les dépendances et les métadonnées de publication. C’est un choix cohérent pour les bibliothèques destinées à être distribuées sur PyPI, mais l’écosystème reste distinct de pip.
- pip + pip-tools : compatible partout, fichier requirements.txt standard, adapté aux déploiements classiques
- uv : résolution rapide, syntaxe compatible pip, pertinent pour les projets en conteneur ou les CI lourdes
- Poetry : configuration centralisée dans pyproject.toml, orienté distribution de packages
Le choix dépend du contexte. Pour un projet Django déployé sur un serveur, pip-tools couvre le besoin sans ajouter de dépendance supplémentaire. Pour un monorepo avec des dizaines de services, la vitesse de résolution d’uv fait la différence.
Quel que soit l’outil, le principe reste le même : déclarer explicitement ses dépendances directes, verrouiller les versions pour la reproductibilité, isoler chaque projet dans son environnement. Un requirements.txt généré par pip freeze sans tri préalable finit toujours par poser problème. Mieux vaut investir dix minutes dans une structure propre que perdre une après-midi à déboguer un conflit de versions.
