Hatch

Hatch is a modern, extensible Python project manager designed to handle the full lifecycle of a Python project. Its core capabilities include:

• Build system: Provides reproducible builds using a plugin ecosystem.
• Environments: Robust management of project environments, supporting custom scripts and uv integration.
• Python management: Allows for manual Python installations or automatic management within environments.
• Testing: Executes tests following industry best practices.
• Static analysis: Integrated static analysis powered by Ruff with sane defaults.
• Script runner: Executes Python scripts within specific environments (defined by dependencies and Python versions).
• Publishing: Streamlined workflow for uploading packages to PyPI or other indices.
• Versioning: Automated workflows for bumping project versions.
• Project generation: Creates new projects from templates.
• CLI: A high-performance command-line interface designed for speed.

The overrides table allows you to modify environment options based on specific conditions. Use dotted key syntax: [tool.hatch.envs.<ENV_NAME>.overrides]<SOURCE>.<CONDITION>.<OPTION> = <VALUE>.

Supported Sources:

• platform: Based on linux, windows, or macos.
• env: Based on the presence or value of environment variables.
• matrix: Based on matrix variable values.
• name: Based on regular expression matching of the generated environment name.

Override Application Order:

1. platform
2. env
3. matrix
4. name

Overwriting vs. Supplementing:

• To supplement (append to arrays or add to mappings), use the standard syntax.
• To overwrite an entire option (e.g., replacing all platforms instead of adding one), prefix the name with set- (e.g., matrix.foo.set-platforms = ["macos"]).

Conditional Modifiers (Inline Tables): You can use inline tables to apply overrides only if certain conditions are met:

• if: An array of allowed values for a condition.
• platform: An array of required platforms.
• env: An array of required environment variables (e.g., env = ["FOO", "BAR=BAZ"]).

[tool.hatch.envs.test.overrides]
platform.windows.scripts = [
  'run=pytest -m "not io_uring"',
]

Hatchling is the build backend for Hatch and offers several advantages over setuptools for standard Python projects:

• Better Defaults: Hatchling uses your version control system (e.g., .gitignore) to determine file inclusion/exclusion for source distributions. For wheels, it uses specific heuristics based on the project name rather than attempting to include every directory that looks like a package.
• Simplified Configuration: All build configuration is handled in a single file using Git-style glob patterns. Unlike setuptools, which may require a separate MANIFEST.in file and complex shell-style globs, Hatchling uses dedicated sections like [tool.hatch.build.targets.wheel].
• Improved Editable Installs: Hatchling's default editable installation behavior supports proper static analysis by IDEs (like Visual Studio Code) without additional configuration.
• Reproducibility: Hatchling builds reproducible wheels and source distributions by default.
• Extensibility: Hatchling uses a plugin system with discrete, well-defined types, making it easier to extend than the low-level setuptools API.

When to avoid Hatchling: If your project requires building C/C++ extension modules, continue using setuptools or a backend specialized in compiler interfacing.

The mode key in config.toml determines how Hatch identifies the project to work on. There are three modes:

1. local (Default): Hatch looks for a pyproject.toml file in the current working directory and any parent directories. The first one found defines the project root.
2. project: Hatch works only on a specific project defined in the configuration. Projects can be defined in the [projects] table via a path string or an inline table with a location key. Alternatively, you can list base directories in [dirs].project, and Hatch will treat any matching subdirectory as a project root.
3. aware: A hybrid mode that attempts local mode first and falls back to project mode if no local project is found.

You can override the project selection for a single command using the -p/--project flag or the HATCH_PROJECT environment variable.

# Example Project Mode configuration
mode = "project"
project = "proj1"

[projects]
proj1 = "/path/to/project1"
proj2 = { location = "/path/to/project2" }

[dirs]
project = ["/path/to/monorepo1", "/path/to/monorepo2"]