Version Management in Hatchling

Version Management in Hatchling

Hatchling provides a comprehensive and flexible version management system for Python projects. Version management can be configured to be static (hardcoded) or dynamic (retrieved from various sources), with support for multiple version source plugins, validation schemes, and automated version bumping.

Overview

Hatchling's version management system consists of several key components:

• Static vs Dynamic Versioning: Choose between hardcoded versions or versions derived from external sources
• Version Source Plugins: Retrieve versions from code, files, environment variables, or VCS
• Version Schemes: Define rules for version formats and bumping strategies
• Build Hooks: Automatically update version information during builds
• CLI Integration: Manage versions through the hatch version command

Configuration Approaches

Static Versioning

For projects with manually managed versions, define the version directly in pyproject.toml:

[project]
name = "my-package"
version = "1.2.3"

Learn more about static versioning

Dynamic Versioning

For automated version management, configure dynamic versioning:

[project]
name = "my-package"
dynamic = ["version"]

[tool.hatch.version]
source = "regex"  # or "code", "env", etc.
path = "src/my_package/__about__.py"

Learn more about dynamic versioning

Version Source Plugins

Hatchling includes several built-in version source plugins:

Code Source

Extract version from Python code using dynamic imports:

[tool.hatch.version]
source = "code"
path = "src/my_package/__version__.py"

Code version source documentation

Regex Source

Extract version using regular expressions (default):

[tool.hatch.version]
source = "regex"
path = "src/my_package/__about__.py"
pattern = "__version__ = ['\"](?P<version>[^'\"]+)['\"]"

Regex version source documentation

Environment Variable Source

Read version from environment variables:

[tool.hatch.version]
source = "env"
variable = "MY_PROJECT_VERSION"

Environment version source documentation

Version Schemes

Version schemes define how versions are validated and bumped:

Standard Scheme

The default scheme following PEP 440:

[tool.hatch.version]
scheme = "standard"

[tool.hatch.version.scheme.standard]
validate-bump = true  # Ensure new versions are higher than current

Version schemes documentation

Version Build Hook

Automatically write version information to files during builds:

[tool.hatch.build.hooks.version]
path = "src/my_package/_version.py"
template = '__version__ = "{version}"'

Version build hook documentation

Command Line Usage

Manage versions using the hatch version command:

# Display current version
hatch version

# Set specific version
hatch version "1.2.3"

# Bump version segments
hatch version patch    # 1.2.3 -> 1.2.4
hatch version minor    # 1.2.3 -> 1.3.0
hatch version major    # 1.2.3 -> 2.0.0

CLI usage documentation

Advanced Topics

Version Validation

Control version validation and bumping rules:

[tool.hatch.version.scheme.standard]
validate-bump = false  # Allow any version change

Version validation documentation

Search Paths

Configure multiple locations for version discovery:

[tool.hatch.version]
source = "code"
search-paths = ["src", "lib"]

Search paths documentation

Version Epochs

Handle version epochs and complex version formats:

# Support for epoch prefixes (e.g., 1!2.0.0)
[tool.hatch.version]
pattern = "(?P<epoch>\\d+!)?(?P<version>.*)"

Version epochs documentation

Version Template Configuration

Customize how versions are formatted and stored:

[tool.hatch.build.hooks.version]
template = """
__version__ = "{version}"
__version_info__ = {version_tuple}
"""

Template configuration documentation

Migration Guide

Migrating from other version management systems:

• From setuptools_scm
• From versioneer
• From bump2version

Best Practices

1. Choose the right source: Use regex for simple file-based versions, code for complex logic, env for CI/CD integration
2. Validate versions: Enable validate-bump to prevent accidental version downgrades
3. Use build hooks: Automatically update version files during package builds
4. Follow PEP 440: Stick to standard version formats for maximum compatibility
5. Document your choice: Add comments explaining your version management strategy

Troubleshooting

Common issues and solutions:

• Version not found: Check path configuration and file existence
• Regex not matching: Test your pattern with the actual file content
• Import errors with code source: Ensure no circular dependencies
• Environment variable not set: Provide fallback or default values

Reference

• Version Source Plugin Interface
• Version Scheme Plugin Interface
• Core Metadata Versions
• Configuration Examples