Hatch — Modern Python Project Manager and Build Tool

Introduction

Hatch is a modern Python project manager maintained by the Python Packaging Authority (PyPA). It covers the entire development lifecycle: project scaffolding, environment management, dependency resolution, testing, building, and publishing. Hatch uses pyproject.toml as its single configuration file and follows all current Python packaging standards (PEP 517, PEP 621, PEP 660). It replaces the need for separate tools like virtualenv, setuptools, twine, and tox.

What Hatch Does

• Scaffolds new Python projects with best-practice directory layouts and pyproject.toml configuration
• Manages multiple isolated environments per project for testing, linting, and documentation
• Builds source distributions and wheel packages using the Hatchling build backend
• Publishes packages to PyPI or private registries with built-in authentication
• Runs scripts and commands in managed environments with dependency isolation

Architecture Overview

Hatch consists of a CLI frontend and the Hatchling build backend. The CLI manages environments using a plugin system that supports virtualenv, conda, and container-based backends. Hatchling reads pyproject.toml for build configuration and produces standards-compliant packages. Environment definitions in pyproject.toml specify dependencies, scripts, and matrix variables for running commands across multiple Python versions or configurations.

Self-Hosting & Configuration

• Install via pip: pip install hatch or pipx: pipx install hatch
• All configuration lives in pyproject.toml under [tool.hatch] sections
• Define environments with custom dependencies and scripts under [tool.hatch.envs]
• Configure the build backend with [build-system] pointing to hatchling
• Global settings (default Python, cache directory) go in ~/.config/hatch/config.toml

Key Features

• Environment management with automatic creation, caching, and matrix support across Python versions
• Hatchling build backend with include/exclude patterns, version management, and custom build hooks
• Version bumping with hatch version following semver or custom schemes
• Script definitions in pyproject.toml: hatch run lint:check runs commands in the lint environment
• Plugin architecture for custom environment types, build hooks, and version sources

Comparison with Similar Tools

• Poetry — Focuses on dependency locking and virtual environments; Hatch provides broader lifecycle management and follows newer PEP standards
• PDM — Standards-compliant with PEP 582 support; Hatch has environment matrices and a built-in build backend
• uv — Ultra-fast package installer and resolver; Hatch is a higher-level project manager that can use uv as its environment backend
• Flit — Minimal build tool for pure Python packages; Hatch adds environment management, scripting, and multi-version testing
• setuptools — The legacy standard; Hatch offers a modern experience with fewer config files and better defaults

FAQ

Q: How does Hatch differ from Poetry? A: Hatch follows PEP 621 for metadata in pyproject.toml, supports environment matrices for multi-version testing, and includes a dedicated build backend (Hatchling). Poetry uses a custom metadata format and focuses on lock-file-based dependency management.

Q: Can I use Hatch with an existing setuptools project? A: Yes. You can migrate incrementally by converting setup.cfg/setup.py to pyproject.toml. Hatch provides a migration guide and the Hatchling backend is a drop-in replacement for setuptools.

Q: Does Hatch support monorepos? A: Hatch can manage multiple packages in a monorepo using workspace-aware environment configurations. Each package has its own pyproject.toml with shared or isolated environments.

Q: Is Hatch officially recommended by PyPA? A: Yes. Hatch is a PyPA project and is listed as a recommended tool on packaging.python.org for modern Python project management.

Sources

• https://github.com/pypa/hatch
• https://hatch.pypa.io/