What is Poetry in Python?

Poetry is a Python packaging and dependency management tool that handles dependency installation, virtual environment creation, package building, and publishing through a unified workflow. It configures projects in `pyproject.toml` and produces a `poetry.lock` file for reproducible installs.

What is the difference between Poetry and pip?

pip only installs packages; Poetry adds dependency resolution with a lockfile, automatic virtual environment management, dependency groups, and commands for building and publishing distributions. Projects using pip typically pair it with separate tools like `venv`, `pip-tools`, and `build`, while Poetry combines those responsibilities in one CLI.

How do I install Poetry?

The recommended install uses the official installer script or `pipx install poetry`, which places Poetry in an isolated environment on PATH. See the official Poetry installation docs for the current command for your operating system.

Should I use Poetry or uv?

Poetry remains a solid choice for teams with existing Poetry workflows and is a mature option for application projects. For new projects, uv resolves and installs dependencies substantially faster, manages Python versions, and covers more of the packaging workflow in one tool, which is why the handbook recommends uv as the default.

Does Poetry support pyproject.toml standards?

Yes. Poetry 2.0 adopted PEP 621 project metadata under the standard `[project]` table, so dependencies and project information can be declared using the same schema other tools read. Poetry-specific options remain available under `[tool.poetry]` for features that aren't covered by the standard.

Poetry: Python Packaging and Dependency Manager

by Tim Hopper · Markdown

Packaging

Poetry is a Python packaging and dependency management tool that handles dependency installation, virtual environment management, package building, and publishing. It aims to provide a unified workflow for Python project management through configuration in pyproject.toml.

When to Use Poetry

Poetry fits teams that already have an established Poetry workflow and need integrated dependency management, virtual environment handling, and package publishing. Its lockfile and dependency group features suit application projects that require reproducible builds.

For new projects, uv offers faster dependency resolution and a broader feature set. For existing Poetry projects, see How to migrate from Poetry to uv.

Key Components

Dependency Management

Handles package installation and removal
Resolves dependencies with version constraints
Creates and updates lockfiles for reproducible installations
Manages virtual environments automatically
Supports dependency groups for development, testing, etc.

Project Management

Initializes new Python projects with poetry new
Configures projects via pyproject.toml
Supports PEP 621 project metadata under the standard [project] table, adopted in Poetry 2.0
Handles package building and publishing
Manages project plugins and versions

Dependency Cooldown

Poetry 2.4.0 added solver.min-release-age, a dependency cooldown that excludes recently published versions from resolution. A version is considered only when all of its known distribution files are at least the configured number of days old, which gives the community time to detect and yank a compromised release before it enters the lockfile. The setting lives under [solver] in poetry.toml:

[solver]
min-release-age = 7
min-release-age-exclude = "internal-lib,other-package"
min-release-age-exclude-source = "private-repo"

min-release-age-exclude takes a comma-separated list of package names to evaluate without the age filter; min-release-age-exclude-source exempts every package from named indexes. The equivalent CLI command is poetry config --local solver.min-release-age 7, and the equivalent environment variable is POETRY_SOLVER_MIN_RELEASE_AGE (an integer number of days). The feature mirrors uv’s exclude-newer cooldown.

Configuration Support

Projects can be configured through standard PEP 621 metadata:

[project]
name = "example"
version = "0.1.0"
description = "Project description"
requires-python = ">=3.10"
dependencies = [
    "requests>=2.32"
]

Or through Poetry-specific features:

[tool.poetry]
packages = [{include = "example"}]
requires-poetry = ">=2.0"

[tool.poetry.requires-plugins]
my-plugin = ">1.0"

Core Features

PEP 621 project metadata support
Lockfile-based dependency resolution
Virtual environment management
Build system for distributions
Package publishing workflow
Plugin system for extensibility
Group-based dependency management
Project-specific Poetry version requirements
Dependency cooldown via solver.min-release-age (Poetry 2.4.0+)

Limitations

Slower dependency resolution than newer tools like uv
Some non-standard dependency specification features
Export functionality lives in poetry-plugin-export, which is no longer bundled with Poetry starting in 2.0 and must be installed separately

Related Handbook Pages

Learn More

Last updated on June 1, 2026

pixi prek

Please submit corrections and feedback...