Poetry & PDM
Poetry and PDM are full-featured Python project managers that handle dependency resolution, lockfiles, virtual environments, and publishing. Both use pyproject.toml as the single source of truth.
//
Search across all documentation pages
Poetry and PDM are full-featured Python project managers that handle dependency resolution, lockfiles, virtual environments, and publishing. Both use pyproject.toml as the single source of truth.
Quick-reference recipe card - copy-paste ready.
# Poetry
curl -sSL https://install.python-poetry.org | python3 -
poetry new myapp
poetry add fastapi pydantic
poetry run pytest
# PDM
pip install pdm
pdm init
pdm add fastapi pydantic
pdm run pytestWhen to reach for this:
requirements.txt to modern packaging# pyproject.toml shared concepts (Poetry or PDM)
[project]
name = "myapp"
version = "0.1.0"
requires-python = ">=3.14"
dependencies = ["fastapi>=0.115", "pydantic>=2"]
[dependency-groups]
dev = ["pytest>=8", "ruff>=0.9"]# Poetry workflow
poetry install --with dev
poetry run uvicorn myapp.main:app
# PDM workflow
pdm install -G dev
pdm run uvicorn myapp.main:appWhat this demonstrates:
[project] metadatapoetry.lock / pdm.lock) pin exact versionsrun executes commands inside the managed environment.venv (or uses an existing one), resolves deps, writes poetry.lock, and can build/publish wheels__pypackages__) or traditional .venv, resolves via pdm.lock, and follows PEP standards closelypyproject.toml constraints change| Feature | Poetry | PDM |
|---|---|---|
| Lockfile | poetry.lock | pdm.lock |
| Venv location | .venv (configurable) | .venv or __pypackages__ |
| Build backend | poetry-core | pdm-backend |
| Publish | poetry publish | pdm publish |
| Speed | Moderate | Moderate |
| PEP 621 native | Yes (2.x+) | Yes |
# Poetry: export for Docker/CI without Poetry installed
poetry export -f requirements.txt --output requirements.txt --without-hashes
# PDM: use uv as installer backend for speed
pdm config install.use_uv truepoetry.lock/pdm.lock; run install with --frozen equivalent.[tool.poetry] vs [project] blocks differ. Fix: migrate to Poetry 2.x PEP 621 layout for new projects.__pypackages__ and IDEs - editors may not find packages. Fix: use .venv mode (pdm config python.use_venv true) for IDE compatibility.pipx install poetry or the official GitHub Action with a pinned version.| Alternative | Use When | Don't Use When |
|---|---|---|
| uv | New projects, speed priority | Team mandate for Poetry |
| pip + pip-tools | Minimal deps, no build step | Complex dependency trees |
| Hatch | Simple builds, no resolver | You need a full project manager |
uv is faster and simpler for most teams. Choose Poetry when you need its mature publish workflow and the team already knows it.
Both support PEP 621 [project], but tool-specific sections ([tool.poetry], [tool.pdm]) differ. Standardize on one tool per repo.
[dependency-groups] (Poetry 2.x) or [tool.poetry.group.dev.dependencies] for dev-only packages. Install with poetry install --with dev.
No. PDM can use PEP 582 local packages. For IDE support, enable venv mode.
Poetry: poetry update. PDM: pdm update. Both regenerate the lockfile with latest compatible versions.
Poetry: poetry add $(cat requirements.txt). PDM: pdm import requirements.txt. Then commit the lockfile.
Define [project.scripts] or [tool.poetry.scripts] and use poetry run <script> or pdm run <script>.
Both respect requires-python in pyproject.toml. Use poetry env use 3.14 or pdm use 3.14 to pin the interpreter.
Poetry: poetry build && poetry publish. PDM: pdm build && pdm publish. Configure tokens via env vars, not in files.
Mostly yes, but platform-specific wheels may differ. CI should generate or verify lockfiles on each target OS.
Stack versions: This page was written for Python 3.14.0, FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, and uv 0.6+.
Reviewed by Chris St. John·Last updated Jul 19, 2026