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.

Recipe

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 pytest

When to reach for this:

Team already standardized on Poetry or PDM
You need built-in build and publish workflows
Dependency groups (dev, docs, test) with lockfile guarantees
Migrating from requirements.txt to modern packaging

Working Example

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

What this demonstrates:

Both tools read PEP 621 [project] metadata
Lockfiles (poetry.lock / pdm.lock) pin exact versions
run executes commands inside the managed environment
Dev groups install separately from production dependencies

Deep Dive

How It Works

Poetry creates a .venv (or uses an existing one), resolves deps, writes poetry.lock, and can build/publish wheels
PDM supports PEP 582 (__pypackages__) or traditional .venv, resolves via pdm.lock, and follows PEP standards closely
Both resolve transitive dependencies and detect conflicts before install
Lockfiles are regenerated when pyproject.toml constraints change

Feature Comparison

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

Python Notes

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

Gotchas

Committing different lockfile versions - CI and local diverge. Fix: commit poetry.lock/pdm.lock; run install with --frozen equivalent.
Poetry 1.x vs 2.x config drift - [tool.poetry] vs [project] blocks differ. Fix: migrate to Poetry 2.x PEP 621 layout for new projects.
PDM __pypackages__ and IDEs - editors may not find packages. Fix: use .venv mode (pdm config python.use_venv true) for IDE compatibility.
Global tool install in CI - slow and version-unpinned. Fix: use pipx install poetry or the official GitHub Action with a pinned version.
Mixing Poetry and uv in one repo - two lockfiles fight each other. Fix: pick one toolchain per project.

Alternatives

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

FAQs

Should new projects use Poetry or uv?

uv is faster and simpler for most teams. Choose Poetry when you need its mature publish workflow and the team already knows it.

Can Poetry and PDM read the same pyproject.toml?

Both support PEP 621 [project], but tool-specific sections ([tool.poetry], [tool.pdm]) differ. Standardize on one tool per repo.

How do dependency groups work in Poetry?

[dependency-groups] (Poetry 2.x) or [tool.poetry.group.dev.dependencies] for dev-only packages. Install with poetry install --with dev.

Does PDM require a venv?

No. PDM can use PEP 582 local packages. For IDE support, enable venv mode.

How do I update all dependencies?

Poetry: poetry update. PDM: pdm update. Both regenerate the lockfile with latest compatible versions.

Can I migrate from requirements.txt?

Poetry: poetry add $(cat requirements.txt). PDM: pdm import requirements.txt. Then commit the lockfile.

How do I run scripts without remembering paths?

Define [project.scripts] or [tool.poetry.scripts] and use poetry run <script> or pdm run <script>.

What Python versions do they support?

Both respect requires-python in pyproject.toml. Use poetry env use 3.14 or pdm use 3.14 to pin the interpreter.

How do I publish to PyPI?

Poetry: poetry build && poetry publish. PDM: pdm build && pdm publish. Configure tokens via env vars, not in files.

Are lockfiles portable across platforms?

Mostly yes, but platform-specific wheels may differ. CI should generate or verify lockfiles on each target OS.

uv - The Fast Toolchain - faster alternative
pyproject.toml Explained - config reference
Dependency Resolution & Lockfiles - pinning deep dive
Environments Best Practices - team conventions

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+.

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.

Recipe

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 pytest

When to reach for this:

Team already standardized on Poetry or PDM
You need built-in build and publish workflows
Dependency groups (dev, docs, test) with lockfile guarantees
Migrating from requirements.txt to modern packaging

Working Example

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

What this demonstrates:

Both tools read PEP 621 [project] metadata
Lockfiles (poetry.lock / pdm.lock) pin exact versions
run executes commands inside the managed environment
Dev groups install separately from production dependencies

Deep Dive

How It Works

Poetry creates a .venv (or uses an existing one), resolves deps, writes poetry.lock, and can build/publish wheels
PDM supports PEP 582 (__pypackages__) or traditional .venv, resolves via pdm.lock, and follows PEP standards closely
Both resolve transitive dependencies and detect conflicts before install
Lockfiles are regenerated when pyproject.toml constraints change

Feature Comparison

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

Python Notes

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

Gotchas

Committing different lockfile versions - CI and local diverge. Fix: commit poetry.lock/pdm.lock; run install with --frozen equivalent.
Poetry 1.x vs 2.x config drift - [tool.poetry] vs [project] blocks differ. Fix: migrate to Poetry 2.x PEP 621 layout for new projects.
PDM __pypackages__ and IDEs - editors may not find packages. Fix: use .venv mode (pdm config python.use_venv true) for IDE compatibility.
Global tool install in CI - slow and version-unpinned. Fix: use pipx install poetry or the official GitHub Action with a pinned version.
Mixing Poetry and uv in one repo - two lockfiles fight each other. Fix: pick one toolchain per project.

Alternatives

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

FAQs

Should new projects use Poetry or uv?

uv is faster and simpler for most teams. Choose Poetry when you need its mature publish workflow and the team already knows it.

Can Poetry and PDM read the same pyproject.toml?

Both support PEP 621 [project], but tool-specific sections ([tool.poetry], [tool.pdm]) differ. Standardize on one tool per repo.

How do dependency groups work in Poetry?

[dependency-groups] (Poetry 2.x) or [tool.poetry.group.dev.dependencies] for dev-only packages. Install with poetry install --with dev.

Does PDM require a venv?

No. PDM can use PEP 582 local packages. For IDE support, enable venv mode.

How do I update all dependencies?

Poetry: poetry update. PDM: pdm update. Both regenerate the lockfile with latest compatible versions.

Can I migrate from requirements.txt?

Poetry: poetry add $(cat requirements.txt). PDM: pdm import requirements.txt. Then commit the lockfile.

How do I run scripts without remembering paths?

Define [project.scripts] or [tool.poetry.scripts] and use poetry run <script> or pdm run <script>.

What Python versions do they support?

Both respect requires-python in pyproject.toml. Use poetry env use 3.14 or pdm use 3.14 to pin the interpreter.

How do I publish to PyPI?

Poetry: poetry build && poetry publish. PDM: pdm build && pdm publish. Configure tokens via env vars, not in files.

Are lockfiles portable across platforms?

Mostly yes, but platform-specific wheels may differ. CI should generate or verify lockfiles on each target OS.

uv - The Fast Toolchain - faster alternative
pyproject.toml Explained - config reference
Dependency Resolution & Lockfiles - pinning deep dive
Environments Best Practices - team conventions

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+.

Poetry & PDM

Search Documentation

Poetry & PDM