Hatch

Hatch is the official PyPA project manager for Python, combining a PEP 517-compliant build backend (Hatchling), isolated per-project virtual environment management, Python interpreter management, and a single hatch CLI for building, testing, publishing, and versioning packages. It replaces the patchwork of setup.py, tox, twine, and bump2version that most Python projects historically stitched together.

Under the hood, Hatch is built around a pluggable architecture: environments, publish targets, version sources, and project templates are all implemented as ABC-based plugin interfaces discovered through a hook system shared with Hatchling, so third parties can add new backends (uv-based installers, custom publish targets, custom scaffolds) without forking the core. The CLI itself is a monorepo companion to hatchling, the standalone build backend used by thousands of other PyPI packages independent of the Hatch CLI.

What You Get

• A PEP 517-compliant build backend (Hatchling) that produces reproducible wheels and sdists from pyproject.toml alone, no setup.py required
• Named, isolated virtual environments per project with pluggable backends (stdlib venv, uv, or custom plugins)
• A single hatch CLI covering build, test, publish, version, env, and project scaffolding commands
• Managed Python interpreter downloads so environments can target an exact, isolated Python version independent of the system interpreter

Common Use Cases

• Migrating a legacy setuptools/setup.py package to a modern, declarative pyproject.toml-only build
• Running a documented test matrix across multiple Python versions and dependency sets via hatch test
• Publishing releases to PyPI or a custom index without separately configuring twine
• Scaffolding new open-source Python projects with a consistent, best-practice layout via hatch new

Under The Hood

Architecture Hatch is a click-based CLI (hatch.cli) with one subcommand module per command group (build, check, clean, config, dep, env, fmt, new, project, publish, python, run, self, shell, status, test, version), all wired together in hatch.cli.__init__ via a top-level click.group that shares a stateful Application object (hatch/cli/application.py). Application lazily resolves Project, ConfigFile, data_dir/cache_dir, and a Platform wrapper, and centralizes execution primitives like ExecutionContext and terminal output. Cross-cutting extension points (environment provisioning, publishing, version sourcing, project templates) are implemented as ABC-based plugin interfaces, such as EnvironmentInterface in hatch/env/plugin/interface.py, discovered through a hatchling.plugin hook system, so hatch.project.core.Project composes a plugin manager rather than hardcoding environment or publish backends. Every CLI subcommand depends on Application.project and Application.get_environment(), so the core Project/Application abstraction is load-bearing across the whole tool.

Tech Stack Hatch targets Python 3.10+ and is built on click for the CLI framework, packaging for version and specifier parsing, uv vendored as a fast installer/resolver backend, virtualenv plus python-discovery for interpreter and environment management, tomlkit/tomli-w for TOML read/write, keyring for credential storage during publish, rich for terminal output, and pexpect/shellingham/userpath for shell integration. The build backend itself is hatchling, developed in the same monorepo under a separate backend/ directory and consumed as its own standalone PyPI package by projects that don’t use the Hatch CLI at all; version bumping is handled via the companion hatch-vcs plugin, deriving versions from git tags.

Code Quality The test suite mirrors the source layout one-to-one (tests under cli/, env, project, publish, python, and backend, invoking the CLI through a hatch pytest fixture), and is run through ruff in preview mode with a shared ruff_defaults.toml, plus mypy with disallow_untyped_defs enforced strictly on the hatchling and hatch.utils modules and relaxed elsewhere, alongside a separate pyrefly.toml static-analysis configuration. The package ships a py.typed marker for downstream type checkers, and CI runs dedicated workflows for the test suite and for building both the hatch and hatchling distributions independently. Application uses explicit self.abort() calls with defined exit codes rather than swallowing exceptions.

API Design A single hatch entrypoint exposes consistent, well-documented subcommands (hatch build, hatch env, hatch run, hatch version, hatch new, hatch publish), with every CLI option paired with a matching environment variable documented directly in --help output. A default single-environment project needs no configuration at all; hatch.toml or a [tool.hatch] table in pyproject.toml is opt-in for anything beyond the defaults. The plugin-extension surface for environments, publish targets, version sources, and templates is documented with runnable plugin.py/hooks.py examples directly in the interface docstrings, and is backed by a full MkDocs Material documentation site with separate tutorials, how-to guides, and reference sections.