pypa/hatch: a Python project manager that splits the CLI from the build backend

What Hatch does that a plain build backend does not

Hatchling is the build backend. Hatch is the command line tool that wraps it, and the wrapper is where the project spends most of its scope. The README lists environment management with custom scripts and UV, Python distribution management, test execution, static analysis, a script runner, publishing to PyPI or other indices, version management and project generation. That is a wide surface for a tool whose name most people first meet as a build-system requirement.

The intended audience is a maintainer who wants one configuration file to cover the whole loop from creating a project to pushing a release. The cost of that breadth is that Hatch is not a thin layer. Its dependency list in pyproject.toml includes click, hatchling, httpx2, hyperlink, keyring, packaging, pexpect, python-discovery, platformdirs, pyproject-hooks, rich, shellingham, tomli-w, tomlkit, userpath, uv, virtualenv and backports.zstd on interpreters older than 3.14. Several of those exist only for one feature each, and you carry all of them whether or not you use publishing or script running.

The README also points at a Why Hatch? page rather than arguing the case inline, which is worth reading before you commit, because the feature list alone does not explain the design decisions behind environment handling or versioning.

The CLI and Hatchling are separate installs with separate version numbers

The release feed shows two products moving on their own schedules. Hatchling v1.32.4 and v1.32.3 landed on 2026-09-20 and 2026-09-17, while Hatch v1.18.1 landed on 2026-09-16. If you are debugging a build failure, the first question is which of the two is producing it, and the answer is not always obvious from the error text.

Hatch's own pyproject.toml declares the relationship explicitly. The build-system table requires hatchling>=1.27 alongside hatch-vcs>=0.3.0, and hatchling>=1.27.0 appears again in the runtime dependencies. So installing Hatch pulls a Hatchling that satisfies that floor, but a project can pin a newer Hatchling in its own build-system table without touching the Hatch CLI. That is the normal arrangement for build backends, and it means a Hatch upgrade and a Hatchling upgrade are two different decisions.

The repository layout reflects the same split. There is a top-level backend/ directory next to src/, docs/, tests/ and release/, and the configuration files at the root cover the tool itself: hatch.toml, pyproject.toml, ruff.toml, ruff_defaults.toml, pyrefly.toml and mkdocs.yml. Nothing in the README explains how the two version lines are meant to be kept in step, which is the kind of gap you notice only when a plugin starts failing after a backend bump.

Installing Hatch and running a first environment command

Hatch is published on PyPI as the hatch package, and its own metadata requires Python 3.10 or newer. The README does not reproduce installation steps, so the package index entry is the place to start. A typical install into an isolated tool environment looks like this:

pipx install hatch

After that, hatch --version should print the installed CLI version. If you prefer pip, the same package installs with pip install hatch, at the cost of sharing an environment with the rest of your packages.

Once the CLI is on your path, the project configuration lives in pyproject.toml under a tool.hatch table. The README links to a build system configuration page rather than showing a complete example, so treat the snippet below as the shape of the file and check the referenced page for the full set of keys:

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[project]
name = "example-project"
version = "0.1.0"

With that in place, hatch build produces a distribution using Hatchling. The README documents publishing to PyPI or other indices under its own page, and environment management, test execution and static analysis each have separate configuration sections. The CLI reference at hatch.pypa.io/latest/cli/about/ is where the exact subcommands live; the README itself does not enumerate them.

Where Hatch is the wrong tool

If you only need to build a wheel and an sdist, Hatchling is already the answer, and it is available without the CLI. Pulling in Hatch for that job adds click, rich, keyring, virtualenv, uv and the rest of the dependency list for features you will not call. The build-system table in Hatch's own pyproject.toml shows the minimal form: hatchling plus a backend declaration is enough to produce distributions.

The second case is a team that has settled on a different environment tool. Hatch's environment management is one of its selling points, but it is also the part most likely to overlap with what you already run. The dependencies include both virtualenv>=21 and uv>=0.5.23, which suggests Hatch is orchestrating rather than replacing them. If your workflow is already built around one of those directly, Hatch adds a configuration layer between you and it.

The third case is version pinning across a large monorepo. The README lists version management as a feature and the build-system table references hatch-vcs, but it does not describe how version resolution behaves when many packages share a repository, and the documentation pages linked from the README are where that would have to be confirmed. Do not assume the behaviour from the feature name.

How Hatch compares with Poetry and PDM

Poetry and PDM both pair a dependency resolver with a build backend, and both keep the whole workflow inside one tool. Hatch takes a different route: the backend, Hatchling, is usable on its own and is listed as a separate package with its own release cadence, while the CLI layers environment, script, test and publishing commands on top. The practical difference is that a Hatch project's build can be reproduced with Hatchling alone in a CI job that never installs the CLI.

PDM's distinguishing feature is PEP 582 support, which Hatch does not claim in its README. Poetry's is a lockfile-driven install model, and the README's dependency list mentions neither a lockfile nor a resolver, so treat dependency resolution as outside what the README describes. Hatch's own claim is narrower and more concrete: a standardized build system with reproducible builds by default, environment management with custom scripts and UV support, and a CLI the README says is roughly 2-3x faster than equivalent tools, with a link to the CI workflow that produces that comparison.

That performance claim is the project's own, backed by a benchmark workflow rather than an independent measurement. If CLI latency matters to you, run the comparison yourself against the tools you actually use; the linked workflow shows how the project measures it.

Maintenance, licence and what an upgrade costs

The repository is not archived, and the last push was on 2026-09-20. Releases are frequent: Hatchling shipped twice in the four days before that, and the Hatch CLI shipped on 2026-09-16. The classifiers in pyproject.toml declare Development Status 5 - Production/Stable and support for CPython 3.10 through 3.14 plus PyPy.

Hatch is distributed under the MIT licence, and the project metadata declares license = "MIT" with license-files = ["LICENSE.txt"]. MIT is permissive, so redistribution and modification are permitted provided the licence text travels with the code. That is a description of what the repository states, not legal advice; if you are bundling Hatch into a product, read LICENSE.txt yourself.

The upgrade cost is concentrated in the two version lines. Hatchling has a floor in Hatch's dependencies, so a Hatch upgrade can move the backend underneath you, and a project that pins an older Hatchling in its build-system table will not follow that move. Plugins are the other exposure: the README advertises extensibility and the topic list includes plugin, but it does not document a compatibility policy for third-party plugins across Hatchling releases. The SECURITY.md file at the repository root is where the project states how it handles vulnerability reports.

Editorial conclusion

Adopt Hatch if you want one CLI covering environments, versioning, builds and publishing, and you are willing to read the configuration reference rather than guess at defaults. Skip it if you only need a build backend, since Hatchling already ships as a standalone package, or if you depend on a plugin whose compatibility with the current release you have not checked. Before committing, verify three things: that your interpreter is Python 3.10 or newer, that hatchling>=1.27.0 satisfies your build-system requirement, and that the commands you plan to run appear in the CLI reference at hatch.pypa.io. The split between the CLI and the backend is the part to test first, because a project can build correctly under Hatchling while the Hatch environment commands behave differently.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. pypa/hatch on GitHub
4. README
5. Releases