Hatch Project Management

1.16.5 · active · verified Sun Apr 05

Hatch is a modern, extensible Python project manager that centralizes environment management, packaging with Hatchling, versioning, and publishing behind a single command-line interface. It is known for its ability to seamlessly manage multiple environments, handle dependencies, and dynamically download required Python distributions. Currently at version 1.16.5, Hatch maintains an active development and release cadence.

Warnings

breaking Hatch v1.16.0 dropped official support for Python 3.9. Projects requiring Python 3.9 or older must use an earlier version of Hatch.
Fix: Upgrade your project's Python version to 3.10 or newer, or pin Hatch to a version <1.16.0 (e.g., `hatch<1.16.0`).
breaking Hatch v1.15.0 dropped official support for Python 3.8. Projects requiring Python 3.8 or older must use an earlier version of Hatch.
Fix: Upgrade your project's Python version to 3.9 or newer, or pin Hatch to a version <1.15.0 (e.g., `hatch<1.15.0`).
breaking In Hatch v1.16.0, several environment type plugin methods were removed (`build_environment`, `build_environment_exists`, `run_builder`, `construct_build_command`). Custom environment plugins might need updates.
Fix: Refer to the Hatch v1.16.0 release notes and documentation for updated environment plugin API. All environments can now be used for building.
gotcha Hatch v1.16.5 fixed a breaking change in `virtualenv` by explicitly supporting only the latest version and adding `python-discovery` as a dependency. Older Hatch versions might encounter issues with newer `virtualenv`.
Fix: Upgrade Hatch to v1.16.5 or newer to ensure compatibility with `virtualenv`.
gotcha Prior to v1.16.3, there were known issues with self-referential dependencies not being recognized and incomplete environments being created when exceptions occurred during environment setup.
Fix: Upgrade Hatch to v1.16.3 or newer to resolve issues with dependency recognition and environment creation stability.

Install

pip install hatch Standard installation
pipx install hatch Recommended for CLI tools

Quickstart

Hatch is primarily a CLI tool. This quickstart demonstrates creating a new project and running a simple command within its managed environment. The `hatch new` command scaffolds a new project with a `pyproject.toml` file, and `hatch run` executes commands within the project's isolated environment.

# Create a new Python project
hatch new "My Awesome Project"

# Navigate into the project directory
cd "my-awesome-project"

# Run a script (e.g., 'python -m my_awesome_project')
# This assumes a default `run` script is defined in pyproject.toml
hatch run python -c "print('Hello from Hatch!')"

# Or enter a shell environment
# hatch shell

view raw JSON →