# Poetry: Python Packaging and Dependency Manager

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](https://pydevtools.com/handbook/reference/pyproject.toml.md).

## 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](https://pydevtools.com/handbook/reference/uv.md) offers [faster dependency resolution and a broader feature set](https://pydevtools.com/handbook/explanation/how-do-uv-and-poetry-compare.md). For existing Poetry projects, see [How to migrate from Poetry to uv](https://pydevtools.com/handbook/how-to/how-to-migrate-from-poetry-to-uv.md).

## 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](https://pydevtools.com/handbook/reference/pyproject.toml.md)
* Supports [PEP 621 project metadata](https://pydevtools.com/handbook/explanation/what-is-pep-621-compatibility.md) 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`:

```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](https://pydevtools.com/handbook/how-to/how-to-protect-against-python-supply-chain-attacks-with-uv.md).

### Configuration Support

Projects can be configured through standard [PEP 621 metadata](https://pydevtools.com/handbook/explanation/what-is-pep-621-compatibility.md):

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

Or through Poetry-specific features:

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

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

## Core Features

* [PEP 621 project metadata](https://pydevtools.com/handbook/explanation/what-is-pep-621-compatibility.md) 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

* [How do uv and Poetry compare?](https://pydevtools.com/handbook/explanation/how-do-uv-and-poetry-compare.md)
* [Does Poetry Support Python Standards for Dependency Management?](https://pydevtools.com/handbook/explanation/poetry-python-dependency-management.md)
* [How to migrate from Poetry to uv](https://pydevtools.com/handbook/how-to/how-to-migrate-from-poetry-to-uv.md)
* [How to protect against Python supply chain attacks with uv](https://pydevtools.com/handbook/how-to/how-to-protect-against-python-supply-chain-attacks-with-uv.md)

## Learn More

* [How to migrate from Poetry to uv](https://pydevtools.com/handbook/how-to/how-to-migrate-from-poetry-to-uv.md)
* [Poetry Documentation](https://python-poetry.org/docs/)
* [Poetry GitHub Repository](https://github.com/python-poetry/poetry)
* [Example Poetry Package](https://github.com/python-developer-tooling-handbook/demo-poetry)
* [PEP 621 Specification](https://peps.python.org/pep-0621/)