Poetry: Python Dependency Management and Packaging

Poetry predates uv by several years and was, for a substantial period, the dominant answer to a real, long-standing gap in Python's tooling ecosystem: no single, official tool historically handled dependency management, virtual environment creation, *and* package building/publishing together with one consistent interface and one lock-file format. Poetry filled that gap with a strongly opinionated, cohesive workflow, and as a result, a very large number of real, existing Python projects — libraries you likely already depend on, and internal codebases at many companies — are built around it today.

poetry add httpx mirrors the same 'update the declaration and the lock file together, atomically' philosophy uv's uv add implements — both tools recognize the same underlying risk (a declaration and a lock file drifting out of sync when edited separately) and solve it the same structural way, despite being built independently and with different implementation languages (Poetry is written in Python; uv in Rust).

Knowing Poetry well, even in a world where uv is often the faster newer choice for greenfield projects, remains genuinely practical: a large fraction of existing, real Python codebases — including many popular open-source libraries — are Poetry-managed, and contributing to or maintaining any of them requires fluency with Poetry's specific commands and conventions, not just theoretical knowledge that 'unified tools exist.'

Like uv, Poetry manages a virtual environment automatically per project — poetry install creates (or reuses) a dedicated environment specifically for the current project, installing exactly what poetry.lock specifies, without requiring the manual python -m venv and activation steps covered in the Virtual Environment Best Practices lesson. poetry run pytest (or any other command) executes inside that project's environment automatically, mirroring uv run's activation-free execution model.

This was, at the time Poetry established this pattern, a genuine innovation over the traditional manual venv workflow — automatically tying a project's environment to its lock file and dependency declarations, rather than requiring a developer to manage that connection manually themselves. It's worth recognizing this as the same underlying idea uv later adopted and optimized for speed, rather than something uv invented independently — Poetry demonstrated the value of this unified, automatic environment model years before uv existed.

The practical difference day to day, for a developer used to either tool, is largely about specific command syntax (poetry install/poetry run versus uv sync/uv run) and — the most commonly cited practical distinction — resolution and installation speed, where uv's Rust implementation provides a measurable, often substantial advantage over Poetry's pure-Python resolver for larger or more complex dependency trees.

Poetry's scope extends beyond dependency management into the complete package lifecycle: poetry build produces both a wheel (the binary distribution format most installs actually use) and a source distribution from your project, using the metadata already declared in pyproject.toml; poetry publish uploads that built package directly to PyPI (or a configured private package index), handling the authentication and upload process in the same tool, no separate twine-style upload utility required (though Poetry can integrate with such tools if needed).

This 'one tool, full lifecycle' scope is exactly the design philosophy that made Poetry influential in shaping what developers now expect from Python packaging tools generally — the same expectation uv's own build and publish capabilities (uv build, uv publish) were designed to meet, following the path Poetry established. Understanding that this all-in-one scope, not just fast dependency resolution, was Poetry's original core value proposition helps explain why it achieved such wide adoption before a Rust-based competitor with a speed advantage existed at all.

The practical decision between Poetry and uv for a new project today often comes down to team familiarity and specific ecosystem integration needs more than a clear-cut technical superiority in either direction — both are legitimate, capable, actively-maintained choices, and the more important professional skill is understanding the underlying concepts (dependency resolution, lock files, unified environment management) well enough to work effectively with whichever specific tool a given project has already chosen.

uv is faster, but Poetry got to the 'one unified tool' idea years earlier and remains extremely widely used — knowing it matters for a large fraction of real, existing Python projects.

poetry add manages both pyproject.toml AND the lock file together, in one atomic step -- the same core idea uv's 'uv add' also implements.

Checkpoint: What does poetry add httpx update, beyond just installing the package?

• →Both pyproject.toml's dependency declaration and poetry.lock, together, in one atomic step
• →Only poetry.lock -- pyproject.toml must still be edited manually

poetry install reads poetry.lock for reproducible installs -- and poetry automatically manages its own virtual environment per project.

poetry build and poetry publish handle the FULL packaging lifecycle -- from source code to a published package on PyPI, all in the same tool.

Checkpoint: Does Poetry require a separate tool for building and publishing a package to PyPI, beyond dependency management?

• →No — poetry build and poetry publish handle the full build-and-publish lifecycle within the same tool
• →Yes — Poetry only handles dependency management; a separate tool is required for building and publishing

Poetry and uv represent two takes on unified tooling; Building Packages is the next lesson, covering what actually happens when either tool (or a lower-level one) turns your source code into a distributable package.

Add to a Real Dependency Group. Finish add_to_group(): keep dev-only tools in their own group, separate from main dependencies.