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

For raw speed and lockfile support, consider uv. See Which Python package manager should I use? for a broader comparison.

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

# 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 generates a pyproject.toml with hatchling as the build backend:

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

See the Hatchling documentation 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:

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

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:

[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 for more options, including enabling uv globally.

Limitations

• More complex than single-purpose tools, with a steeper learning curve
• No built-in lockfile generation

Learn More

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