# Hatch — Modern Python Project Manager and Build Tool

> A standards-compliant Python project manager that handles environment management, dependency resolution, building, and publishing. Maintained by the Python Packaging Authority (PyPA) as the recommended modern workflow tool.

## Install

Save in your project root:

# Hatch — Modern Python Project Manager and Build Tool

## Quick Use
```bash
pip install hatch
```
```bash
hatch new my-project        # scaffold a new project
cd my-project
hatch env create             # create a virtual environment
hatch run test               # run tests in the managed environment
hatch build                  # build sdist and wheel
hatch publish                # publish to PyPI
```

## 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/

---
Source: https://tokrepo.com/en/workflows/asset-0f597aab
Author: AI Open Source