CheatPoetry Python packaging and dependencies
Light · Postcard
102 × 152 mm · PDF
Dark · Postcard
102 × 152 mm · PDF
Ink saver · Postcard
102 × 152 mm · PDF
Light · A4 landscape
297 × 210 mm · PDF
Dark · A4 landscape
297 × 210 mm · PDF
Ink saver · A4 landscape
297 × 210 mm · PDF
Light · A3 landscape
420 × 297 mm · PDF
Dark · A3 landscape
420 × 297 mm · PDF
Ink saver · A3 landscape
420 × 297 mm · PDF
Start here
poetry new <name>
New project
poetry add <pkg>
Add a dependency
poetry installInstall from the lockfile
poetry run <cmd>
Run in the project env
poetry updateUpgrade within constraints
poetry show --tree
Dependency tree
poetry buildMake sdist and wheel
poetry publishUpload to PyPI
Concepts
- pyproject.toml your constraints
- poetry.lock exact pinned versions
- Virtualenv installed packages
- Your command runs inside the env
Projects
poetry new <name>
Create a project in a new directory
poetry new --flat <name>
Flat layout instead of src/
poetry initCreate pyproject.toml interactively
poetry checkValidate pyproject.toml
poetry check --lock
Also verify poetry.lock matches
poetry versionShow the project version
poetry version <rule>
Bump patch, minor, major or set a version
Rules: patch, minor, major, prepatch, preminor, premajor,
prerelease or a PEP 440 version.
Dependencies
poetry add <pkg>...
Add dependencies and install them
poetry add <pkg>@<constraint>
Add with a version constraint
Constraint examples: ^1.2, ~1.2, >=1.2,<2, latest.
poetry add --group <name> <pkg>
Add to a dependency group
poetry add --dev <pkg>
Shortcut for the dev group
poetry add --optional <pkg>
Add as an optional dependency
poetry add --extras <extra> <pkg>
Activate extras of the package
poetry add --editable <path>
Add a local path in editable mode
poetry add --source <name> <pkg>
Install from a named source
poetry add --python <spec> <pkg>
Restrict by Python version
poetry add --dry-run <pkg>
Show what would change
poetry remove <pkg>...
Remove dependencies
poetry remove --group <name> <pkg>
Remove from a group
poetry source add --priority=<p> <name>
<url>
Add a package source
Priority is primary, supplemental or explicit.
Install and lock
poetry install
Install the project and its locked dependencies
poetry install --no-root
Skip installing the project itself
poetry install --with <group>
Include an optional group
poetry install --without <group>
Exclude a group
poetry install --only <group>
Install just that group
poetry install --all-groups
Install every group
poetry install --extras <extra>
Install an extra
poetry install --all-extras
Install every extra
poetry install --dry-run
Show operations without running them
poetry syncMake the env match the lock exactly
Removes packages not in the lock. Replaces the deprecated
install --sync.
poetry lockRefresh poetry.lock for pyproject.toml
poetry lock --regenerate
Discard the lock and resolve afresh
poetry updateUpgrade all packages within constraints
poetry update <pkg>...
Upgrade only these packages
poetry update --lock
Update the lock without installing
poetry update --dry-run
Preview an update
Running and environments
poetry run <cmd>
Run a command in the project env
poetry run python
Python REPL with project deps
poetry run pytest
Run a tool from the dev group
poetry shellSpawn a shell in the env (plugin)
poetry env infoShow env details
poetry env info --path
Print only the env path
poetry env info --executable
Print only the Python executable
poetry env use <python>
Pick or create the env for a Python
Takes a version such as 3.12 or a path to an interpreter.
poetry env listList this project's envs
poetry env remove <python>
Delete an env
Inspecting
poetry showList installed packages
poetry show <pkg>
Details for one package
poetry show --tree
Dependencies as a tree
poetry show --outdated
Only packages with newer versions
poetry show --latest
Show the latest version of each
poetry show --top-level
Only explicitly declared packages
poetry show --why <pkg>
Why a package is installed
poetry show --format json
Machine-readable output
Build and publish
poetry buildBuild sdist and wheel into dist/
poetry build --format wheel
Build only a wheel or an sdist
Value is wheel or sdist.
poetry build --output <dir>
Write to another directory
poetry publishUpload dist/ to PyPI
poetry publish --build
Build, then upload
poetry publish --repository <name>
Upload to another repository
poetry publish --dry-run
Do everything except the upload
poetry publish --skip-existing
Ignore files already uploaded
Config and maintenance
poetry config --list
Show current settings
poetry config <key> <value>
Set a setting
poetry config <key> --unset
Remove a setting
poetry config --local <key> <value>
Store in the project's poetry.toml
poetry config virtualenvs.in-project true
Create .venv inside the project
poetry cache clear --all <repo>
Clear a repository's cache
poetry self add <plugin>
Install a plugin
poetry self show plugins
List installed plugins
poetry self update
Update Poetry itself
Recipes
poetry new demo && cd demopoetry add requestspoetry add --group dev pytest ruffpoetry run pytestpoetry check --lockpoetry install --without dev --no-rootpoetry run python -m demopoetry version minorpoetry buildpoetry publish --dry-runpoetry publishpoetry config virtualenvs.in-project true --localpoetry env use 3.12poetry install
