Poetry : gérer les dépendances et packager en Python

Poetry est un outil qui gère les dépendances, l'environnement virtuel et le packaging d'un projet Python à partir d'un seul fichier pyproject.toml. Il remplace le trio pip + requirements.txt + virtualenv par une commande unique, verrouille les versions exactes dans un poetry.lock reproductible, et publie vos paquets sur PyPI.

Ce guide, pour développeurs débutants et intermédiaires, couvre l'installation, la gestion des dépendances, les environnements virtuels et la publication. Il est à jour pour Poetry 2.x, qui apporte le support du format standard [project] (PEP 621) et remplace poetry shell par poetry env activate.

Ce que vous allez apprendre

• Installer Poetry proprement et l'ajouter au PATH
• Initialiser un projet et comprendre pyproject.toml
• Ajouter, mettre à jour et retirer des dépendances, par groupe
• Gérer l'environnement virtuel (poetry env activate, poetry run)
• Verrouiller les versions avec poetry.lock et sécuriser la supply chain
• Construire et publier un paquet sur PyPI

Un peu d'Histoire

Poetry est né d’un constat simple : gérer les projets Python devenait un véritable parcours du combattant. Entre les environnements virtuels à créer à la main, les fichiers requirements.txt souvent bancals et les outils existants comme pip ou pipenv, il manquait un outil tout-en-un, simple et fiable. C'est là qu'intervient Sébastien Eustace, un développeur qui, en 2018, décide de prendre les choses en main et de créer Poetry.

Son idée ? Proposer une alternative qui regroupe le meilleur des deux mondes : la gestion des dépendances et des environnements virtuels, tout en intégrant des pratiques modernes comme le fichier pyproject.toml introduit par PEP 518. En quelques années, Poetry a séduit la communauté Python grâce à son approche élégante et efficace.

Aujourd’hui, Poetry est maintenu par une communauté active et se positionne comme une référence incontournable. Ce succès témoigne d’un besoin clair dans l’écosystème Python : des outils simples qui permettent de se concentrer sur l’essentiel, c’est-à-dire coder. Et franchement, qui ne préfère pas une bonne dose de simplicité ?

Fonctionnalités de Poetry

Voici les principales fonctionnalités qui rendent Poetry indispensable :

• Gestion des dépendances intelligente : Ajout, suppression et mise à jour des bibliothèques avec gestion automatique des conflits de versions.
• Fichier pyproject.toml : Centralisation des dépendances, des métadonnées du projet et des configurations de build.
• Environnements virtuels intégrés : Création et gestion automatique d’environnements isolés pour chaque projet.
• Packaging pour PyPI : Génération et publication de packages prêts à être distribués sur la plateforme PyPI.
• Versionnement sémantique : Gestion simplifiée des versions du projet, avec incréments automatiques selon les règles de versionnement sémantique.
• Support des environnements multiples : Organisation des dépendances par groupe, selon les besoins (développement, production, tests, etc.).
• Scripts intégrés : Automatisation des tâches avec des commandes configurables directement dans le fichier de projet.

Avec ces fonctionnalités, Poetry s'impose comme un outil complet et polyvalent pour tout projet Python.

Installation

L'installation de Poetry est rapide et accessible, quel que soit votre système. Voici un guide détaillé pour vous accompagner pas à pas, avec une mention spéciale pour les fans de asdf-vm.

Prérequis

Avant d’installer Poetry, assurez-vous d’avoir :

• Python 3.7 ou supérieur : Poetry ne fonctionne pas avec des versions antérieures. Vous pouvez vérifier votre version de Python avec :

  python3 --version

• Un gestionnaire de téléchargement : Soit curl (pour les commandes shell), soit pip (préinstallé avec Python).

• Facultatif : Si vous utilisez déjà asdf-vm pour gérer vos versions d’outils et langages, Poetry dispose d’un plugin officiel. On y revient plus tard dans ce chapitre.

Méthode standard

La manière la plus simple et universelle d’installer Poetry est d'utiliser le script officiel. Exécutez la commande suivante :

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

Ce script télécharge et configure Poetry pour qu’il soit utilisable sur votre machine. Par défaut, il installe Poetry dans ~/.local/bin sur Linux/MacOS ou %APPDATA%\Python\Scripts sur Windows.

Pipe vers le shell : à utiliser en connaissance de cause

curl … | python3 - exécute un script distant sans que vous l'ayez lu. Deux options plus prudentes : passer par un gestionnaire d'outils (asdf, mise, pipx install poetry), ou inspecter le script avant de l'exécuter :

curl -sSL https://install.python-poetry.org -o install-poetry.py
less install-poetry.py   # relire
python3 install-poetry.py

Vérification de l’installation

Pour vérifier que l’installation s’est bien déroulée, lancez :

poetry --version

Si tout fonctionne, vous verrez un message indiquant la version installée de Poetry.

Si la commande poetry n’est pas reconnue, il se peut que son emplacement ne soit pas dans le PATH de votre système. Voici comment l’ajouter :

• Linux/MacOS : Ajoutez cette ligne dans votre fichier ~/.bashrc ou ~/.zshrc :

  export PATH="$HOME/.local/bin:$PATH"

  Rechargez ensuite votre shell avec :

  source ~/.bashrc

• Windows : Ajoutez %APPDATA%\Python\Scripts au PATH via les paramètres système.

Méthode alternative : installation avec asdf

Si vous utilisez asdf-vm, un gestionnaire polyvalent pour les versions de langages et d’outils, vous pouvez installer Poetry en tant que plugin. Voici comment :

1. Assurez-vous que asdf-vm est installé sur votre machine.

2. Ajoutez le plugin Poetry à asdf avec la commande :

   asdf plugin add poetry

3. Installez la version souhaitée de Poetry :

   asdf install poetry latest

4. Définissez cette version comme globale (ou locale pour un projet spécifique) :

   asdf global poetry latest

5. Vérifiez l'installation :

   poetry --version

Utiliser asdf est une excellente solution si vous travaillez sur plusieurs projets nécessitant différentes versions de Poetry. Cela garantit un environnement propre et cohérent.

Utilisation de base

Maintenant que Poetry est installé, il est temps de passer à l’action et de découvrir les bases de son utilisation. Que vous souhaitiez initialiser un projet, ajouter des dépendances, ou gérer vos environnements virtuels, Poetry rend tout cela simple et fluide.

Initialiser un projet

La première étape pour utiliser Poetry est de créer un projet. Poetry configure tout pour vous, générant un fichier pyproject.toml pour centraliser la configuration.

poetry init

Vous serez guidé à travers une série de questions interactives :

• Nom du projet
• Version initiale
• Description
• Auteur(s)
• Dépendances et compatibilité Python

Si vous préférez sauter les questions, utilisez l’option --no-interaction pour une initialisation rapide avec des valeurs par défaut.

Ajouter des dépendances

Besoin d’ajouter une bibliothèque à votre projet ? Poetry rend cela incroyablement simple. Par exemple, pour installer Flask :

poetry add flask
Creating virtualenv test-poetry-wuC4HPt9-py3.12 in /home/bob/.cache/pypoetry/virtualenvs
Using version ^3.1.0 for flask

Updating dependencies
Resolving dependencies... (0.4s)

Package operations: 7 installs, 0 updates, 0 removals

  - Installing markupsafe (3.0.2)
  - Installing blinker (1.9.0)
  - Installing click (8.1.7)
  - Installing itsdangerous (2.2.0)
  - Installing jinja2 (3.1.4)
  - Installing werkzeug (3.1.3)
  - Installing flask (3.1.0)

Writing lock file

Quelques points à noter :

• Poetry télécharge automatiquement la version compatible la plus récente.
• Les dépendances sont ajoutées au fichier pyproject.toml.
• Vous pouvez spécifier une version particulière ou un intervalle, comme flask@^2.0.

Pour des dépendances spécifiques à un environnement (par exemple, des outils de développement) :

poetry add pytest --group dev

Using version ^8.3.3 for pytest

Updating dependencies
Resolving dependencies... (0.2s)

Package operations: 4 installs, 0 updates, 0 removals

  - Installing iniconfig (2.0.0)
  - Installing packaging (24.2)
  - Installing pluggy (1.5.0)
  - Installing pytest (8.3.3)

Writing lock file

Poetry crée un fichier poetry.lock, qui verrouille les versions exactes des bibliothèques installées pour garantir la reproductibilité.

Gestion des environnements virtuels

Un des avantages majeurs de Poetry est sa gestion intégrée des environnements virtuels.

• Activer l’environnement virtuel :

  poetry env activate

  Cette commande affiche (ou lance) la commande d'activation de l'environnement du projet. Elle remplace poetry shell, retiré du cœur de Poetry en 2.x (désormais fourni par le plugin poetry-plugin-shell si vous tenez à l'ancien comportement).

• Lancer une commande dans l’environnement sans l’activer :

  poetry run python script.py

• Vérifier où est situé l’environnement virtuel :

  poetry env info
  Virtualenv
  Python:         3.12.3
  Implementation: CPython
  Path:           /home/bob/.cache/pypoetry/virtualenvs/test-poetry-wuC4HPt9-py3.12
  Executable:     /home/bob/.cache/pypoetry/virtualenvs/test-poetry-wuC4HPt9-py3.12/bin/python
  Valid:          True
  
  Base
  Platform:   linux
  OS:         posix
  Python:     3.12.3
  Path:       /usr
  Executable: /usr/bin/python3.12

Poetry crée automatiquement un environnement virtuel pour chaque projet, sauf si vous le désactivez via :

poetry config virtualenvs.create false

Supprimer une dépendance

Pour désinstaller une bibliothèque, utilisez simplement :

poetry remove flask

Cela met à jour automatiquement les fichiers pyproject.toml et poetry.lock.

Mettre à jour les dépendances

Besoin de mettre vos bibliothèques à jour vers les dernières versions compatibles ? Poetry s’en charge :

poetry update

Pour une bibliothèque spécifique :

poetry update flask

Vérifier l’état des dépendances

Pour une vue d’ensemble des bibliothèques installées et de leurs versions :

poetry show

Vous pouvez également voir les bibliothèques obsolètes avec :

poetry show --outdated

Gérer les scripts

Si votre projet comporte des scripts ou des commandes spécifiques, vous pouvez les configurer dans le fichier pyproject.toml. Par exemple :

[tool.poetry.scripts]
run = "mon_projet.main:run"

Ensuite, exécutez-les simplement avec :

poetry run run

Ça me fait penser à un groupe de musique, pas vous ?

Avec ces commandes de base, vous êtes déjà bien équipé pour gérer vos projets Python avec Poetry. Le prochain niveau ? Découvrir les fonctionnalités avancées pour aller encore plus loin !

Utilisation avancée de Poetry

Après avoir maîtrisé les bases de Poetry, il est temps d’explorer ses fonctionnalités avancées. Ces outils permettent de gérer des projets complexes, de travailler efficacement en équipe et de tirer parti de tout le potentiel de l’outil.

Travailler avec des bibliothèques locales

Lors du développement d’un projet qui dépend d’un autre module local, Poetry peut le gérer facilement :

• Ajouter une dépendance locale :

  poetry add ../mon_autre_projet

Cela crée un lien symbolique vers le projet local.

Gestion avancée des versions

Poetry facilite le versionnement grâce à la commande version, qui suit le versionnement sémantique (SemVer). Vous pouvez incrémenter automatiquement les parties majeures, mineures ou correctives de votre version :

poetry version patch   # Incrémente 1.0.0 -> 1.0.1
poetry version minor   # Incrémente 1.0.0 -> 1.1.0
poetry version major   # Incrémente 1.0.0 -> 2.0.0

Cela met à jour la version dans le fichier pyproject.toml.

Dépendances spécifiques à un environnement

Poetry permet de scinder vos dépendances en groupes, comme développement, tests ou production. Cela vous permet d’éviter d’installer des outils inutiles en production.

• Ajouter une dépendance pour le développement :

  poetry add black --group dev

• Installer uniquement un groupe spécifique :

  poetry install --with dev

• Ignorer certains groupes, par exemple en production :

  poetry install --without dev

Définir des contraintes de compatibilité

Pour un contrôle précis des versions de vos dépendances, Poetry utilise des opérateurs tels que :

• ^ : Compatible avec cette version (par exemple ^2.0 inclut 2.x mais pas 3.0).
• ~ : Permet les mises à jour dans la même version mineure (par exemple ~2.1 inclut 2.1.x mais pas 2.2).

Dans pyproject.toml, une contrainte pourrait ressembler à ceci :

[tool.poetry.dependencies]
flask = "^2.0"

Verrouillage des versions exactes

Le fichier poetry.lock garantit que tous les membres de l’équipe utilisent les mêmes versions de bibliothèques. Pour synchroniser l'environnement exactement sur le lock (et retirer les paquets qui n'y sont plus), utilisez la commande poetry sync (qui remplace l'ancien poetry install --sync) :

poetry sync

Sécuriser la supply chain

Au-delà de la reproductibilité, poetry.lock enregistre l'empreinte (hash) de chaque paquet : Poetry rejette un artefact qui ne correspond pas, donc altéré ou substitué sur un miroir compromis. Trois réflexes renforcent cette protection.

Auditez avant d'installer, pas après. Un paquet malveillant peut exécuter du code pendant l'installation (via setup.py d'une archive source) : scanner après coup est déjà trop tard. Auditez d'abord le lock, installez ensuite.

# Auditer les vulnérabilités connues à partir du lock
pipx run pip-audit

Forcez les wheels pour éviter toute exécution de code au build. Un wheel est une archive précompilée qui n'exécute rien à l'installation, contrairement à une archive source :

poetry config installer.only-binary :all:

Publiez avec un jeton API, jamais un mot de passe (PyPI ne l'accepte plus) : le nom d'utilisateur est __token__ et le mot de passe le jeton pypi-....

poetry config pypi-token.pypi pypi-XXXXXXXX

Publier un package sur PyPI

Vous souhaitez partager votre projet avec la communauté ? Poetry simplifie le packaging et la publication.

1. Construire le package :

   poetry build

   Cela génère des fichiers .tar.gz et .whl prêts à être envoyés sur PyPI.

2. Publier sur PyPI avec le jeton API configuré plus haut (PyPI n'accepte plus le mot de passe) :

   poetry publish

   Testez d'abord sur TestPyPI en déclarant le dépôt poetry config repositories.testpypi https://test.pypi.org/legacy/, puis poetry publish -r testpypi.

Configurations globales

Poetry propose des options de configuration globale pour personnaliser son comportement. Par exemple, pour désactiver la création d’environnements virtuels globaux :

poetry config virtualenvs.create false

Vous pouvez voir toutes les configurations en cours avec :

poetry config --list

Déboguer avec Poetry

Lorsque des problèmes surviennent, utilisez ces commandes pour obtenir des informations utiles :

• Voir les dépendances et leurs relations :

  poetry show --tree
  black 24.10.0 The uncompromising code formatter.
  ├── click >=8.0.0
  │   └── colorama *
  ├── mypy-extensions >=0.4.3
  ├── packaging >=22.0
  ├── pathspec >=0.9.0
  └── platformdirs >=2
  flask 3.1.0 A simple framework for building complex web applications.
  ├── blinker >=1.9
  ├── click >=8.1.3
  │   └── colorama *
  ├── itsdangerous >=2.2
  ├── jinja2 >=3.1.2
  │   └── markupsafe >=2.0
  └── werkzeug >=3.1
      └── markupsafe >=2.1.1
  pytest 8.3.3 pytest: simple powerful testing with Python
  ├── colorama *
  ├── iniconfig *
  ├── packaging *
  └── pluggy >=1.5,<2

• Obtenir des informations sur l’environnement virtuel :

  poetry env info

Utilisation avec Docker

Si vous travaillez avec Docker, intégrez Poetry directement dans vos images :

1. Installez Poetry dans le Dockerfile :

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

2. Assurez-vous d’utiliser l’option --no-root dans vos commandes pour éviter les conflits liés aux environnements.

Avec ces fonctionnalités avancées, Poetry devient un outil essentiel pour les projets Python complexes ou collaboratifs. Une fois maîtrisé, il simplifie non seulement la gestion des dépendances, mais aussi le développement et la publication de vos applications.

À retenir

• Poetry centralise tout dans pyproject.toml : dépendances, métadonnées, build ; Poetry 2.x supporte le format standard [project] (PEP 621).
• poetry add / remove / update gèrent les dépendances et mettent à jour poetry.lock (versions exactes + hashes).
• poetry env activate remplace poetry shell (retiré en 2.x) ; poetry run lance une commande sans activer.
• Les groupes (--group dev) séparent dev, test et production (poetry install --without dev).
• Supply chain : auditez le lock avant d'installer (pip-audit), forcez les wheels (installer.only-binary) pour éviter l'exécution de code au build.
• Publier se fait avec poetry build puis poetry publish authentifié par jeton API, jamais par mot de passe.

FAQ : questions fréquentes

Les réponses courtes ci-dessous couvrent les questions les plus recherchées sur Poetry. Les commandes sont valables pour Poetry 2.x.

C'est quoi Poetry en Python ?

Poetry est un outil qui gère les dépendances, l'environnement virtuel et le packaging d'un projet Python à partir d'un seul fichier pyproject.toml. Il remplace le trio pip, requirements.txt et virtualenv, et verrouille les versions exactes dans un fichier poetry.lock reproductible.

Comment installer Poetry ?

Le plus prudent est un gestionnaire d'outils : pipx install poetry, ou asdf/mise. Le script officiel curl install.python-poetry.org | python3 - fonctionne aussi mais exécute un script distant. Vérifiez avec poetry --version et ajoutez ~/.local/bin au PATH si besoin.

Comment ajouter une dépendance avec Poetry ?

Utilisez poetry add suivi du nom du paquet : poetry add flask. Poetry résout les versions, met à jour pyproject.toml et régénère poetry.lock. Pour une dépendance de développement, ajoutez --group dev ; pour une version précise, poetry add 'flask@^3.0'.

À quoi sert le fichier poetry.lock ?

poetry.lock enregistre les versions exactes de toutes les dépendances, sous-dépendances comprises, avec leur empreinte (hash). Il garantit des installations identiques entre développeurs, CI et production, et protège contre un paquet altéré. On le versionne avec Git.

Comment activer l'environnement virtuel de Poetry (poetry shell) ?

Depuis Poetry 2.x, poetry shell a été retiré du cœur de l'outil. Utilisez poetry env activate pour obtenir la commande d'activation, ou poetry run <commande> pour lancer une commande dans l'environnement sans l'activer. L'ancien poetry shell reste disponible via le plugin poetry-plugin-shell.

Faut-il utiliser Poetry ou uv aujourd'hui ?

Les deux gèrent dépendances, environnements et packaging via pyproject.toml et un lockfile. uv (en Rust) est bien plus rapide et gère aussi les versions de Python. Poetry est mature et très répandu. uv convient à un nouveau projet axé vitesse ; Poetry si l'équipe l'utilise déjà.

Prochaines étapes

uv : l'alternative rapide Gérer versions, dépendances et environnements avec un seul outil en Rust.

Modules et packages Comprendre la structure d'un package Python que vous publiez.

pyenv Choisir la version de Python sur laquelle Poetry crée l'environnement.

Dagger Un orchestrateur CI/CD dont le SDK Python s'appuie sur Poetry.

×

📖 Voir la documentation →