hatch

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

Core Functionality

• Project Creation: Scaffolds new Python projects with standardized structure
• Environment Management: Creates and controls isolated virtual environments
• Build Backend: Provides a compliant PEP 517 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

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

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