Python Poetry : guide moderne de gestion des dépendances et de packaging

Name

Soren Atelier

Updated on 12/02/2026

Gérer des dépendances Python ne devrait pas être douloureux. Pourtant, chaque développeur Python a déjà vécu la scène suivante : vous clonez un projet, exécutez pip install -r requirements.txt, et regardez les conflits de dépendances se propager dans le terminal. Le package A a besoin de la version 1.x d’une bibliothèque, le package B a besoin de la version 2.x, et pip installe celle qu’il résout en dernier — en cassant silencieusement l’un des deux. S’ensuivent des heures de débogage, simplement parce que pip ne dispose pas d’un véritable mécanisme de résolution de dépendances et de lock file.

Le problème s’amplifie en équipe. Un développeur épingle des versions exactes, un autre utilise des plages larges, et un troisième oublie de mettre à jour requirements.txt après avoir installé un nouveau package. Les déploiements échouent. Les tests passent en local mais cassent en CI. La cause racine est toujours la même : l’outillage par défaut de Python traite la gestion des dépendances comme un sujet secondaire.

Poetry résout cela en fournissant un outil unique qui gère la résolution des dépendances, la gestion des environnements virtuels, et la publication de packages. Il s’appuie sur un fichier standardisé pyproject.toml, génère des lock files déterministes, et résout les conflits de dépendances avant l’installation — pas après. Ce guide couvre tout, de l’installation à la publication, avec des exemples pratiques pour chaque workflow.

Qu’est-ce que Python Poetry ?

Poetry est un outil open-source de gestion des dépendances et de packaging pour Python. Créé par Sebastien Eustace en 2018, il répond à l’état fragmenté du packaging Python en regroupant plusieurs fonctions dans un outil cohérent :

• Résolution des dépendances : Poetry analyse toutes les dépendances et leurs sous-dépendances afin de trouver des versions compatibles avant d’installer quoi que ce soit.
• Lock files : un fichier poetry.lock enregistre les versions exactes de chaque package installé, garantissant des builds reproductibles sur toutes les machines.
• Gestion des environnements virtuels : Poetry crée et gère automatiquement des environnements virtuels isolés par projet.
• Build et publication de packages : Poetry construit des distributions source et des wheels, et publie directement sur PyPI ou sur des dépôts privés.
• Génération de projet (scaffolding) : Poetry génère des structures de projet avec une configuration pyproject.toml correcte.

Poetry utilise pyproject.toml comme fichier de configuration, conformément aux standards PEP 518 et PEP 621. Cela remplace la combinaison de setup.py, setup.cfg, requirements.txt, et MANIFEST.in requise par les projets Python traditionnels.

Installer Poetry

Poetry fournit son propre installateur, qui l’isole de vos dépendances de projet, évitant les conflits de version entre Poetry lui-même et les packages de votre projet.

Installation recommandée (installateur officiel)

Linux, macOS, et Windows (WSL) :

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

Windows (PowerShell) :

(Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | py -

Après l’installation, ajoutez Poetry à votre PATH. L’installateur affiche le chemin exact — généralement $HOME/.local/bin sur Linux/macOS ou %APPDATA%\Python\Scripts sur Windows.

Vérifiez l’installation :

poetry --version

Installation avec pipx

Si vous préférez utiliser pipx (qui isole également les outils CLI) :

pipx install poetry

Mettre à jour Poetry

poetry self update

Pour mettre à jour vers une version spécifique :

poetry self update 1.8.0

Activer l’autocomplétion (Tab Completion)

Poetry prend en charge l’autocomplétion pour Bash, Zsh et Fish :

# Bash
poetry completions bash >> ~/.bash_completion
 
# Zsh
poetry completions zsh > ~/.zfunc/_poetry
 
# Fish
poetry completions fish > ~/.config/fish/completions/poetry.fish

Créer un nouveau projet

Poetry propose deux façons de démarrer un projet : en créer un nouveau à partir de zéro, ou initialiser Poetry dans un projet existant.

Nouveau projet à partir de zéro

poetry new my-project

Cela génère la structure suivante :

my-project/
├── pyproject.toml
├── README.md
├── my_project/
│   └── __init__.py
└── tests/
    └── __init__.py

Pour une organisation « flat » des sources (package à la racine) :

poetry new --src my-project

Cela place le package dans un répertoire src/ :

my-project/
├── pyproject.toml
├── README.md
├── src/
│   └── my_project/
│       └── __init__.py
└── tests/
    └── __init__.py

Initialiser dans un projet existant

Placez-vous dans le répertoire de votre projet existant et exécutez :

cd existing-project
poetry init

Poetry vous guide via une configuration interactive, en demandant le nom du package, la version, la description, l’auteur, la compatibilité de version Python, et les dépendances. Vous pouvez appuyer sur Entrée pour accepter les valeurs par défaut ou ignorer les champs optionnels.

Pour une configuration non interactive :

poetry init --name my-package --description "A useful package" --author "Your Name <you@example.com>" --python "^3.9" --no-interaction

Comprendre pyproject.toml

Le fichier pyproject.toml est l’unique source de vérité pour la configuration de votre projet. Voici un exemple complet :

[tool.poetry]
name = "my-project"
version = "1.0.0"
description = "A data processing library"
authors = ["Your Name <you@example.com>"]
license = "MIT"
readme = "README.md"
homepage = "https://github.com/yourname/my-project"
repository = "https://github.com/yourname/my-project"
keywords = ["data", "processing", "analytics"]
classifiers = [
    "Development Status :: 4 - Beta",
    "Intended Audience :: Developers",
    "Topic :: Software Development :: Libraries",
]
 
[tool.poetry.dependencies]
python = "^3.9"
pandas = "^2.0"
requests = "^2.31"
pydantic = ">=2.0,<3.0"
 
[tool.poetry.group.dev.dependencies]
pytest = "^8.0"
black = "^24.0"
mypy = "^1.0"
ruff = "^0.3"
 
[tool.poetry.group.docs.dependencies]
sphinx = "^7.0"
sphinx-rtd-theme = "^2.0"
 
[tool.poetry.scripts]
my-cli = "my_project.cli:main"
 
[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"

Syntaxe des contraintes de version

Poetry utilise une syntaxe claire pour les contraintes de version :

La contrainte caret (^) est la plus courante et recommandée. Elle autorise des mises à jour qui ne changent pas le chiffre non nul le plus à gauche, en suivant les principes du semantic versioning.

Groupes de dépendances

Poetry organise les dépendances en groupes, remplaçant le besoin de fichiers requirements séparés :

• Dépendances principales ([tool.poetry.dependencies]) : nécessaires au fonctionnement du package. Elles sont incluses quand quelqu’un installe votre package.
• Dépendances de développement ([tool.poetry.group.dev.dependencies]) : outils pour le développement, les tests et le linting. Non incluses dans les packages publiés.
• Groupes personnalisés ([tool.poetry.group.docs.dependencies]) : toute autre classification utile, par exemple les outils de documentation.

Ajouter et supprimer des dépendances

Ajouter des packages

Ajouter un package aux dépendances principales :

poetry add pandas

Ajouter avec une contrainte de version :

poetry add "pandas>=2.0,<3.0"

Ajouter au groupe de développement :

poetry add --group dev pytest black ruff

Ajouter à un groupe personnalisé :

poetry add --group docs sphinx

Ajouter un package depuis un dépôt Git :

poetry add git+https://github.com/user/repo.git

Ajouter un package depuis une branche ou un tag spécifique :

poetry add git+https://github.com/user/repo.git#branch-name
poetry add git+https://github.com/user/repo.git#v1.0.0

Ajouter une dépendance via un chemin local :

poetry add ../my-local-package

Ajouter des extras pour un package :

poetry add "uvicorn[standard]"

Supprimer des packages

Supprimer un package :

poetry remove pandas

Supprimer depuis un groupe spécifique :

poetry remove --group dev black

Lister les packages installés

Afficher tous les packages installés :

poetry show

Afficher les détails d’un package spécifique :

poetry show pandas

Afficher l’arbre de dépendances :

poetry show --tree

Afficher les packages obsolètes :

poetry show --outdated

Le lock file : poetry.lock

Le fichier poetry.lock est l’une des fonctionnalités les plus importantes de Poetry. Quand vous exécutez poetry install ou poetry add, Poetry résout toutes les dépendances et écrit les versions exactes (y compris toutes les dépendances transitives) dans poetry.lock.

Pourquoi les lock files sont importantes

Sans lock file, exécuter pip install -r requirements.txt avec des contraintes de version larges peut produire des installations différentes selon les machines ou selon le moment. Une lock file élimine cette part d’aléatoire.

Considérez ce scénario :

[tool.poetry.dependencies]
requests = "^2.28"

Cela autorise n’importe quelle version de 2.28.0 à 2.99.x. Sans lock file, votre serveur CI peut installer 2.31.0 tandis que votre machine locale utilise 2.28.2. La lock file épingle la version exacte dans tous les environnements.

Workflow autour du lock file

Committez poetry.lock dans le version control. Cela garantit que chaque développeur et chaque déploiement utilisent des versions de packages identiques.

git add poetry.lock pyproject.toml
git commit -m "Add project dependencies"

Installer depuis le lock file (pour des installations reproductibles) :

poetry install

Cela installe exactement les versions spécifiées dans poetry.lock, en ignorant toute version compatible plus récente.

Mettre à jour le lock file quand vous souhaitez des versions plus récentes :

# Mettre à jour tous les packages
poetry update
 
# Mettre à jour un package spécifique
poetry update pandas
 
# Mettre à jour le lock file sans installer
poetry lock

Vérifier l’intégrité du lock file :

poetry lock --check

Cela confirme que la lock file est cohérente avec pyproject.toml sans modifier quoi que ce soit.

Gestion des environnements virtuels

Poetry crée et gère automatiquement des environnements virtuels pour vos projets.

Comportement par défaut

Quand vous exécutez poetry install ou poetry add, Poetry crée un environnement virtuel s’il n’existe pas. Par défaut, les environnements sont stockés dans un répertoire de cache centralisé :

• Linux : ~/.cache/pypoetry/virtualenvs/
• macOS : ~/Library/Caches/pypoetry/virtualenvs/
• Windows : C:\Users\<user>\AppData\Local\pypoetry\Cache\virtualenvs\

Environnements virtuels dans le projet

Beaucoup de développeurs préfèrent avoir l’environnement virtuel dans le répertoire du projet (similaire à Node.js node_modules). Configurez cela globalement :

poetry config virtualenvs.in-project true

Cela crée un répertoire .venv à la racine du projet, facile à trouver et compatible avec l’auto-détection des IDE.

Exécuter des commandes dans l’environnement virtuel

Exécuter une seule commande :

poetry run python my_script.py
poetry run pytest
poetry run black .

Activer un shell dans l’environnement :

poetry shell

Cela ouvre un nouveau shell avec l’environnement virtuel activé. Sortez avec exit ou Ctrl+D.

Informations sur l’environnement

Afficher les détails de l’environnement :

poetry env info

Lister tous les environnements associés au projet :

poetry env list

Utiliser une version spécifique de Python :

poetry env use python3.11

Supprimer un environnement :

poetry env remove python3.11

Installer des dépendances

Installation standard

Installer toutes les dépendances (principales et de développement) :

poetry install

Installation pour la production

Installer sans les dépendances de développement :

poetry install --without dev

Installer sans certains groupes :

poetry install --without dev,docs

Installer uniquement certains groupes

poetry install --only main
poetry install --only dev

Synchroniser l’environnement

Supprimer les packages qui ne sont pas dans la lock file (installation « propre ») :

poetry install --sync

Cela supprime tout package installé manuellement ou qui n’est plus dans la lock file, afin que l’environnement corresponde exactement à la configuration du projet.

Construire et publier des packages

Poetry simplifie l’ensemble du workflow de publication.

Builder votre package

poetry build

Cela crée à la fois une distribution source (.tar.gz) et une wheel (.whl) dans le répertoire dist/ :

dist/
├── my_project-1.0.0.tar.gz
└── my_project-1.0.0-py3-none-any.whl

Publier sur PyPI

Commencez par configurer vos identifiants PyPI :

poetry config pypi-token.pypi your-api-token

Puis publiez :

poetry publish --build

Le flag --build build et publie en une seule étape.

Publier sur un dépôt privé

Ajouter un dépôt privé :

poetry config repositories.private https://private.pypi.example.com/simple/
poetry config http-basic.private username password

Publier dessus :

poetry publish --repository private

Gestion de version

Incrémenter les versions via semantic versioning :

poetry version patch    # 1.0.0 -> 1.0.1
poetry version minor    # 1.0.0 -> 1.1.0
poetry version major    # 1.0.0 -> 2.0.0
poetry version prepatch # 1.0.0 -> 1.0.1a0

Afficher la version actuelle :

poetry version

Migrer depuis requirements.txt

Si vous avez un projet existant utilisant requirements.txt, migrer vers Poetry est simple.

Étape 1 : initialiser Poetry

cd your-project
poetry init --no-interaction

Étape 2 : ajouter les dépendances depuis requirements.txt

Pour un fichier requirements simple :

cat requirements.txt | xargs poetry add

Pour des fichiers avec contraintes de version, ajoutez les packages manuellement ou utilisez un script de migration :

import subprocess
 
with open("requirements.txt") as f:
    packages = []
    for line in f:
        line = line.strip()
        if line and not line.startswith("#") and not line.startswith("-"):
            packages.append(line)
 
if packages:
    subprocess.run(["poetry", "add"] + packages)

Étape 3 : ajouter les dépendances de développement

Si vous avez un requirements-dev.txt :

cat requirements-dev.txt | xargs poetry add --group dev

Étape 4 : vérifier et verrouiller

poetry install
poetry lock --check

Étape 5 : nettoyage

Après avoir vérifié que tout fonctionne, vous pouvez supprimer les anciens fichiers :

rm requirements.txt requirements-dev.txt setup.py setup.cfg

Exporter à nouveau vers requirements.txt

Si vous avez besoin d’un requirements.txt pour la compatibilité (builds Docker, anciens systèmes CI) :

poetry export -f requirements.txt --output requirements.txt

Inclure les dépendances de développement :

poetry export -f requirements.txt --with dev --output requirements-dev.txt

Poetry vs pip vs pipenv vs uv : comparaison

Choisir le bon outil de gestion des dépendances dépend des besoins de votre projet. Voici une comparaison détaillée :

Quand choisir chaque outil

Choisissez Poetry quand vous avez besoin d’une solution complète de packaging — gestion des dépendances, build et publication sur PyPI dans un outil unique, avec un écosystème mature et une documentation riche.

Choisissez pip pour des scripts simples, du prototypage rapide, ou lorsque vous devez respecter des contraintes imposant les outils standards. Pip reste la base sur laquelle les autres outils se construisent.

Choisissez pipenv pour les applications web où vous avez besoin d’environnements reproductibles mais sans publier de packages sur PyPI. Son format Pipfile sépare clairement les dépendances de développement et de production.

Choisissez uv quand la vitesse d’installation est prioritaire, ou si vous voulez un outil unique qui gère aussi les versions de Python. uv est écrit en Rust et résout les dépendances bien plus rapidement que les outils basés sur Python. Il est compatible pip et peut servir de remplacement « drop-in ».

Configuration Poetry et conseils

Options de configuration utiles

# Stocker les environnements virtuels dans le répertoire du projet
poetry config virtualenvs.in-project true
 
# Utiliser une version Python spécifique pour les nouveaux environnements
poetry config virtualenvs.prefer-active-python true
 
# Désactiver la création automatique d’environnement virtuel
poetry config virtualenvs.create false
 
# Voir toute la configuration
poetry config --list

Poetry avec Docker

Un Dockerfile de production utilisant Poetry :

FROM python:3.12-slim
 
ENV POETRY_VERSION=1.8.0 \
    POETRY_HOME="/opt/poetry" \
    POETRY_VIRTUALENVS_CREATE=false \
    POETRY_NO_INTERACTION=1
 
RUN pip install poetry==$POETRY_VERSION
 
WORKDIR /app
 
COPY pyproject.toml poetry.lock ./
RUN poetry install --without dev --no-root
 
COPY . .
RUN poetry install --without dev
 
CMD ["python", "-m", "my_project"]

Points clés :

• POETRY_VIRTUALENVS_CREATE=false évite de créer un environnement virtuel dans le container (le container fournit déjà l’isolation).
• Installez les dépendances avant de copier le code source pour profiter du caching des couches Docker.
• Exécutez poetry install deux fois : d’abord sans le projet (uniquement les dépendances), puis avec le projet.

Poetry avec CI/CD

Exemple GitHub Actions :

name: CI
 
on: [push, pull_request]
 
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - name: Install Poetry
        run: pip install poetry
      - name: Install dependencies
        run: poetry install
      - name: Run tests
        run: poetry run pytest
      - name: Run linting
        run: poetry run ruff check .

Poetry dans les workflows Jupyter

Les data scientists travaillent souvent dans des notebooks Jupyter, où la gestion des dépendances est particulièrement critique. Poetry s’intègre bien à Jupyter en garantissant que les notebooks utilisent le bon environnement.

Installer Jupyter dans votre projet Poetry :

poetry add --group dev jupyter ipykernel

Enregistrer l’environnement Poetry comme kernel Jupyter :

poetry run python -m ipykernel install --user --name=my-project

Lancer Jupyter depuis l’environnement Poetry :

poetry run jupyter notebook

Pour une expérience Jupyter plus fluide, avec gestion automatique des dépendances et assistance alimentée par l’IA, RunCell (opens in a new tab) propose un environnement intégré permettant de se concentrer sur l’analyse plutôt que sur la configuration. RunCell gère automatiquement l’installation des packages et la gestion des kernels, ce qui complète le contrôle des dépendances au niveau projet apporté par Poetry.

Référence des commandes Poetry les plus courantes

Dépannage des problèmes courants

Échecs de résolution de dépendances

Problème : Poetry ne trouve pas un ensemble de versions compatible.

SolverProblemError: ...unable to find compatible versions...

Solution : élargissez les contraintes de version ou vérifiez les exigences conflictuelles :

# Afficher les conflits existants
poetry show --tree
 
# Essayer avec une contrainte plus large
poetry add "problematic-package>=1.0"

Résolution lente

Problème : poetry lock prend beaucoup de temps.

Solution : Poetry met en cache les métadonnées des packages, mais la première résolution d’un projet avec beaucoup de dépendances peut être lente. Si la résolution dépasse plusieurs minutes :

# Vider le cache et réessayer
poetry cache clear --all pypi
 
# Utiliser la sortie verbose pour comprendre ce qui se passe
poetry lock -vvv

Environnement virtuel non détecté par l’IDE

Problème : VS Code ou PyCharm ne trouve pas l’environnement Poetry.

Solution : configurez les environnements virtuels dans le projet :

poetry config virtualenvs.in-project true
poetry install  # Recrée .venv à la racine du projet

Puis sélectionnez .venv/bin/python comme interpréteur dans votre IDE.

Erreurs de hash mismatch

Problème : poetry install signale des hash mismatches.

Solution : régénérez la lock file :

poetry lock --no-update

Cela régénère les hashes sans changer les versions des dépendances.

FAQ

À quoi sert Python Poetry ?

Python Poetry est un outil de gestion des dépendances et de packaging qui prend en charge l’installation des packages, la résolution des conflits de version, la gestion des environnements virtuels, et la publication sur PyPI. Il remplace la combinaison de pip, venv, setuptools et twine par un outil unifié centré sur le fichier de configuration pyproject.toml.

Poetry est-il meilleur que pip ?

Poetry et pip ne répondent pas exactement aux mêmes besoins. Poetry fournit la résolution des dépendances, des lock files, la gestion des environnements virtuels et la publication de packages dans un seul outil. Pip est plus simple et fonctionne bien pour des installations directes. Pour les projets nécessitant des builds reproductibles, du travail en équipe, ou la publication de packages, Poetry offre des avantages significatifs. Pour des scripts rapides ou des projets simples, pip reste suffisant.

Comment passer de pip à Poetry ?

Initialisez Poetry dans votre projet avec poetry init, puis ajoutez vos dépendances depuis requirements.txt via cat requirements.txt | xargs poetry add. Poetry crée un fichier pyproject.toml et un fichier poetry.lock. Après avoir vérifié que tout fonctionne avec poetry install, vous pouvez supprimer l’ancien fichier requirements.txt. Utilisez poetry export si vous avez encore besoin de requirements.txt pour la compatibilité.

Poetry remplace-t-il virtualenv ?

Oui. Poetry crée et gère automatiquement des environnements virtuels pour chaque projet. Vous n’avez pas besoin de créer ou d’activer les environnements manuellement. Poetry stocke les environnements dans un cache centralisé par défaut, ou dans le répertoire du projet si vous configurez poetry config virtualenvs.in-project true. Vous pouvez toujours utiliser poetry shell pour activer l’environnement de manière interactive.

Poetry peut-il gérer plusieurs versions de Python ?

Poetry n’installe pas lui-même les versions de Python, mais il fonctionne avec les versions disponibles sur votre système. Utilisez pyenv ou uv pour installer plusieurs versions de Python, puis indiquez à Poetry laquelle utiliser via poetry env use python3.11. Poetry crée des environnements virtuels séparés pour différentes versions de Python au sein d’un même projet.

Quelle est la différence entre poetry.lock et requirements.txt ?

Un fichier poetry.lock enregistre chaque package installé et sa version exacte, y compris toutes les dépendances transitives, ainsi que des hashes de contenu pour la vérification. Un requirements.txt généré via pip freeze liste aussi des versions exactes, mais sans vérification de hash ni suivi des relations de dépendances. La lock file garantit des installations déterministes dans tous les environnements, tandis que requirements.txt peut produire des résultats différents quand des dépendances transitives évoluent.

Conclusion

Python Poetry transforme la gestion des dépendances — d’une source de friction — en un workflow fluide. En combinant la résolution des dépendances, la gestion des environnements virtuels et la publication de packages dans un outil unique, il élimine la chaîne d’outils fragmentée qui frustre depuis longtemps les développeurs Python. Le fichier pyproject.toml fournit une unique source de vérité, la lock file garantit des installations reproductibles, et le résolveur de dépendances détecte les conflits avant qu’ils ne provoquent des échecs à l’exécution.

Que vous construisiez une bibliothèque pour PyPI, que vous gériez une application complexe avec des dizaines de dépendances, ou que vous collaboriez avec une équipe ayant besoin d’environnements cohérents, Poetry apporte une structure et une fiabilité que pip seul ne peut pas offrir. Sa courbe d’apprentissage est modeste — la plupart des développeurs sont productifs en moins d’une heure — et le temps économisé sur le débogage de dépendances est rentabilisé dès la première semaine.

Commencez en lançant poetry new pour votre prochain projet, ou poetry init dans un projet existant. Ajoutez vos dépendances, committez la lock file, et découvrez une gestion des dépendances qui fonctionne comme elle le devrait. Pour des workflows data science dans Jupyter, associez le contrôle des dépendances au niveau projet offert par Poetry avec RunCell (opens in a new tab) afin d’obtenir un environnement qui gère à la fois le package management et l’analyse interactive, de manière fluide.