Poetry
By Python Poetry Team
toml` configuration file. txt, and manual virtual environment management with one integrated command-line workflow covering a project's full lifecycle from development through release.
Definition
Poetry is a Python tool for dependency management and packaging that lets developers declare project dependencies, resolve them into a reproducible lock file, and build and publish Python packages, all through a single `pyproject.toml` configuration file. It replaces the separate use of setup.py, requirements.txt, and manual virtual environment management with one integrated command-line workflow covering a project's full lifecycle from development through release.
Overview
Python's packaging tooling historically grew piecemeal: setuptools handled building distributable packages, pip installed them, virtualenv isolated environments, and requirements.txt files loosely tracked dependencies without pinning the full dependency tree or guaranteeing reproducible installs. Poetry was created to consolidate these responsibilities into a single tool built around the pyproject.toml standard that the Python community had adopted for project metadata. When a developer declares dependencies in pyproject.toml, Poetry's dependency resolver computes a complete, conflict-free set of package versions across the entire dependency tree and writes the result to a poetry.lock file, which subsequent installs use to reproduce the exact same environment. Poetry also manages a project's virtual environment automatically, creating one on demand and exposing commands like `poetry run` and `poetry shell` to execute code inside it. For package authors, `poetry build` and `poetry publish` handle constructing distributable wheel and source archives and uploading them to PyPI, folding what used to require setuptools, twine, and manual version bumps into native commands. Poetry differs from Pipenv, an earlier attempt at similar consolidation, mainly by covering the full lifecycle including build and publish steps that Pipenv leaves to other tools, and by generally offering a faster dependency resolver. It differs from Conda by staying within the pure Python packaging ecosystem rather than managing arbitrary system-level and non-Python dependencies, which keeps it lighter weight but less suited to projects needing compiled scientific libraries with complex native dependencies. In practice, Poetry has become a common choice for both Python applications and open-source libraries: application teams use its lock file for reproducible deployments, while library maintainers use its build and publish commands to release packages to PyPI without assembling a separate toolchain. Its adoption grew alongside the broader Python community's move toward pyproject.toml as the standard project configuration file, and many open-source projects migrated their build configuration to Poetry specifically to gain that reproducibility without adopting multiple separate tools, consolidating what used to be several configuration files into one. Poetry's dependency resolver, while generally reliable, can occasionally take a long time to resolve complex dependency trees with many version constraints, and some large scientific or data-science projects with heavy native dependencies still find Conda's environment management better suited to their needs. Migrating an existing project with a legacy setup.py to Poetry's conventions can also require nontrivial restructuring, particularly for projects with custom build steps or compiled extensions that do not map cleanly onto Poetry's standard build backend and require a custom plugin or manual reconfiguration to work correctly.
Key Features
- Manages dependencies, environments, builds, and publishing in one tool
- Uses pyproject.toml as the single source of project configuration
- Generates a poetry.lock file for fully reproducible dependency installs
- Automatically creates and manages a project-specific virtual environment
- Resolves the full dependency tree to avoid version conflicts
- Builds wheel and source distributions for publishing to PyPI
- Provides poetry run and poetry shell for working inside managed environments
- Supports dependency groups for separating development and runtime needs