{"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,"last_verified":"2026-05-12T13:02:36.330Z","next_check":"2026-06-26T00:00:00.000Z","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,"install_tag":"verified","quickstart_score":0,"quickstart_tag":"stale","pypi_latest":null,"install_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.08,"mem_mb":2.8,"disk_size":"20.2M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.06,"mem_mb":2.8,"disk_size":"21M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.13,"mem_mb":3.2,"disk_size":"22.2M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.11,"mem_mb":3.2,"disk_size":"23M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.12,"mem_mb":3.1,"disk_size":"14.1M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.12,"mem_mb":3.1,"disk_size":"15M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.1,"mem_mb":3,"disk_size":"13.7M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.1,"mem_mb":2.8,"disk_size":"14M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.08,"mem_mb":2.9,"disk_size":"19.7M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.07,"mem_mb":2.9,"disk_size":"20M"}]},"quickstart_checks":{"last_tested":"2026-04-23","tag":"stale","tag_description":"widespread failures or data too old to trust","results":[{"runtime":"python:3.10-alpine","exit_code":1},{"runtime":"python:3.10-slim","exit_code":1},{"runtime":"python:3.11-alpine","exit_code":1},{"runtime":"python:3.11-slim","exit_code":1},{"runtime":"python:3.12-alpine","exit_code":1},{"runtime":"python:3.12-slim","exit_code":1},{"runtime":"python:3.13-alpine","exit_code":1},{"runtime":"python:3.13-slim","exit_code":1},{"runtime":"python:3.9-alpine","exit_code":1},{"runtime":"python:3.9-slim","exit_code":1}]}}