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.

When to use Poetry

Use Poetry when you need an integrated tool for dependency management, virtual environment handling, and package publishing and your team already has an established Poetry workflow. Poetry’s lockfile and dependency group features make it well suited for application projects that need reproducible builds. For new projects, uv offers faster dependency resolution and a broader feature set; if you are currently on Poetry, 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 lock files 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
• Handles package building and publishing
• Manages project plugins and versions

Configuration Support

Projects can be configured through standard PEP 621 metadata:

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

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 compliant project metadata
• 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 requires separate plugin installation

Related Handbook Pages

• How do uv and Poetry compare?
• Does Poetry Support Python Standards for Dependency Management?
• How to migrate from Poetry to uv

Learn More

• Poetry Documentation
• Poetry GitHub Repository
• PEP 621 Specification