Poetry : la gestion de projet Python moderne — dépendances, virtualenv et packaging

Tu as déjà créé un requirements.txt à la main, un virtualenv avec python -m venv, puis réalisé que ton collègue n’arrive pas à reproduire ton environnement ? La gestion des dépendances Python a longtemps été le point faible de l’écosystème. Poetry est venu régler ce problème une bonne fois pour toutes.

Dans cet article, tu vas découvrir pourquoi Poetry est devenu un standard de la gestion de projet Python moderne : dépendances déclarées proprement, environnement virtuel géré automatiquement, versions verrouillées pour une reproductibilité parfaite, et packaging prêt pour la publication. Tu repartiras avec un workflow complet, directement applicable à tes projets.

Le problème : la gestion de projet Python à l’ancienne

Avant Poetry, le workflow typique ressemblait à ça :

• Un requirements.txt où l’on épinglait les versions à la main… ou pas
• La création manuelle d’un virtualenv (python -m venv .venv), qu’il fallait activer à chaque session
• Des conflits de versions dès que deux projets utilisaient des versions différentes de la même bibliothèque
• Un passage pénible de « ça marche chez moi » à « ça marche en CI »

Ce fonctionnement a plusieurs défauts. Le requirements.txt ne distingue pas les dépendances d’exécution des dépendances de développement (test, lint, documentation). Les versions ne sont pas systématiquement verrouillées, donc deux installations du même fichier peuvent produire deux environnements différents. Et rien ne t’aide à empaqueter ton code pour le distribuer.

Qu’est-ce que Poetry ?

Poetry est un gestionnaire de dépendances et d’empaquetage pour Python. Il centralise tout dans un fichier unique, pyproject.toml, et s’occupe de :

• Déclarer les dépendances dans un format standardisé et lisible
• Créer et gérer l’environnement virtuel automatiquement — tu n’as plus jamais à l’activer à la main
• Verrouiller les versions dans un fichier poetry.lock pour une reproductibilité exacte
• Empaqueter et publier ton projet sur PyPI en quelques commandes

L’idée centrale de Poetry : un projet Python doit être aussi simple à gérer qu’un projet Node.js avec npm ou un projet Rust avec Cargo. Et c’est exactement ce qu’il apporte : un fichier de configuration unique, une commande pour ajouter une dépendance, une commande pour tout installer.

Installer Poetry

L’installation recommandée se fait via le script officiel, qui installe Poetry dans un environnement isolé (il ne pollue pas ton Python système) :

curl -sSL https://install.python-poetry.org | python3 -

À l’issue de l’installation, ajoute le répertoire d’installation à ton PATH (le script t’indique le chemin exact selon ton système). Vérifie que tout fonctionne :

poetry --version

Tu peux aussi installer Poetry avec pipx, si tu l’utilises déjà pour tes outils en ligne de commande :

pipx install poetry

Dans les deux cas, Poetry vit dans son propre environnement : tes projets restent propres, et les mises à jour de Poetry ne cassent jamais tes dépendances.

Créer son premier projet

Pour un nouveau projet, Poetry génère la structure complète — dossier de code, tests, configuration :

poetry new mon-projet
cd mon-projet

Tu obtiens une arborescence propre et prête à l’emploi :

mon-projet/
├── mon_projet/
│   └── __init__.py
├── tests/
│   └── test_mon_projet.py
├── pyproject.toml
├── README.md
└── .gitignore

Pour un projet existant, poetry init te pose quelques questions (nom, version, licence, dépendances) et génère le pyproject.toml sans toucher à ton code :

cd mon-projet-existant
poetry init

Le fichier pyproject.toml, le cœur du projet

Tout est déclaré dans pyproject.toml, un format standardisé par la communauté Python (PEP 518). Voici à quoi ressemble un fichier typique :

[tool.poetry]
name = "mon-projet"
version = "0.1.0"
description = "Un projet Python moderne"
authors = ["Ton Nom <ton@email.com>"]

[tool.poetry.dependencies]
python = "^3.11"
requests = "^2.32.0"

[tool.poetry.group.dev.dependencies]
pytest = "^8.0.0"

[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"

Deux sections sont essentielles :

• [tool.poetry.dependencies] : les dépendances d’exécution, avec une contrainte de version lisible (^2.32.0 signifie « compatible avec 2.32.0, jusqu’à la prochaine version majeure »)
• [tool.poetry.group.dev.dependencies] : les dépendances de développement, installées seulement quand c’est nécessaire

Fini les requirements.txt séparés et les fichiers de contraintes incompréhensibles : tout tient dans un seul fichier, versionnable et reviewable en pull request.

L’environnement virtuel géré pour toi

C’est l’un des plus grands conforts de Poetry : tu n’as plus jamais besoin de créer ou d’activer un virtualenv à la main. Quand tu exécutes une commande Poetry, il crée automatiquement un environnement virtuel isolé pour ton projet s’il n’existe pas encore :

poetry install

Cette commande crée l’environnement, résout les dépendances, puis installe tout (y compris ton propre package en mode développement, ce qui est pratique pour les tests). Tu peux vérifier où vit ton environnement :

poetry env info

Pour exécuter une commande dans l’environnement du projet, deux options :

• poetry run python main.py — exécute une commande ponctuelle dans le bon environnement
• poetry shell — active l’environnement dans ton terminal pour une session de travail

Personnellement, je recommande poetry run : c’est explicite, ça marche partout (y compris dans les scripts et la CI) et ça évite les erreurs du type « j’ai oublié d’activer mon venv ».

Ajouter des dépendances

Ajouter une bibliothèque à ton projet se fait en une commande :

poetry add requests

Poetry résout le graphe de dépendances complet (les dépendances des dépendances), choisit une version compatible, met à jour pyproject.toml et poetry.lock, puis installe la bibliothèque. Une seule commande, trois fichiers à jour.

Pour une dépendance de développement (tests, lint, outils) :

poetry add --group dev pytest
poetry add --group dev ruff black mypy

Retirer une dépendance ? poetry remove requests. Voir l’arbre des dépendances ? poetry show --tree. Tout est pensé pour que la maintenance reste simple, même quand le projet grossit.

poetry.lock : la reproductibilité absolue

Pourquoi verrouiller les versions ?

Le pyproject.toml déclare des contraintes (^2.32.0), pas des versions exactes. C’est volontaire : tu veux pouvoir bénéficier des correctifs de sécurité. Mais pour garantir que tout le monde (toi, tes collègues, la CI, la production) utilise exactement les mêmes versions, Poetry génère poetry.lock : un fichier qui fige la version précise de chaque package du graphe de dépendances.

Le poetry.lock doit être commité dans Git. C’est lui qui rend les installations reproductibles :

• Sur ta machine : poetry install installe les versions exactes du lock
• Chez ton collègue : même résultat, même commande
• En CI : même chose encore — fini le « mais ça marchait sur ma machine »

Quand tu veux mettre à jour tes dépendances, tu utilises poetry update (ou poetry update requests pour une seule). Poetry recalcule le graphe et met à jour le lock en conservant les contraintes de ton pyproject.toml.

Les groupes de dépendances

Un projet sérieux a plusieurs types de dépendances : celles nécessaires en production, celles pour les tests, celles pour le développement. Poetry les organise en groupes :

[tool.poetry.group.test.dependencies]
pytest = "^8.0.0"
pytest-cov = "^5.0.0"

[tool.poetry.group.docs.dependencies]
mkdocs = "^1.6.0"

Par défaut, poetry install installe tous les groupes. Mais tu peux choisir :

# Production uniquement (ex: image Docker)
poetry install --only main

# Tests uniquement
poetry install --with test

# Tout sauf la doc
poetry install --without docs

C’est particulièrement utile pour construire des images Docker légères ou des environnements de production minimalistes : tu n’installes que ce dont l’application a réellement besoin.

Empaqueter et publier

Poetry ne s’arrête pas à la gestion locale : il gère aussi le packaging. Quand ton projet est prêt à être distribué :

poetry build

Cette commande génère une archive source (.tar.gz) et une wheel (.whl) dans le dossier dist/. La wheel est le format moderne d’installation : plus rapide, plus fiable. Pour publier sur PyPI (ou un registre privé) :

poetry publish

Poetry utilise les identifiants configurés (via poetry config ou des variables d’environnement) et publie les deux archives. Tout ton workflow de distribution tient dans deux commandes, sans outil séparé comme twine.

Migrer depuis pip + requirements.txt

Migrer un projet existant est simple. La démarche :

1. Générer un pyproject.toml avec poetry init
2. Ajouter tes dépendances avec poetry add (en t’appuyant sur ton requirements.txt actuel)
3. Supprimer requirements.txt et les scripts d’activation manuels de venv
4. Vérifier avec poetry install que tout s’installe depuis zéro

Un conseil : profite de la migration pour trier tes dépendances. Beaucoup de projets accumulent des bibliothèques inutilisées dans leurs requirements.txt. Avec Poetry, tu peux facilement identifier ce qui est réellement importé et ce qui ne sert plus.

Poetry en équipe et en CI/CD

Poetry brille particulièrement dès qu’on travaille à plusieurs. Le workflow type :

• Onboarding : un nouveau développeur clone le dépôt et lance poetry install. En quelques secondes, il a exactement le même environnement que toute l’équipe.
• Pull requests : les changements de dépendances apparaissent comme des diffs propres dans pyproject.toml et poetry.lock, faciles à relire.
• CI : dans GitHub Actions ou GitLab CI, l’installation devient poetry install --with test, puis tu lances tes tests avec poetry run pytest.

Il existe aussi une action officielle snok/install-poetry pour GitHub Actions qui configure Poetry en quelques lignes de YAML. Le résultat : une CI plus simple, plus rapide à écrire, et beaucoup moins de mystères d’environnement.

Limites et alternatives

Poetry n’est pas parfait. Ses points faibles historiques : un résolveur parfois lent sur les gros projets, et une empreinte plus lourde que des outils minimalistes. Des alternatives existent :

• uv : l’outil en Rust qui monte en puissance, extrêmement rapide, compatible avec le format pyproject.toml et même avec les fichiers Poetry
• pip-tools : l’approche minimaliste — pip + un générateur de lock (pip-compile)
• pip + venv : toujours valable pour les projets très simples

Mon avis : si tu débutes en gestion de projet Python, Poetry reste le meilleur point d’entrée. Sa documentation est excellente, son workflow est cohérent, et les concepts que tu apprends (lock, groupes, contraintes sémantiques) se transfèrent tels quels vers uv ou pip-tools si tu changes d’outil plus tard.

Conclusion

Poetry modernise en profondeur la gestion de projet Python : dépendances déclarées dans un fichier standard, environnement virtuel géré automatiquement, versions verrouillées pour la reproductibilité, packaging prêt pour PyPI. Pour un développeur, c’est un gain de temps quotidien — et pour une équipe, c’est la fin des problèmes d’environnement.

Si tu débutes ou si tu veux consolider tes bases Python (structures de données, programmation orientée objet, gestion de projet), le cours Python — Les fondamentaux sur adamcours.fr t’accompagne pas à pas avec des exercices pratiques.

Tu utilises déjà Poetry, uv ou pip-tools dans tes projets ? Dis-moi en commentaire quel outil tu préfères et pourquoi — c’est en confrontant les pratiques qu’on progresse le plus vite.