Python Poetry Cheat Sheet
Project setup, dependency management, virtual environments, and publishing workflow using Poetry as an all-in-one Python packaging tool.
1 PageBeginnerFeb 14, 2026
Project Setup
Initialize a new project or adopt Poetry in an existing one.
bash
poetry new myproject # scaffold a new project with src layoutcd myprojectpoetry init # interactively create pyproject.toml in an existing dirpoetry check # validate pyproject.tomlpoetry env info # show the active virtualenv's details
Managing Dependencies
Add, remove, and update packages; Poetry updates pyproject.toml and the lockfile.
bash
poetry add requests # add a runtime dependencypoetry add pytest --group dev # add a dev-only dependency (groups)poetry add "django>=4.2,<5.0" # version constraintpoetry remove requests # remove a dependencypoetry update # update all deps within constraintspoetry update requests # update just one packagepoetry show --tree # show dependency treepoetry lock # regenerate poetry.lock without installing
Running & Environments
Poetry manages an isolated virtualenv per project by default.
bash
poetry install # install all deps from poetry.lockpoetry install --no-dev # (legacy) or: poetry install --only mainpoetry install --sync # remove packages not in the lockfilepoetry run python script.py # run inside the project's venvpoetry run pytest # run a tool inside the venvpoetry shell # spawn a subshell with the venv activatedpoetry env use python3.12 # pin the interpreter version
Building & Publishing
Build sdist/wheel and publish to PyPI.
bash
poetry build # produce dist/*.whl and dist/*.tar.gzpoetry config pypi-token.pypi <token> # store a PyPI API tokenpoetry publish # build (if needed) and upload to PyPIpoetry publish --build # explicit build + publish in one steppoetry version patch # bump 1.2.3 -> 1.2.4 in pyproject.toml
pyproject.toml Sections
Key tables Poetry reads to configure the project.
- [tool.poetry]- name, version, description, authors, license
- [tool.poetry.dependencies]- runtime dependencies incl. python version constraint
- [tool.poetry.group.dev.dependencies]- named dependency groups (dev, test, docs, ...)
- [tool.poetry.scripts]- console-script entry points installed as CLI commands
- [build-system]- requires = ["poetry-core"], required for PEP 517 builds
- poetry.lock- pinned, hashed dependency graph; commit this to version control
Optional Dependency Groups & Extras
Groups control what's installed by default vs. on demand; extras expose optional feature sets to consumers of your published package.
toml
[tool.poetry.group.docs]optional = true[tool.poetry.group.docs.dependencies]sphinx = "^7.0"myst-parser = "^2.0"[tool.poetry.dependencies]python = "^3.11"redis = { version = "^5.0", optional = true }[tool.poetry.extras]cache = ["redis"]
Installing Optional Groups & Extras
Commands to selectively install the groups/extras defined above.
bash
poetry install --with docs # install main deps + the optional docs grouppoetry install --without docs # explicitly skip a non-optional grouppoetry install --only main,docs # install only these groups, nothing elsepoetry install --extras cache # install the 'cache' extra for end userspoetry install --all-extras # install every declared extrapip install "mypkg[cache]" # how a downstream pip user requests it
Private & Custom Package Sources
Configure additional package indexes (private registries, mirrors) beyond PyPI, with per-source priority.
toml
[[tool.poetry.source]]name = "internal"url = "https://pypi.internal.example.com/simple/"priority = "explicit" # only used when a dependency names this source[tool.poetry.dependencies]my-internal-lib = { version = "^2.0", source = "internal" }
Path, Git & Monorepo Dependencies
Reference sibling packages or unreleased git commits directly, useful in monorepos and pre-release development.
bash
# In pyproject.toml:# [tool.poetry.dependencies]# shared-utils = { path = "../shared-utils", develop = true } # editable local path# some-lib = { git = "https://github.com/org/some-lib.git", branch = "main" }# other-lib = { git = "https://github.com/org/other-lib.git", rev = "a1b2c3d" }poetry lock # resolves path/git refs into poetry.lock toopoetry install # develop=true installs the local path in editable mode
Poetry Plugins & Configuration
Extending Poetry's behavior and tuning its global/project-local settings.
- poetry self add poetry-plugin-export- installs a plugin into Poetry's own environment (not the project's)
- poetry export -f requirements.txt -o requirements.txt- generate a pinned requirements.txt from poetry.lock (needs the export plugin)
- poetry config virtualenvs.in-project true- create the venv as .venv inside the project instead of a global cache dir
- poetry.toml- project-local config overrides, not committed the same way as pyproject.toml conventions vary by team
- poetry cache clear pypi --all- clear cached wheels/sdists when debugging resolution issues
- poetry-dynamic-versioning plugin- derive the package version from git tags instead of hardcoding it
- dependency-groups (PEP 735) migration- newer poetry-core supports the PEP 621 [project] table alongside [tool.poetry]
Pro Tip
Always commit poetry.lock alongside pyproject.toml — it's what gives every machine and CI run the exact same resolved dependency graph, not just versions satisfying your constraints.
Was this cheat sheet helpful?
Explore Topics
#PythonPoetry#PythonPoetryCheatSheet#Programming#Beginner#ProjectSetup#ManagingDependencies#RunningEnvironments#BuildingPublishing#CheatSheet#SkillVeris
