# Hatchling

> Provides Hatchling build backend guidance for Python packaging — use when configuring pyproject.toml metadata, build targets (wheel, sdist, binary), file selection with git-style globs, build hooks, metadata hooks, version management (code/regex/env sources), editable installs, the hatch-vcs plugin, plugin development, build environment setup (UV/pip/Cython), setuptools migration, or troubleshooting Hatchling errors. Covers PEP 517/518/621/660 standards and context variable interpolation.

- Skill: `jamie-bitflight/hatchling` (Agent Skill, multi-file: 182 files)
- Install (CLI): `npx skillmds@latest add jamie-bitflight/hatchling`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jamie-bitflight/hatchling/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: Jamie-BitFlight (https://skillmd.com/u/jamie-bitflight)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/jamie-bitflight/hatchling

---


# Hatchling

## Overview

Hatchling is a modern, standards-compliant Python build backend that replaces legacy setuptools for package building. It provides clear configuration through `pyproject.toml`, intelligent defaults, and extensibility through hooks and plugins. This skill enables understanding Hatchling's architecture, configuration options, and build customization capabilities.

## Key Capabilities

Load and follow the standards in `/python-engineering:standards-for-python-development` when applying shared architecture, typing, testing, or CLI rules.

- **Configuration via pyproject.toml**: Standards-compliant PEP 621 metadata with sensible defaults
- **Build Targets**: Wheel and source distribution builds with extensive customization
- **Build Hooks**: Dynamic code execution during build for artifacts, version management, and compilation
- **Version Management**: Multiple version sources with automatic version injection
- **File Selection**: Git-aware VCS integration with glob pattern matching
- **Plugins**: Extensible architecture for custom builders, hooks, and metadata hooks

## Reference Documentation

This skill provides comprehensive reference documentation organized by topic. Each section links to detailed guides covering configuration, usage patterns, and examples.

### Project Configuration

- `references/project-metadata/index.md` - Package metadata, dependencies, entry points, dynamic fields
- `references/build-system/index.md` - Build backend setup, PEP 517/518, reproducible builds, environment variables

### Build Targets

- `references/wheel-target/index.md` - Wheel configuration, package discovery, file selection, editable installs
- `references/sdist-target/index.md` - Sdist configuration, VCS integration, legacy setup.py support
- `references/build-targets/index.md` - Wheel, sdist, binary, custom builders, multi-version builds
- `references/target-config/index.md` - Target-specific hooks, dependencies, versions, precedence

### File Selection & Build Customization

- `references/file-selection/index.md` - Git-style globs, include/exclude patterns, VCS integration, force-include
- `references/build-hooks/index.md` - Hook interface, execution order, custom hooks, version hooks, build data passing
- `references/advanced-features/index.md` - Dynamic dependencies, force-include, path rewriting, editable installs, build context

### Version & Metadata Management

- `references/version-management/index.md` - Version sources (code, regex, env), schemes, validation, build hooks
- `references/metadata-hooks/index.md` - Metadata hook interface, custom hooks, dynamic metadata generation
- `references/context-formatting/index.md` - Context variables, environment-based config, interpolation

### Plugin System

- `references/plugins/index.md` - Builder, hook, metadata, version plugins, hatch-vcs, plugin development

### Build Environment & Integration

- `references/build-environment/index.md` - Environment config, dependencies, UV vs pip, Cython integration, isolation
- `references/integration/index.md` - PEP standards compliance, setup.py migration, setuptools compatibility, CMake/extensions
- `references/special-config/index.md` - PEP 561 type hints, SPDX licenses, namespace packages, src-layout, extensions

### Core Concepts & Standards

- `references/core-concepts/index.md` - PEP 517 backend, minimal philosophy, VCS file selection, reproducible builds
- `references/standards/index.md` - Python packaging overview, PEP references, metadata specs, distribution formats

### Operational Guides

- `references/cli-building/index.md` - hatch build commands, python -m build, pip install, output customization
- `references/error-handling/index.md` - Path validation, file selection errors, version/license validation, heuristic failures
- `references/release-notes/index.md` - Hatchling version history, feature additions, PEP 639 support, performance improvements