← Back to package-management tools

Poetry

Package ManagerPythonpyproject.tomlVirtual EnvironmentDependency ManagementLock FileModern Python

Package Manager

Poetry

Overview

Poetry is a modern tool that streamlines dependency management and packaging for Python projects. Designed as an integrated solution to replace the traditional combination of pip, setuptools, and requirements.txt, Poetry provides configuration management through PEP 518-compliant pyproject.toml files, deterministic poetry.lock files, and automatic virtual environment management. With Poetry 2.0 released in January 2025, support for the PEP 621-compliant [project] table was added, further advancing standardization in the Python ecosystem.

Details

Poetry was developed in 2018 by Sébastien Eustace to solve the complexities of Python package management. It leverages the pyproject.toml file defined in PEP 518 to centrally manage project metadata, dependencies, and build settings. The deterministic poetry.lock file records exact versions of all dependencies, enabling reproducible builds across different environments. The dependency groups feature allows for separate management of dependencies by purpose (development, testing, documentation), improving maintainability in large-scale projects. Additionally, automatic virtual environment management maintains project-independent environments without polluting the system-wide Python installation.

Pros and Cons

Pros

  • Integrated dependency management: Replaces pip, virtualenv, and requirements.txt with a single tool
  • Deterministic builds: Precise version management through poetry.lock files
  • Automatic virtual environment management: Automatic creation and management of isolated environments per project
  • PEP compliance: Supports pyproject.toml (PEP 518) and [project] table (PEP 621)
  • Dependency groups: Separate management of development, testing, and production dependencies
  • Package publishing: Simplified publishing process to PyPI
  • Advanced dependency resolution: Automatic resolution of complex dependency conflicts

Cons

  • Learning curve: Concept understanding required when migrating from pip/virtualenv
  • Performance: Dependency resolution being Python-implemented can be time-consuming for large projects
  • Memory usage: Increased memory consumption with complex dependency graphs
  • Ecosystem compatibility: Compatibility issues with some legacy tools
  • Tool competition: Speed disadvantage compared to Rust-implemented tools like UV

Reference Links

Code Examples

Basic Project Management

# Install Poetry
curl -sSL https://install.python-poetry.org | python3 -

# Create a new project
poetry new my-project
cd my-project

# Initialize existing project
poetry init

# Install dependencies
poetry install

# Add packages
poetry add requests
poetry add pytest --group dev
poetry add mkdocs --group docs

# Remove packages
poetry remove requests
poetry remove pytest --group dev

pyproject.toml Configuration (Poetry 2.0+)

[build-system]
requires = ["poetry-core>=2.0"]
build-backend = "poetry.core.masonry.api"

[project]
name = "my-project"
version = "0.1.0"
description = "My awesome Python project"
authors = [
    {name = "Your Name", email = "your.email@example.com"}
]
readme = "README.md"
requires-python = ">=3.9"
dependencies = [
    "requests>=2.28.0",
    "click>=8.0.0",
]

[project.optional-dependencies]
dev = [
    "pytest>=7.0.0",
    "black>=22.0.0",
    "flake8>=5.0.0",
]
docs = [
    "sphinx>=5.0.0",
    "sphinx-rtd-theme>=1.0.0",
]

[tool.poetry]
packages = [{include = "my_project"}]

# Legacy Poetry format (Poetry 1.x compatible)
[tool.poetry.dependencies]
python = "^3.9"
requests = "^2.28.0"
click = "^8.0.0"

[tool.poetry.group.dev.dependencies]
pytest = "^7.0.0"
black = "^22.0.0"
flake8 = "^5.0.0"

[tool.poetry.group.docs]
optional = true

[tool.poetry.group.docs.dependencies]
sphinx = "^5.0.0"
sphinx-rtd-theme = "^1.0.0"

Dependency Group Management

# Install dependencies with specific groups
poetry install --with docs
poetry install --with dev,docs

# Install excluding specific groups
poetry install --without dev
poetry install --without dev,docs

# Install only specific groups
poetry install --only dev
poetry install --only docs,test

# Synchronized install (exact match with lock file)
poetry install --sync
poetry install --with docs --sync

# Production environment install
poetry install --only main

Virtual Environment Management

# Display virtual environment information
poetry env info
poetry env info --path

# List virtual environments
poetry env list

# Create virtual environment with specific Python version
poetry env use python3.11
poetry env use /usr/bin/python3.9
poetry env use system

# Remove virtual environments
poetry env remove python3.11
poetry env remove --all

# Execute commands in virtual environment
poetry run python main.py
poetry run pytest
poetry run black .

# Activate virtual environment shell
poetry shell

Advanced Dependency Specification

# Dependencies from Git repositories
poetry add git+https://github.com/user/repo.git
poetry add git+https://github.com/user/repo.git@branch
poetry add git+https://github.com/user/repo.git#subdirectory=subdir

# Dependencies from local paths
poetry add ./local-package
poetry add ../shared-library --editable

# Dependencies from URLs
poetry add https://example.com/package.whl

# Complex condition specification
poetry add 'requests[security,socks]>=2.25.0,<3.0.0'
poetry add 'typing-extensions; python_version<"3.8"'

# Version constraint examples
poetry add django~=4.1.0    # >=4.1.0, <4.2.0
poetry add numpy^=1.21.0    # >=1.21.0, <2.0.0
poetry add pytest@latest    # Latest version

Package Publishing and Building

# Build package
poetry build

# Configure PyPI token
poetry config pypi-token.pypi your-api-token

# Publish to Test PyPI
poetry config repositories.testpypi https://test.pypi.org/legacy/
poetry publish -r testpypi

# Publish to production PyPI
poetry publish

# Dry run verification
poetry publish --dry-run

# Build and publish simultaneously
poetry publish --build

Configuration and Customization

# Global configuration
poetry config virtualenvs.create true
poetry config virtualenvs.in-project true
poetry config virtualenvs.prefer-active-python true

# Project-specific configuration (poetry.toml)
poetry config virtualenvs.create false --local
poetry config repositories.private https://private.pypi.org/

# View configuration
poetry config --list
poetry config virtualenvs.path

# Cache management
poetry cache list
poetry cache clear pypi --all
poetry cache clear testpypi --all

# Environment variable configuration
export POETRY_VIRTUALENVS_IN_PROJECT=true
export POETRY_CACHE_DIR=/tmp/poetry-cache