Poetry

Poetry replaces the fragmented Python packaging toolchain of setup.py, requirements.txt, setup.cfg, and Pipfile with a single pyproject.toml-based project format. It handles dependency declaration, version resolution, virtual environment management, building, and publishing to PyPI in one coherent CLI, rather than stitching together pip, virtualenv, twine, and setuptools separately.

At its core is a PubGrub-based dependency resolver (mixology) that produces a deterministic, cross-platform poetry.lock file so every machine and CI run installs the exact same dependency graph. This closes a long-standing gap in the Python ecosystem where pip install order and environment could silently produce different resolved versions.

Poetry also builds and publishes packages itself, using poetry-core as its PEP 517 build backend, so projects don’t need a separate setup.py or third-party build tool to produce wheels and sdists. A plugin system (poetry.plugin entry points) lets the community extend commands and behavior — used by projects like poetry-plugin-export and poetry-plugin-bundle to add functionality the core team keeps out of the base tool.

What You Get

• A single pyproject.toml file for metadata, dependencies, scripts, and build configuration, replacing setup.py/setup.cfg/requirements.txt/Pipfile
• A PubGrub-based resolver that produces a deterministic poetry.lock file, guaranteeing identical dependency graphs across machines and CI runs
• Built-in virtual environment management — poetry install creates and manages an isolated env per project automatically
• PEP 517 package building and PyPI publishing (poetry build, poetry publish) with no separate build backend needed
• Dependency groups ([tool.poetry.group.*] / PEP 735 [dependency-groups]) for organizing dev, test, docs, and lint dependencies independently
• A plugin system (poetry.plugin entry points) for extending commands, exemplified by poetry-plugin-export and poetry-plugin-bundle

Common Use Cases

• New Python project scaffolding - a developer runs poetry new or poetry init to get a working pyproject.toml, virtual environment, and lockfile without manually wiring together pip and venv
• Reproducible CI/CD builds - a team commits poetry.lock so CI installs the exact dependency versions used in development, eliminating “works on my machine” resolution drift
• Library packaging and publishing - a maintainer uses poetry build and poetry publish to produce and upload wheels/sdists to PyPI without configuring setuptools or twine separately
• Multi-environment dependency organization - a project defines separate dev, test, docs, and lint dependency groups so CI can install only what a given job needs via poetry install --with test
• Complex dependency conflict resolution - a project with many transitive dependencies relies on Poetry’s PubGrub resolver to find a valid version set or explain precisely why none exists, instead of pip’s less informative resolution failures

Under The Hood

Architecture Poetry is a layered CLI application built on the cleo framework, with src/poetry/console/commands/ holding one file per subcommand (add, install, lock, build, publish, etc.) that delegate into dedicated subsystems: factory.py builds the core Poetry object from pyproject.toml, packages/locker.py reads/writes poetry.lock, installation/installer.py and installation/executor.py drive environment sync, repositories/ abstracts PyPI and custom package indexes behind a common interface, and mixology/ implements the PubGrub-based version_solver.py that the installer calls to resolve a consistent dependency graph before anything is installed. This separation means the resolver, the repository layer, and the installer can be reasoned about and modified independently — a change to how a private index is queried lives entirely in repositories/, not scattered through command code.

Tech Stack Poetry is a Python 3.10+ application depending on poetry-core for PEP 517 build-backend logic, cleo for the CLI framework and argument parsing, dulwich for pure-Python git operations (VCS dependencies), virtualenv and findpython/pbs-installer for environment and interpreter management, keyring for credential storage, tomlkit for round-trip-safe TOML editing, requests/requests-toolbelt for registry HTTP calls, and installer/pkginfo/fastjsonschema for low-level wheel installation and metadata validation. It ships itself via pyproject.toml using its own poetry-core build backend — the project packages itself with the exact mechanism it provides to its users.

Code Quality The test suite spans 128 test files under tests/, mirroring the src/poetry/ package layout one-to-one (tests/mixology/, tests/installation/, tests/repositories/, tests/console/, etc.), run via pytest with coverage reporting configured in pyproject.toml. Type checking is enforced with mypy (strict overrides configured per-module) and linting/formatting with ruff, both wired into .pre-commit-config.yaml and GitHub Actions (tests.yaml). Error handling favors explicit, typed exception classes (PoetryError, PoetryRuntimeError) surfaced through cleo’s IO layer rather than bare excepts, and the resolver module carries dedicated failure.py/incompatibility.py types for structured conflict reporting instead of opaque resolution errors.

What Makes It Unique Poetry’s PubGrub-derived resolver (mixology/) is the project’s defining technical choice: unlike pip’s historically weaker backtracking resolver, PubGrub can explain precisely why a dependency set is unsatisfiable rather than just failing, and guarantees a deterministic lockfile result independent of installation order. Combined with owning its own PEP 517 build backend (poetry-core), Poetry collapses what is normally a chain of separate tools — pip, pip-tools, setuptools, virtualenv, twine — into one resolver-driven, lockfile-first workflow that most of the Python ecosystem still assembles manually.