Introduction to
Poetry

Foundations

• What Poetry is — origins, scope, design philosophy
• Installation — official installer, pipx, package managers
• Starting a project with poetry new & poetry init
• pyproject.toml in the Poetry 2.0 / PEP 621 era

Origin & status

• Created by Sébastien Eustace — first release Feb 2018
• 1.0 in Dec 2019; 1.2 introduced dependency groups (Aug 2022)
• 2.0 (Jan 2025) — first-class PEP 621 support, poetry sync, pluggable shell
• MIT licensed, written in Python, hosted at python-poetry/poetry
• Community-maintained; roadmap and discussions on GitHub Discussions

Problems Poetry solves

Official installer (recommended)

# macOS / Linux
curl -sSL https://install.python-poetry.org | python3 -

# Windows (PowerShell)
(Invoke-WebRequest -Uri https://install.python-poetry.org `
  -UseBasicParsing).Content | py -

# pin a version
curl -sSL https://install.python-poetry.org | \
  python3 - --version 2.0.1

First sanity check

$ poetry --version
Poetry (version 2.0.1)

$ poetry config --list
cache-dir = "/home/me/.cache/pypoetry"
virtualenvs.create = true
virtualenvs.in-project = false
virtualenvs.path = "{cache-dir}/virtualenvs"

From scratch

$ poetry new my-app
Created package my_app in my-app

$ tree -a my-app
my-app/
├── pyproject.toml
├── README.md
├── src/
│   └── my_app/
│       └── __init__.py
└── tests/
    └── __init__.py

# flat layout (no src/)
poetry new --flat my-app

# library only (skip the tests dir)
poetry new --readme=md my-app

Anatomy of a Poetry 2.0 project

[project]
name = "my-app"
version = "0.1.0"
description = "Example service"
readme = "README.md"
requires-python = ">=3.11,<3.14"
authors = [
  { name = "Brendan Lynskey",
    email = "you@example.com" }
]
dependencies = [
  "fastapi (>=0.115,<1)",
  "httpx (>=0.27,<1)",
  "pydantic (>=2.8,<3)",
]

[project.optional-dependencies]
postgres = ["asyncpg (>=0.29)"]

[tool.poetry]
package-mode = true

[tool.poetry.group.dev.dependencies]
pytest = "^8"
ruff   = "^0.6"
mypy   = "^1.10"

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

Adding

# runtime deps (caret bound by default)
poetry add fastapi httpx

# explicit version
poetry add 'pydantic@^2.8'
poetry add 'pydantic>=2.8,<3'

# dev-group dependency
poetry add --group dev pytest ruff mypy

# extras
poetry add 'fastapi[standard]'

# optional dep that becomes an extra
poetry add asyncpg --optional

# from a local path / git / URL
poetry add ./libs/internal-utils
poetry add 'git+https://github.com/foo/bar.git#main'
poetry add 'https://files.pythonhosted.org/.../wheel.whl'

# editable
poetry add --editable ./libs/internal-utils

# dry-run (don't write files)
poetry add fastapi --dry-run

Excerpt

[[package]]
name = "fastapi"
version = "0.115.4"
description = "..."
optional = false
python-versions = ">=3.8"
groups = ["main"]
files = [
  { file = "fastapi-0.115.4-py3-none-any.whl",
    hash = "sha256:abc..." },
  { file = "fastapi-0.115.4.tar.gz",
    hash = "sha256:def..." },
]

[package.dependencies]
pydantic   = ">=1.7.4,!=1.8,<3.0.0"
starlette  = ">=0.40.0,<0.42.0"
typing-extensions = ">=4.8.0"

[metadata]
lock-version = "2.1"
python-versions = ">=3.11,<3.14"
content-hash = "..."

What install does

1. Read pyproject.toml + poetry.lock
2. Verify the content-hash matches
3. Ensure a venv exists with a compatible Python
4. Install every package at its locked version + hash
5. Install the project itself in editable mode (if package-mode = true)

Default behaviour is additive — packages already in the venv that aren't in the lock are not removed.

Auto-managed venvs

# default location (cached, content-hashed)
~/.cache/pypoetry/virtualenvs/
    my-app-aB3-py3.12/

# inspect
poetry env info
poetry env info --path     # just the path
poetry env list            # all venvs Poetry knows about
poetry env list --full-path

# remove
poetry env remove python3.12
poetry env remove --all

Everyday usage

poetry run python main.py
poetry run pytest -q
poetry run ruff check .
poetry run mypy src/
poetry run ipython
poetry run python -c 'import torch; print(torch.__version__)'

# scripts defined in pyproject
poetry run serve

pyenv (most common)

# install a Python
pyenv install 3.12.7
pyenv install 3.13.0

# project-local pin (writes .python-version)
pyenv local 3.12.7

# point Poetry at it
poetry env use $(pyenv which python)
poetry env info

Switching mid-project

# nuke the old venv
poetry env remove python3.11

# tell Poetry the new one
poetry env use python3.12

# re-install — no need to re-lock if range is wide enough
poetry install

Declaring groups

[tool.poetry.group.dev.dependencies]
pytest    = "^8"
ruff      = "^0.6"
mypy      = "^1.10"

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

[tool.poetry.group.docs.dependencies]
mkdocs            = "^1.6"
mkdocs-material   = "^9"

[tool.poetry.group.profile.dependencies]
py-spy = "^0.3"
memray = "^1"

Groups are internal-only — never installed by your downstream users.

Public flags users opt into

# Poetry 2.0 / PEP 621
[project]
dependencies = [
  "fastapi (>=0.115)",
]

[project.optional-dependencies]
postgres = ["asyncpg (>=0.29)"]
redis    = ["redis (>=5)"]
all      = ["my-app[postgres,redis]"]

# Pre-2.0 syntax
[tool.poetry.dependencies]
asyncpg = { version = "^0.29", optional = true }
redis   = { version = "^5",    optional = true }

[tool.poetry.extras]
postgres = ["asyncpg"]
redis    = ["redis"]
all      = ["asyncpg", "redis"]

Defining sources

[[tool.poetry.source]]
name     = "PyPI"
priority = "primary"

[[tool.poetry.source]]
name     = "internal"
url      = "https://pkg.acme.com/simple"
priority = "supplemental"

[[tool.poetry.source]]
name     = "pytorch-cu124"
url      = "https://download.pytorch.org/whl/cu124"
priority = "explicit"

Priority levels:

• primary — searched first
• supplemental — searched only if not found upstream
• explicit — used only when a package is bound to it

Build wheels & sdists

# build into ./dist/
poetry build

# only one format
poetry build --format wheel
poetry build --format sdist

# inspect
unzip -l dist/my_app-0.1.0-py3-none-any.whl

Uses poetry-core as the PEP 517 build backend. Pure-Python by default; for native extensions add a build.py script.

Managing plugins

# install (into Poetry's own venv)
poetry self add poetry-plugin-export
poetry self add poetry-plugin-bundle
poetry self add poetry-dynamic-versioning

# list
poetry self show plugins

# upgrade / remove
poetry self update
poetry self remove poetry-plugin-export

CLI configuration

# global (default scope)
poetry config virtualenvs.in-project true
poetry config virtualenvs.path "$HOME/.venvs"
poetry config installer.parallel true
poetry config installer.max-workers 10
poetry config cache-dir "/big/disk/poetry-cache"

# project-local — writes ./poetry.toml
poetry config virtualenvs.in-project true --local

# inspect
poetry config --list
poetry config virtualenvs.in-project

The Mixology resolver

• Port of Dart's PubGrub algorithm — same family as Cargo, npm, uv
• Conflict-driven clause learning — backtracks intelligently rather than re-trying the whole graph
• Reports human-readable conflicts: "fastapi requires pydantic ≥ 2, but my-lib pins pydantic < 1"
• Slower than uv's Rust implementation but functionally equivalent — the same lock would result, just minutes vs seconds

Verdicts

• pip — the floor; fine for one-off venvs; pair with pip-tools if you want reproducibility
• pipenv — historical; lock semantics & UX have not aged well
• pdm — closest spiritual ancestor of uv; smaller ecosystem; __pypackages__ is unusual
• Hatch — strong on builds + matrices, weaker on locking
• Poetry — mature, opinionated, the de-facto standard for new app projects since ~2020
• uv — same lock semantics, much faster, single binary; fastest-rising

Stage 1 — initialise Poetry

cd existing-repo
poetry init       # answer prompts (or skip with --no-interaction)

# this writes a minimal pyproject.toml with no deps yet

Before — Poetry 1.x layout

[tool.poetry]
name        = "svc"
version     = "1.2.3"
description = "..."
authors     = ["You <you@x.com>"]
readme      = "README.md"

[tool.poetry.dependencies]
python  = "^3.12"
fastapi = "^0.115"
httpx   = "^0.27"

[tool.poetry.group.dev.dependencies]
pytest = "^8"
ruff   = "^0.6"

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

Minimal CI workflow

name: CI
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        python: ["3.11", "3.12", "3.13"]
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: ${{ matrix.python }}

      - uses: snok/install-poetry@v1
        with:
          version: '2.0.1'
          virtualenvs-in-project: true
          virtualenvs-create: true

      - name: Cache venv
        uses: actions/cache@v4
        with:
          path: .venv
          key: venv-${{ matrix.python }}-${{ hashFiles('poetry.lock') }}

      - run: poetry check --lock
      - run: poetry install --with dev --no-interaction
      - run: poetry run ruff check .
      - run: poetry run mypy src/
      - run: poetry run pytest -q --cov

Multi-stage build

# ─── builder ────────────────────────────
FROM python:3.12-slim AS builder

ENV POETRY_VERSION=2.0.1 \
    POETRY_NO_INTERACTION=1 \
    POETRY_VIRTUALENVS_CREATE=false \
    PIP_NO_CACHE_DIR=1

RUN pip install "poetry==${POETRY_VERSION}"

WORKDIR /app
COPY pyproject.toml poetry.lock ./

# install deps only — leverages layer cache
RUN poetry install --only main --no-root

# now copy code and install the project itself
COPY src/ src/
RUN poetry install --only main

# ─── runtime ────────────────────────────
FROM python:3.12-slim AS runtime
COPY --from=builder /usr/local/lib/python3.12/site-packages \
                    /usr/local/lib/python3.12/site-packages
COPY --from=builder /app /app
WORKDIR /app
CMD ["python", "-m", "myapp"]

Caret on pre-1.0 packages

Poetry's ^0.2.3 means >=0.2.3,<0.3.0, not <1.0. Catches people from npm-land. If you want any 0.x, use >=0.2,<1.

poetry shell missing in 2.0

poetry self add poetry-plugin-shell
# or:
eval $(poetry env activate)

What we covered

• Poetry as the opinionated, declarative Python toolchain
• poetry new / init for project scaffolding
• PEP 621 [project] + Poetry-specific [tool.poetry]
• poetry add / remove / install / sync
• poetry.lock as a hash-pinned, cross-platform contract
• Virtual environments — poetry env & the activate dance
• Dependency groups vs optional extras
• Private indexes & source priorities
• Build & publish via poetry-core
• Plugins, configuration, performance internals
• CI & Docker patterns; common gotchas