Build Automation Tools (pip & Poetry)

This content was generated with the assistance of AI and should be verified against the official documentation before being relied on in production.

The reference material consulted while preparing these pages is listed in the Python Reference bibliography.

In Java, one tool (Maven or Gradle) compiles, tests, packages and publishes. Python splits the same work across standards and interchangeable tools: pyproject.toml describes a project, a build backend turns it into distribution files, an installer puts those files into an environment, and a package index stores and serves them. "Build automation" in Python is the choice and wiring of those tools, so that every developer and every CI job builds, locks, installs and publishes the same way. This section covers the two tools most projects choose between: pip, the standard installer that ships with Python, and Poetry, an all-in-one dependency manager and packaging tool built on the same standards. Basic virtual environments and a first upload are on Virtual Environments & Packaging; this section goes much further.

This is the Python counterpart of the JVM section, JVM Build Tools: Ant, Maven & Gradle (issue #300); the two sections share no pages. Two related topics are still open issues: a comparison of programming languages (issue #196) and command-line applications (issue #236).

The five roles

flowchart LR SRC["Source tree + pyproject.toml"] -->|"frontend calls PEP 517 hooks: pip, build, poetry build"| BE["Build backend: hatchling, setuptools, poetry-core, ..."] BE --> DIST["sdist (.tar.gz) and wheel (.whl)"] DIST -->|"upload: twine, poetry publish"| IDX[("Index: PyPI, TestPyPI, private")] IDX -->|"resolve + download: pip, Poetry"| INST["Installer: pip, Poetry's installer"] DIST -.->|"local files"| INST INST --> ENV["Environment: venv, Poetry env, pipx env"]
Role Job pip side Poetry side

Build frontend

Reads [build-system], creates an isolated build environment, calls the backend’s hooks.

pip (when installing from source), python -m build

poetry build, poetry install (for the project)

Build backend

Turns the project into an sdist and a wheel, writing the core metadata.

any: hatchling, setuptools, flit-core, pdm-backend, uv_build, …

poetry-core (or any backend since Poetry 2.1)

Installer

Resolves versions and installs wheels into an environment.

pip install

poetry install / poetry sync (its own installer)

Index

Stores distributions and serves them through the simple API.

PyPI, TestPyPI, private indexes; upload with twine

the same; upload with poetry publish

Environment

Where the packages end up.

a venv you create (python -m venv)

one Poetry creates and manages per project

pip versus Poetry in one paragraph. pip installs what it is told into whichever environment runs it: it resolves, downloads, builds and installs, and since 25.1 it can write a pylock.toml, but it does not manage projects, environments, version bumps or publishing ("pip is not a workflow management tool"); you combine it with venv, build, twine and a requirements or lock file. Poetry manages the whole project: it edits pyproject.toml (poetry add), keeps a cross-platform poetry.lock, creates the virtual environment, builds with poetry-core and publishes. The choice, and the way from one to the other, is on Choosing & Migrating.

Source: pip: pip is not a workflow management tool, PUG: Tool recommendations, PUG: Key projects: pip, Key projects: Poetry, Poetry: Introduction.

Release baseline

Every page states the release it was written against; examples ran on Linux on 2026-10-22 with CPython 3.14.6 unless they say otherwise.

Tool Version Notes

pip

26.2.2 (2026-10-20)

Requires Python 3.10+; only the latest release is supported.

Poetry

2.5.1 (2026-09-20)

Runs on Python 3.10+; projects may target any Python range.

poetry-core

2.5.0 (2026-09-19)

The PEP 517 backend behind Poetry; PEP 639 since 2.2.0.

poetry-plugin-export / -shell / -bundle

1.10.1 / 1.0.1 / 1.8.0

Plugins since Poetry 2.0.

build

1.6.1 (2026-09-10)

The standard frontend for building sdists and wheels.

twine

7.0.0 (2026-07-27)

Uploads; accepts Core Metadata up to 2.5.

Backends

setuptools 84.2.1, hatchling 1.32.4, flit-core 4.1.0, pdm-backend 2.5.0, uv_build 0.13.5

Compared on Build Backends.

Index tools

pypiserver 2.4.2, devpi-server 6.20.3

The local indexes used for every upload in this section.

CPython

3.14.6 (also 3.13.16 and 3.12.3)

See the Python versions status page.

The running example

Every page uses birdtally, a small original library that tallies bird-survey sightings from a CSV file: a birdtally command, a pretty extra (rich tables), test, lint and docs dependency groups, and a py.typed marker. It exists in two flavours, one managed with pip (hatchling backend, requirements/pylock.toml locks) and one with Poetry (poetry-core, poetry.lock), plus a birdtally-report application that consumes the library from a private index. Nothing is ever uploaded to PyPI or TestPyPI: uploads go to a local pypiserver or devpi.

Reading path

  1. Shared concepts, for both tools: Packaging Concepts & Standards, pyproject.toml, Versions & Dependency Specifiers, Environments & Externally Managed Pythons, Lock Files & Reproducible Installs, Supply-Chain Security, CI Caching & Containers, Choosing & Migrating and the Ecosystem of other tools.

  2. pip, from installing pip to locks, configuration and troubleshooting: pip.

  3. Poetry, from installation to plugins, migration and troubleshooting: Poetry.

  4. Publishing, from preparing a library to Trusted Publishing and after the release: Publishing & Distributing Libraries.

  5. The one-page summary: Cheat Sheet (PDF).

Every source used is listed in the Python Reference bibliography.

References