Poetry Cheat Sheet

01Install Poetrykeep it isolated

curl -sSL https://install.python-poetry.org | python3 -★
Official installer — puts Poetry in its own venv, off your project's PATH.
pipx install poetry★
Clean alternative if you already use pipx. Also on Homebrew, conda-forge.
pip install poetry # inside your project venv
Avoid — Poetry's own deps can clash with your project's. Keep it separate.
poetry self update
Upgrade Poetry itself (installer/pipx installs).
poetry --version · poetry about
Confirm the version — this sheet assumes 2.x.

02Start a Projectnew / init

poetry new myapp★
Scaffold a fresh project: src/ layout, tests/, README, PEP 621 pyproject.toml.
poetry new --flat myapp
Package at the top level instead of under src/.
poetry init
Interactively add a pyproject.toml to an existing codebase.
poetry init --no-interaction
Non-interactive — good for scripts/CI scaffolding.
poetry check
Validate pyproject.toml and its consistency with the lock. --lock to focus on drift.

03Add Dependenciespoetry add

poetry add httpx★
Resolve, write to [project].dependencies + poetry.lock, install — all at once.
poetry add "httpx>=0.27,<1.0"
Any PEP 508 spec. Bare add writes a caret-style >=0.28,<0.29 bound.
poetry add --group dev pytest ruff★
Into a group (2.x: -G). Replaces the old --dev flag.2.x
poetry add "httpx[socks]"
With extras. -E/--extras also works.
poetry add --editable ../mylib
Local path, editable. Also git+https://..., --source, --optional.
poetry add --dry-run numpy
Preview the resolution without changing anything.

04Remove & Updateremove / update

poetry remove httpx★
Drop from pyproject + lock + env. --group dev to target a group.
poetry update★
Re-resolve to the newest versions your constraints allow; refresh the lock.
poetry update httpx anyio
Update only named packages, leave the rest pinned.
poetry update --with dev --dry-run
Preview an update including a group.
add/update change the lock; sync doesn't
add/update re-resolve. install/sync apply the existing lock.

05Dependency Groupsorganize deps

[dependency-groups] dev = ["pytest (>=9,<10)"]★
Groups now use the standard PEP 735 table. Not shipped to your users.PEP 735
[tool.poetry.group.docs.dependencies] sphinx = "^8"
The Poetry-specific group form — still valid, needed for Poetry-only features.
poetry install --with docs★
Include an optional group. --without dev to skip one.
poetry install --only main★
Runtime deps only — the lean production/CI install. --only dev for just tools.
optional = true # under a group
A group installed only when explicitly requested with --with.

06Extras vs Groupstwo different things

[project.optional-dependencies] fast = ["orjson"]★
Extras ship with your package — users opt in via pip install pkg[fast].PEP 621
poetry install --extras "fast"
Install your own extras locally. --all-extras for all of them.
groups = dev-time; extras = ship-time★
The key distinction: groups never reach your users; extras are part of the published package.
poetry install --all-groups
Every dependency group at once.

07The Files & Layoutwhat's on disk

[project] # PEP 621★
Standard metadata: name, version, requires-python, dependencies. Commit.2.x
[tool.poetry]★
Poetry-only bits: packages, [tool.poetry.source], requires-poetry. Not deprecated.
poetry.lock★
Exact resolution + hashes + locked markers/groups. Commit it. Never hand-edit.
[build-system]
requires = ["poetry-core>=2.0"]. 2.1+ respects any PEP 517 backend here.2.1
virtualenv is NOT in the project
By default it lives in Poetry's cache, not .venv. Set in-project to change that.

08Install & Reproducepoetry install

poetry install★
Build the env from poetry.lock (locks first if missing). Installs your project too.
poetry install --no-root★
Deps only, don't install the project itself — common in Docker layers.
poetry install --only main --no-root
Leanest runtime install: no dev groups, no project.
poetry install --compile
Byte-compile to .pyc on install — faster cold starts.
poetry install --no-directory
Skip path deps — pairs with --no-root for cacheable Docker builds.

09Lock & Syncthe source of truth

poetry lock★
Resolve everything into poetry.lock without installing.
poetry lock --regenerate
Throw away the lock and re-resolve from scratch — the "clean slate" refresh.2.x
poetry sync★
Make the env exactly match the lock — installs missing and removes extras.2.x
poetry sync --only main
Prune the env down to just what a group set needs.
install --sync is deprecated
2.x split it out: use the standalone poetry sync command instead.changed
poetry check --lock
CI guard: fail if poetry.lock is out of sync with pyproject.toml.

10Environmentspoetry env

poetry env info★
Show the active env's path, Python, and details. --path for just the path.
poetry env activate★
Prints the command to activate the venv — the 2.x replacement for poetry shell.2.x
eval $(poetry env activate)★
Actually enter the env in one step.
poetry env use 3.12
Create/switch the env to a specific Python interpreter.
poetry env list · remove
List all envs for the project; env remove --all to clean them out.
poetry shell is gone in 2.x
Removed from core — use env activate, or add the shell plugin back.2.x

11Run Commandspoetry run

poetry run python app.py★
Run a command inside the managed env without activating it.
poetry run pytest · poetry run ruff check★
Any console script installed in the env.
poetry run my-cli
Runs a script you defined under [project.scripts].
poetry run python -m module
Module invocation works exactly as inside the venv.
[project.scripts] my-cli = "pkg.module:main"
Declare entry points — PEP 621 standard, installed on poetry install.

12Manage Pythonpoetry python

poetry python install 3.13★
Download a standalone CPython build — Poetry can manage interpreters now.2.x
poetry python list
Show interpreters Poetry sees, with implementation, manager & path.
poetry python remove 3.13
Remove a Poetry-managed interpreter.
poetry env use $(which python3.12)
Point the project's env at any interpreter on disk.
# experimental in 2.x
The python command group is marked experimental — handy but stabilizing.

13Inspect Dependenciespoetry show

poetry show★
Flat list of installed packages with versions & summaries.
poetry show --tree★
The full dependency graph. --why pkg explains why something's there.
poetry show --outdated
Only packages with newer versions available. --latest shows latest for all.
poetry show --top-level
Just your direct dependencies, not the transitive ones.
poetry show httpx --format json
Machine-readable output for tooling.2.2

14Build & Publishship to PyPI

poetry build★
Build sdist + wheel into dist/. --format wheel for just one.
poetry publish★
Upload dist/* to PyPI. --build to build first in one step.
poetry publish -r testpypi
Publish to a configured alternate repository.
poetry build --clean
Wipe dist/ before building. --local-version to tag a local build.2.x
[build-system] → maturin, hatchling …
2.1+ honours any PEP 517 backend, building in isolation if it isn't poetry-core.2.1

15Versioningpoetry version

poetry version★
Print the current project version.
poetry version minor
Bump it: patch / minor / major / prerelease.
poetry version 2.1.0
Set an explicit version string.
poetry version minor --dry-run
See the resulting version without writing it.
poetry version --short
Just the number — handy in CI: tag=$(poetry version --short).

16Configurationpoetry config

poetry config --list★
Show all settings & their current values.
poetry config virtualenvs.in-project true★
Put the venv in .venv inside the project — the most-changed setting.
poetry config virtualenvs.create false
Don't create a venv — useful in an already-isolated CI container.
poetry config installer.parallel true
Parallel installs (on by default). Tune installer.max-workers.
poetry config solver.min-release-age 7d
Dependency "cooldown" — ignore versions published in the last N days.2.4
poetry config ... --local
--local writes to poetry.toml beside the project instead of globally.

17Sources & Authprivate indexes

poetry source add pypi-internal https://...
Register an extra package index for the project.
[[tool.poetry.source]] priority = "supplemental"
Control ordering: primary, supplemental, or explicit.
poetry config http-basic.myindex USER PASS★
Store credentials for a source. Or a token via pypi-token.myindex.
POETRY_HTTP_BASIC_MYINDEX_PASSWORD
Every config maps to an env var — the CI-friendly way to pass secrets.
poetry add pkg --source pypi-internal
Pin a package to a specific index.

18Plugins & Exportself add

poetry export needs a plugin now★
export was unbundled in 2.0 — it's no longer built in.2.x
poetry self add poetry-plugin-export★
Add it back, then poetry export -f requirements.txt --output reqs.txt.
poetry self show plugins
List installed plugins & their versions.
poetry self add poetry-plugin-shell
Bring back the classic poetry shell command if you miss it.
[tool.poetry.requires-plugins] poetry-plugin-export = ">=1.8"
Declare plugins the project needs — auto-installed by 2.x.2.x

191.x → 2.x & Gotchaswhat changed

config moved to [project]2.0
Metadata & deps now live in PEP 621 [project], not [tool.poetry.*].
--dev → --group dev
The old --dev / [tool.poetry.dev-dependencies] gave way to groups.
poetry shell removed
Use eval $(poetry env activate), or install the shell plugin.
export & shell are plugins
Both unbundled — add via poetry self add ....
install --sync → sync
Syncing is its own command now.
^caret is written by add, not required
PEP 508 strings like >=0.28,<0.29 are canonical; ^/~ still work in [tool.poetry].
commit poetry.lock, ignore the venv★
The lock is reproducibility; the venv is disposable and rebuilt by install.

★Reading the Outputoperation lines

Package operations: 7 installs, 0 updates
the plan before it runs
- Installing httpx (0.28.1)
a package being added to the env
Writing lock file
poetry.lock was updated
Resolving dependencies...
the solver is working the graph
No dependencies to install or update
env already matches the lock
All set!
poetry check passed

poetry cheat sheet2.x

Project & Dependencies

Install, Environments & Run

Build, Publish & Config

Four things worth seeing once

the 2.x shift: [tool.poetry] → [project]

pyproject vs poetry.lock

install vs sync

where groups & extras go

Worth memorizing