# 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

### 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

## 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)

## Learn More

* [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/)