Hatchling

Common errors

• 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`.

• 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: 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.

• 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

• pip install hatchling Install Hatchling

Imports

• BuildHookInterface

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

  Ensure correct import path to access build hook interfaces.

Quickstart

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