{"id":319,"library":"hatchling","title":"Hatchling","description":"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.","status":"active","version":"1.29.0","language":"python","source_language":"en","source_url":"https://github.com/pypa/hatch/tree/master/backend","tags":["build","packaging","hatch","python"],"install":[{"cmd":"pip install hatchling","lang":"bash","label":"Install Hatchling"}],"dependencies":[{"reason":"Required for environment management during the build process","package":"virtualenv","optional":false}],"imports":[{"note":"Ensure correct import path to access build hook interfaces.","symbol":"BuildHookInterface","correct":"from hatchling.builders.hooks.plugin.interface import BuildHookInterface"}],"quickstart":{"code":"import os\nfrom hatchling.builders.hooks.plugin.interface import BuildHookInterface\n\nclass CustomBuildHook(BuildHookInterface):\n    def initialize(self, version):\n        pass\n\n    def build(self, version):\n        pass\n\n# Usage\nbuild_hook = CustomBuildHook()\nbuild_hook.initialize('1.0.0')\nbuild_hook.build('1.0.0')","lang":"python","description":"A basic example of implementing a custom build hook using Hatchling's BuildHookInterface."},"warnings":[{"fix":"Upgrade to Python 3.10 or later.","message":"Hatchling v1.28.0 dropped support for Python 3.9.","severity":"breaking","affected_versions":">=1.28.0"},{"fix":"Install 'virtualenv' using 'pip install virtualenv'.","message":"Ensure that 'virtualenv' is installed to manage build environments; otherwise, builds may fail.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"search_vec":"'1.29.0':16 '2026':21 '23':20 '50':32 'approxim':30 'backend':9 'build':8,34 'cadenc':27 'current':13 'day':33 'everi':31 'extens':6 'februari':19 'follow':23 'hatch':12,36 'hatchl':1,2 'modern':5 'packag':35 'python':7,37 'regular':25 'releas':17,26 'updat':29 'use':10 'version':15","created_at":"2026-03-28T08:31:09.651619+00:00","updated_at":"2026-04-16T15:33:00.898052+00:00","problems":[{"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`.","cause":"This error typically occurs when the `hatchling` package is not installed in the active Python environment or the environment is not correctly configured.","error":"ModuleNotFoundError: No module named 'hatchling'"},{"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.","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.","error":"AttributeError: module 'hatchling.build' has no attribute 'prepare_metadata_for_build_editable'"},{"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.","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.","error":"error: metadata-generation-failed"},{"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`.","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.","error":"ValueError: Dependency #1 of field `project.dependencies` cannot be a direct reference"}],"ecosystem":"pypi","meta_description":null,"install_score":100,"quickstart_score":0,"quickstart_tag":"stale","pypi_latest":"1.30.1","cli_name":"hatch","cli_version":"sh: 1: hatch: not found","type":"library","homepage":"https://hatch.pypa.io/latest/","github":"https://github.com/pypa/hatch","docs":null,"changelog":"https://hatch.pypa.io/dev/history/hatchling/","pypi":"https://pypi.org/project/hatchling/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["devops"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-06-28","next_check":"2026-07-28","install_tag":"verified"}}