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 or nox. PyPA governance backs the project.

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 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 with hatchling as the build backend:

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

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

Command Examples

# 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, distributed as a separate package. It can be used independently of the hatch CLI in any Python project, including uv projects:

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). It was the default backend for uv init before uv switched to uv_build.

See the Hatchling documentation for configuration options.

Environment Matrix

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

[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 compliant lockfiles in pylock.toml format for environments configured with locked = true. The locker interface is pluggable with built-in uv and pip implementations:

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

[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:

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:

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

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

See How to use uv to speed up Hatch 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)

Learn More

• Hatch Documentation
• GitHub Repository
• Example Hatch Package
• pyproject.toml — the configuration file hatch uses
• setuptools — the traditional build backend for comparison