# Hatch: Python Project Manager

hatch is a Python project management tool maintained by the Python Packaging Authority (PyPA). It handles virtual environment management, dependency resolution, project scaffolding, and publishing through a unified interface that follows Python packaging standards. Its build backend, hatchling, is one of the most widely used on PyPI.

## When to Use Hatch

Hatch suits library authors who want a single, standards-compliant tool covering scaffolding, building, publishing, and multi-version testing. Its environment matrix system runs tests across Python versions and dependency sets without a separate tool like [tox](https://pydevtools.com/handbook/reference/tox.md) or [nox](https://pydevtools.com/handbook/reference/nox.md). PyPA governance backs the project.

For raw speed, consider [uv](https://pydevtools.com/handbook/reference/uv.md). See [Which Python package manager should I use?](https://pydevtools.com/handbook/explanation/which-python-package-manager-should-i-use.md) for a broader comparison.

> [!NOTE]
> [uv](https://pydevtools.com/handbook/reference/uv.md) covers much of the same ground (project management, environment creation, script running) with faster performance. Hatch differentiates through its environment matrix system, PEP 751 lockfile support, and official PyPA backing. Hatch can also use uv as its installer backend, gaining the same installation speed without switching tools.

## Core Functionality

- Project Creation: Scaffolds new Python projects with standardized structure
- Environment Management: Creates and controls isolated virtual environments
- Build Backend: Provides a PEP 517-compliant build backend (hatchling)
- Lockfile Generation: Produces [PEP 751](https://pydevtools.com/handbook/explanation/what-is-pep-751.md) compliant `pylock.toml` files with pluggable locker backends
- Code Checking: Lints, formats, and type-checks code via the `hatch check` command group
- Version Management: Handles version bumping and release tracking
- Script Execution: Runs commands in project environments

## Configuration

Hatch projects use [pyproject.toml](https://pydevtools.com/handbook/reference/pyproject.toml.md) with hatchling as the build backend:

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

[project]
name = "my-package"
version = "0.1.0"
dependencies = ["requests"]
```

## Command Examples

```bash
# Create a new project
hatch new my-project

# Run a command in project environment
hatch run pytest

# Generate a PEP 751 lockfile for the default environment
hatch env lock

# Sync dependencies from a lockfile
hatch dep sync

# Lint and format code
hatch check lint
hatch check lint --fix

# Type-check code
hatch check types

# Build distribution packages
hatch build

# Publish to PyPI
hatch publish

# Create a specific environment
hatch env create docs
```

## Hatchling build backend

Hatchling is Hatch's [build backend](https://pydevtools.com/handbook/explanation/what-is-a-build-backend.md), distributed as a separate package. It can be used independently of the `hatch` CLI in any Python project, including [uv](https://pydevtools.com/handbook/reference/uv.md) projects:

```bash
uv init --build-backend hatch my-lib
```

This generates a `pyproject.toml` with hatchling as the build backend:

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

Hatchling supports build hooks, custom metadata, and version source plugins (e.g. reading the version from a VCS tag). It was the default backend for `uv init` before [uv switched to `uv_build`](https://pydevtools.com/handbook/explanation/why-does-uv-use-hatch-as-a-backend.md).

See the [Hatchling documentation](https://hatch.pypa.io/latest/config/build/) for configuration options.

## Environment Matrix

Hatch's environment matrix system is its primary differentiator. It allows defining a single environment that expands across multiple Python versions or dependency sets. For example, to run tests across several Python versions:

```toml
[tool.hatch.envs.test]
dependencies = ["pytest"]

[[tool.hatch.envs.test.matrix]]
python = ["3.10", "3.11", "3.12"]
```

Running `hatch run test:pytest` then executes the test suite in each Python version defined in the matrix. This provides tox-like multi-version testing without a separate tool.

## Lockfile Generation

Since v1.17.0, Hatch generates [PEP 751](https://pydevtools.com/handbook/explanation/what-is-pep-751.md) compliant lockfiles in `pylock.toml` format. The locker interface is pluggable with built-in uv and pip implementations:

```bash
# Lock the default environment
hatch env lock

# Lock a named environment
hatch env lock test

# Shortcut: lock the active environment's dependencies
hatch dep lock
```

Hatch auto-creates environments when locking if they do not already exist. To install from a lockfile, use `hatch dep sync`.

## Code Checking

The `hatch check` command group (v1.17.0) replaces the deprecated `hatch fmt` command. It provides linting, formatting, and type checking:

```bash
# Lint code (uses Ruff by default)
hatch check lint

# Auto-fix lint violations
hatch check lint --fix

# Type-check code (uses Pyrefly)
hatch check types

# Summarize type coverage
hatch check types --cover
```

## Advantages

- Full support for modern Python packaging standards (PEP 517, PEP 621)
- Handles the complete project lifecycle from scaffolding to publishing
- Environment matrix system enables multi-version testing without extra tools
- Plugin system allows extending functionality for custom workflows

## Using uv as the installer

Hatch can use uv for dependency installation instead of pip/virtualenv. Set the `installer` option in your environment configuration:

```toml
[tool.hatch.envs.default]
installer = "uv"
```

This gives Hatch the same fast resolution and installation that uv provides, without changing the rest of your Hatch workflow. See [How to use uv to speed up Hatch](https://pydevtools.com/handbook/how-to/how-to-use-uv-to-speed-up-hatch.md) for more options, including enabling uv globally.

## Limitations

- More complex than single-purpose tools, with a steeper learning curve
- Slower than uv for dependency resolution and installation (mitigated by using uv as the installer backend)

## Learn More

- [Hatch Documentation](https://hatch.pypa.io/latest/)
- [GitHub Repository](https://github.com/pypa/hatch)
- [Example Hatch Package](https://github.com/python-developer-tooling-handbook/demo-hatch)
- [pyproject.toml](https://pydevtools.com/handbook/reference/pyproject.toml.md) — the configuration file hatch uses
- [setuptools](https://pydevtools.com/handbook/reference/setuptools.md) — the traditional build backend for comparison