Hatchling

1.29.0 verified Tue May 12 auth: no python install: verified quickstart: stale

Hatchling is a modern, extensible Python build backend used by Hatch, currently at version 1.29.0, released on February 23, 2026. It follows a regular release cadence, with updates approximately every 50 days.

pip install hatchling

Common errors

error ModuleNotFoundError: No module named 'hatchling' ↓

cause This error typically occurs when the `hatchling` package is not installed in the active Python environment or the environment is not correctly configured.

fix

Ensure hatchling is installed in your current virtual environment by running: pip install hatchling. If using Hatch, ensure it's installed and the environment is activated, or try hatch env prune followed by hatch env restore.

error AttributeError: module 'hatchling.build' has no attribute 'prepare_metadata_for_build_editable' ↓

cause This error usually indicates an incompatibility or version mismatch between `hatchling` and the build frontend (like `pip` doing an editable install) or other build tools, often due to changes in `hatchling`'s internal API for editable builds.

fix

Upgrade hatchling to its latest version (pip install --upgrade hatchling) and ensure your build tools (e.g., pip) are also up-to-date. If the issue persists, review hatchling's release notes for breaking changes related to editable installs and adjust your pyproject.toml or workflow accordingly.

error error: metadata-generation-failed ↓

cause This is a general error indicating that `hatchling` could not properly generate the package metadata, often due to misconfigurations in `pyproject.toml`, missing files (like `__init__.py` in a package), incorrect file encoding (e.g., UTF-16 readme), or issues with build hooks.

fix

Check your pyproject.toml for syntax errors, ensure all declared files (e.g., readme) exist and are UTF-8 encoded, verify that Python packages have an __init__.py file, and inspect any custom build hooks for errors. The full traceback accompanying this error message will provide more specific details.

error ValueError: Dependency #1 of field `project.dependencies` cannot be a direct reference ↓

cause This error occurs when you use direct references (e.g., `package @ url`) in your `project.dependencies` field within `pyproject.toml` without explicitly allowing them in `hatchling`'s configuration.

fix

To allow direct references in your dependencies, add the following to your pyproject.toml under the [tool.hatch.metadata] section: allow-direct-references = true.

Warnings

breaking Hatchling v1.28.0 dropped support for Python 3.9. ↓

fix Upgrade to Python 3.10 or later.

gotcha Ensure that 'virtualenv' is installed to manage build environments; otherwise, builds may fail. ↓

fix Install 'virtualenv' using 'pip install virtualenv'.

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) - - 0.08s 20.2M

3.10 slim (glibc) - - 0.06s 21M

3.11 alpine (musl) - - 0.13s 22.2M

3.11 slim (glibc) - - 0.11s 23M

3.12 alpine (musl) - - 0.12s 14.1M

3.12 slim (glibc) - - 0.12s 15M

3.13 alpine (musl) - - 0.10s 13.7M

3.13 slim (glibc) - - 0.10s 14M

3.9 alpine (musl) - - 0.08s 19.7M

3.9 slim (glibc) - - 0.07s 20M

Imports

BuildHookInterface
```
from hatchling.builders.hooks.plugin.interface import BuildHookInterface
```
Ensure correct import path to access build hook interfaces.

Quickstart stale last tested: 2026-04-23

A basic example of implementing a custom build hook using Hatchling's BuildHookInterface.

import os
from hatchling.builders.hooks.plugin.interface import BuildHookInterface

class CustomBuildHook(BuildHookInterface):
    def initialize(self, version):
        pass

    def build(self, version):
        pass

# Usage
build_hook = CustomBuildHook()
build_hook.initialize('1.0.0')
build_hook.build('1.0.0')