hatchling

Hatchling is refreshingly straightforward once you understand it's a build backend, not a project manager like Poetry. The transition from setuptools was smooth - I appreciated that basic configurations in pyproject.toml are intuitive with sensible defaults. Dynamic versioning from git tags worked out of the box, and including/excluding files via path patterns felt more modern than MANIFEST.in.

Error messages are generally clear when you misconfigure something in pyproject.toml, though some plugin-related errors could be more specific about what went wrong. The official documentation covers common scenarios well, with practical examples for version strings, entry points, and package data. I found myself rarely needing to consult Stack Overflow.

Debugging build issues can be tricky since it operates at the build layer - sometimes you need to clear .egg-info directories and rebuild from scratch. The plugin system is powerful but documentation for writing custom plugins is sparse. For 95% of standard Python packages, though, you won't need anything beyond the built-in features.

Hatchling has become my go-to build backend for new Python projects. The learning curve is remarkably gentle - you can get started with just a few lines in pyproject.toml, and the sensible defaults mean you rarely need complex configuration. The documentation is clear and well-organized, with practical examples that cover most common scenarios like adding data files, configuring dynamic versioning, or excluding test directories.

Error messages are generally helpful, pointing you to the specific configuration issue rather than cryptic build failures. When I accidentally misconfigured a file inclusion pattern, the error clearly identified the problematic section. The plugin system for custom build hooks is straightforward if you need advanced features, though the API documentation could be more detailed for edge cases.

Day-to-day usage is smooth once configured. Issues on GitHub get addressed reasonably quickly, and the maintainers are responsive. Stack Overflow coverage is growing but still limited - you'll often need to check GitHub issues or the official docs. The integration with modern Python packaging standards (PEP 517/660) means it plays well with pip, build, and other tools without surprises.

Hatchling excels as a build backend for Python packages when you need predictable, fast builds without complex requirements. It's notably lighter weight than setuptools, with significantly faster wheel generation in CI pipelines - I've seen 30-40% build time reductions on medium-sized projects. The pyproject.toml configuration is straightforward and well-documented, with sensible defaults that rarely need tweaking.

The plugin system for version management and file inclusion works reliably, though the error messages when paths are misconfigured can be cryptic. Build reproducibility is excellent - same inputs consistently produce identical outputs, which is critical for supply chain integrity. Resource usage is minimal; it doesn't hold file handles or spawn excessive subprocesses.

One limitation: if you need complex build steps (C extensions, asset compilation), you'll need custom hooks or alternative backends. The plugin API is functional but not extensively documented beyond basic examples. Breaking changes between 1.x versions have been minimal, mostly additive features, which makes version pinning less critical than with other build tools.