# 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 runs tests across Python versions and dependency sets without [tox](https://pydevtools.com/handbook/reference/tox.md) or [nox](https://pydevtools.com/handbook/reference/nox.md). PyPA governance backs the project.

> [!NOTE]
> [uv](https://pydevtools.com/handbook/reference/uv.md) covers much of the same ground (project management, environment creation, script running) and resolves faster. Hatch differentiates through its environment matrix, PEP 751 lockfiles, and PyPA backing, and can use uv as its installer to close the speed gap. 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.

## Key Features

- 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
- Dependency Sources: Redirects dependencies to local paths, Git repos, alternate indexes, or workspace members at install time without altering published metadata
- 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 lockfiles for environments configured with locked = true
hatch env lock

# Sync a locked environment from its lockfile (requires the uv locker)
hatch dep sync

# Report what each dependency source redirects to
hatch dep show sources

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

# 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 writes the same `[build-system]` table shown in Configuration.

Hatchling supports build hooks, custom metadata, and version source plugins (e.g. reading the version from a VCS tag). See [how uv_build and Hatchling compare](https://pydevtools.com/handbook/explanation/what-is-the-uv-build-backend.md).

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

## Environment Matrix

The environment matrix expands a single environment definition across multiple Python versions or dependency sets:

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

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

This defines `test.py3.10`, `test.py3.11`, and `test.py3.12`. Running `hatch run test:pytest` executes the suite in each.

## Lockfile Generation

Hatch generates [PEP 751](https://pydevtools.com/handbook/explanation/what-is-pep-751.md) compliant lockfiles in `pylock.toml` format for environments configured with `locked = true`. The locker interface is pluggable with built-in uv and pip implementations:

```bash
# Lock all environments configured with locked = true
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 sync a locked environment from a lockfile, use the uv locker and run `hatch dep sync`. The pip locker generates lockfiles but cannot apply them, so `hatch dep sync` fails with a `LockerUnsupportedError` under pip.

## Dependency Sources

The `sources` table redirects a dependency to an alternative origin at install time without altering published metadata. This covers development against a local checkout, a fork, or a private index:

```toml
[tool.hatch.sources]
# Shorthand string: editable install from a local checkout
my-lib = "./packages/my-lib"

# Track a Git branch (rev and tag are also accepted)
upstream-fork = { git = "https://github.com/example/my-lib", branch = "main" }

# Resolve from a specific index, passed to the installer as --extra-index-url
some-package = { index = "https://private.example.com/simple" }
```

Five source types are available: `path`, `git`, `url`, `index`, and `workspace`. A bare string is shorthand for `{ path = "...", editable = true }`; set `editable = false` for a non-editable install.

`[tool.hatch.sources]` is an alias for the default environment. Named environments inherit sources entry by entry and can override individual redirects; detached environments inherit none. Setting `HATCH_NO_SOURCES` to any non-empty value disables every source, which confirms published metadata resolves on its own:

```bash
HATCH_NO_SOURCES=1 hatch env create
```

## Code Checking

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

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

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

# Check formatting (uses Ruff by default)
hatch check fmt

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

# Generate a type coverage report
hatch check types --cover
```

## Pros

- 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 on an environment:

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

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.

## Cons

- 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)
