Poetry — Python Packaging and Dependency Management Made Easy

Introduction

Poetry brings modern dependency management to Python. Before Poetry, Python developers juggled setup.py, requirements.txt, pip-tools, and virtualenv — each handling a piece of the packaging puzzle. Poetry unifies all of this into a single tool with a deterministic lockfile, automatic virtual environment management, and a modern pyproject.toml configuration.

With over 34,000 GitHub stars, Poetry has been the most popular Python project manager for years. While uv (by Astral) is gaining ground with its speed advantage, Poetry remains widely used for its maturity, stability, and extensive ecosystem integration.

What Poetry Does

Poetry manages the complete lifecycle of a Python project: creating projects with standard structure, declaring dependencies in pyproject.toml, resolving compatible versions, generating a lockfile for reproducibility, managing virtual environments, building packages, and publishing to PyPI.

Architecture Overview

[pyproject.toml]
Project metadata,
dependencies, build config
        |
   [Poetry CLI]
   add, install, update,
   build, publish, run
        |
+-------+-------+
|       |       |
[Dependency [Virtual    [Build &
Resolver]   Environment] Publish]
SAT solver  Auto-create  sdist,
Lockfile    and manage   wheel,
generation  per-project  PyPI
        |
   [poetry.lock]
   Deterministic,
   cross-platform,
   hash-verified

Self-Hosting & Configuration

# pyproject.toml — Poetry project configuration
[tool.poetry]
name = "my-app"
version = "1.0.0"
description = "My awesome application"
authors = ["Developer <dev@example.com>"]
readme = "README.md"

[tool.poetry.dependencies]
python = "^3.11"
fastapi = "^0.115"
sqlalchemy = "^2.0"
httpx = "^0.27"

[tool.poetry.group.dev.dependencies]
pytest = "^8.0"
black = "^24.0"
mypy = "^1.13"

[tool.poetry.scripts]
serve = "my_app.main:run"

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

# Common Poetry workflows
poetry new my-project          # Create project with structure
poetry init                    # Add Poetry to existing project
poetry add fastapi             # Add dependency
poetry add --group dev pytest  # Add dev dependency
poetry install                 # Install all dependencies
poetry update                  # Update to latest compatible versions
poetry lock                    # Regenerate lockfile
poetry run python main.py      # Run in virtual environment
poetry build                   # Build sdist and wheel
poetry publish                 # Publish to PyPI
poetry shell                   # Activate virtual environment
poetry env info                # Show environment information

Key Features

• Dependency Resolution — SAT solver finds compatible version combinations
• Lockfile — deterministic builds with poetry.lock
• Virtual Environments — automatic per-project environment management
• Dependency Groups — separate dev, test, and docs dependencies
• Build System — PEP 517 compliant builds (sdist + wheel)
• Publishing — one-command publishing to PyPI or private registries
• Plugin System — extend Poetry with community plugins
• pyproject.toml — single configuration file (PEP 621 compatible)

Comparison with Similar Tools

FAQ

Q: Poetry vs uv — which should I use? A: uv is dramatically faster and offers Python version management. Poetry is more mature with a larger ecosystem. For new projects, uv is increasingly recommended. For existing Poetry projects, migration is optional.

Q: How do I use Poetry with Docker? A: Export requirements: "poetry export -f requirements.txt -o requirements.txt". Then use pip in Docker: "RUN pip install -r requirements.txt". Or install Poetry in the Docker image for lockfile-based installs.

Q: Can I use Poetry with monorepos? A: Poetry supports path dependencies for local packages. Use "poetry add --editable ../shared-lib" for inter-package dependencies within a monorepo.

Q: How do I migrate from requirements.txt to Poetry? A: Run "poetry init" in your project, then use "cat requirements.txt | xargs poetry add" to add existing dependencies. Poetry generates the pyproject.toml and lockfile.

Sources

• GitHub: https://github.com/python-poetry/poetry
• Documentation: https://python-poetry.org/docs
• Website: https://python-poetry.org
• Created by Sebastien Eustace
• License: MIT