Changed:

• Bump default core metadata version to 2.5

• Add tomlkit as a runtime dependency, which is required to rewrite pyproject.toml when setting a static version

Added:

• The version command can now set a version that is statically defined by the project.version field, updating pyproject.toml in place. Pass --force to allow an explicit downgrade

Fixed:

• Allow the ; private annotation on project.import-names and project.import-namespaces entries rather than rejecting them as invalid import names.

• Reject project.readme paths that are absolute or resolve outside of the project directory.

Fixed

• Only rewrite the shebang of a shared script when a Python shebang is present on the first line, preserving binary files and other content verbatim instead of dropping leading bytes.

Fixed

• Default core metadata version kept at 2.4 until more tools support 2.5

Fix draft release uploads. (#2293)

Fixed:

• Source Date Epoch no longer fails when set to date before 1980.

Changed:

• Drop support for Python 3.9

Added:

• Add sbom-files option and sbom_files build data to the wheel build target for including Software Bill of Materials files.

Added:

• Update the default version of core metadata to 2.4

Fixed:

• Support an old import path that is still used by some consumers like Hatch

Fixed:

• Back-populate string license fields (License-Expression) for core metadata versions prior to 2.4
• Remove the License-Expression and License-Files core metadata from version 2.2 that was missed in the previous minor release

Fixed:

• Add backward compatibility for the old license-files metadata field
• Support an old import path that is still used by some consumers like Hatch

Changed:

• The license-files metadata field has been updated to the latest spec and is now just an array of glob patterns

Added:

• Support version 2.4 of core metadata for the wheel and sdist targets
• Add HATCH_METADATA_CLASSIFIERS_NO_VERIFY environment variable to disable trove classifier verification
• Add .pixi to the list of directories that cannot be traversed
• Bump the minimum supported version of packaging to 24.2

Fixed:

• No longer write package metadata for license expressions and files for versions of core metadata prior to 2.4
• Properly enable Zip64 support for the wheel target
• Properly ignore parent .gitingore files when the project root matches one of the patterns

Changed:

• The macos-max-compat option for the wheel target is now disabled by default and will be removed in a future release

Added:

• Artifacts for the wheel and sdist targets now have their permission bits normalized

Fixed:

• Ignore manylinux/musllinux tags for the wheel target artifact name when enabling the infer_tag build data
• The wheel target build data infer_tag when enabled now respects the MACOSX_DEPLOYMENT_TARGET environment variable

Fixed:

• Add .venv to the list of directories that cannot be traversed
• Output from the core Application utility now writes to stderr

Fixed:

• Maintain file permissions for shared-scripts option/shared_scripts build data of the wheel target

Added:

• Add shared_data and shared_scripts build data for the wheel target

Added:

• Add shared-scripts option for the wheel target

Fixed:

• Support recursive optional dependencies
• Set the packaging dependency version as >=23.2 to avoid its URL validation which can conflict with context formatting

Fixed:

• Fix reading metadata from source distributions when fields are dynamic but not part of core metadata like entry points

Fixed:

• Only read source distribution metadata for fields that are explicitly defined as dynamic

Fixed:

• Fix the custom build hook when using dynamic dependencies

Fixed:

• Fix regression when loading metadata from source distributions
• Fix metadata hooks when building wheels from source distributions

Fixed:

• Update the default version of core metadata to 2.3

Deprecated:

• The app build target has been renamed to binary to reduce ambiguity with the name of an upcoming feature. The former name will still be usable for several minor releases.

Added:

• Metadata for the wheel target now defaults to the PKG-INFO metadata within source distributions
• Add dependencies method to the build hook interface so that hooks can themselves dynamically define dependencies
• Update the default version of core metadata to 2.2
• Update SPDX license information to version 3.23
• Improve error message for when the default heuristics for wheel file inclusion fail

Fixed:

• Properly support core metadata version 2.2
• Remove editables as a direct dependency
• Fix default wheel tag when the supported Python version declaration is strict
• Load VCS ignore patterns first so that whitelisted patterns can be excluded by project configuration
• Don't consider VCS ignore files that are outside of the VCS boundary
• The sdist build target now gracefully ignores UNIX socket files
• Begin ignoring certain files ubiquitously, like .DS_Store on macOS

Fixed:

• Fix loading of local plugins to account for newly released versions of a dependency

Added:

• Add parent context modifier for path fields

Added:

• Add bypass-selection option to the wheel build target to allow for empty (metadata-only) wheels

Fixed:

• Fix regression in 1.19.1 that allowed exclude to count toward inclusion selection, thus bypassing the default inclusion selection heuristics
• Fix writing optional dependency core metadata in situations where there are multiple environment markers

Fixed:

• Add better error message when the wheel build target cannot determine what to ship
• Consider forced inclusion patterns and build-time artifacts as file selection since some build hooks generate the entire wheel contents without user configuration

Changed:

• An error will now be raised if a force-included path does not exist
• An error will now be raised for the wheel build target if no file selection options are defined

Added:

• Officially support Python 3.12
• Allow using an empty string for the sources option to add a prefix to distribution paths

Fixed:

• Properly handle non-zero version epoch for the standard version scheme
• Fix the wheel build target for case insensitive file systems when the project metadata name does not match the directory name on disk
• The app build target no longer has suppressed output
• Prevent duplicate paths when projects require the sources option while build hooks overwrite included paths
• Properly escape spaces for URI context formatting

Changed:

• Upgrade default CPython distributions to 20260807

Added:

• Add the sources environment option, which redirects dependencies to a local path, Git repository, URL, alternate index, or workspace member at install time without altering published metadata. The top-level [tool.hatch.sources] table is an alias for the default environment, environments inherit sources entry by entry, the HATCH_NO_SOURCES environment variable disables them, and hatch dep show sources reports what each source redirects

• Add the --all/-a flag to the build command to build the workspace root and every workspace member defined by the selected environment, consolidating artifacts in the workspace root's dist directory by default. A root that does not define a project table is skipped so that a top-level pyproject.toml may only contain workspace configuration

• Add the tool.hatch.requires-hatch field, a version specifier set that commands reading the project's metadata enforce against the running version of Hatch

• Add first-class support for free-threaded distribution names such as 3.13t and 3.14t to the python commands and environment python option, rather than requiring the HATCH_PYTHON_VARIANT_GIL environment variable

• The version command can now bump versions that are statically defined by the project.version field, updating pyproject.toml in place. Pass --force to allow an explicit downgrade

• Support managing Python 3.15 distributions, currently 3.15.0rc1

Fixed:

• Erase stale coverage data before running hatch test --cover.

• Fix environment creation crashing when a metadata hook exists that doesn’t happen to be installed in the hatch CLI’s environment.

• Fix commands run by hatch run no longer being interruptible with Ctrl-C, which happened because the ignored SIGINT of the parent process was inherited by the child process.

• Fix the generated Pyrefly config being invalid on Windows, since backslashes in the absolute paths were interpreted as TOML escape sequences.

• Fix the hardcoded reliance on pip when installing dependencies internally by using uv instead.

• Fix environment creation silently installing a GIL-enabled Python distribution when Hatch itself runs on a free-threaded build. The distribution matching the running interpreter, such as 3.14t, is now selected.

• Fix free-threaded selectors such as 3.14t being rejected by an environment's python option, even though hatch python install 3.14t already accepted them.

• Never automatically select a prerelease Python distribution, such as 3.15.0rc1, when falling back to the latest compatible version. A prerelease is still installed when requested explicitly.

Fixed:

• Fix dev mode when the project has symlinks and file inclusion is defined with the packages or only-include options
• Change the name of generated PTH files for dev mode so they come first lexicographically and therefore load first

Added:

• The app build target now embeds the project version in the name of binaries

Fixed:

• Fix determining the built executable path for the app build target option when using a local copy of PyApp when there is an explicit target triple set

Added:

• Add app build target option to build using a local copy of the PyApp repository

Added:

• Add app build target

Fixed:

• Fix internal archive root naming for the sdist target when strict-naming is disabled to match the file name in order to support the expectation of some frontends

Added:

• Add trove-classifiers as a dependency

Fixed:

• Properly normalize metadata descriptions that contain line breaks

Added:

• Update the set of known trove classifiers to version 2023.2.8

Fixed:

• Add macos-max-compat option to the wheel target that is enabled by default to support the latest version 22.0 of the packaging library

Fixed:

• Fix minor regression in the PEP 517/660 function signatures that was discovered by Fedora

Added:

• Improve readability of exceptions
• Add extra_metadata build data to the wheel target
• Retroactively support License-Expression core metadata starting at version 2.1
• Add more type hints
• Update the set of known trove classifiers to version 2022.12.22
• Update SPDX license information to version 3.19
• Store Hatchling's metadata in pyproject.toml

Fixed:

• Acknowledge the ARCHFLAGS environment variable on macOS for the wheel target when build hooks set the infer_tag build data to true
• Fix dependency checking when encountering broken distributions
• Fix the support-legacy option for the sdist target when using a src-layout project structure
• Remove unnecessary encoding declaration in the default template for the version build hook

Fixed:

• Fix default file selection behavior of the wheel target when there is a single top-level module

Added:

• Add env version source to retrieve the version from an environment variable
• Add validate-bump option to the standard version scheme

Fixed:

• Use proper CSV formatting for the RECORD metadata file of the wheel target to avoid warnings during installation by pip if, for example, file names contain commas
• Fix installations with pip for build hooks that modify runtime dependencies
• Decreasing verbosity now has no affect on output that should always be displayed

Added:

• Add the following to the list of directories that cannot be traversed: __pypackages__, .hg, .hatch, .tox, .nox
• Add deprecated option to allow ambiguous features

Fixed:

• Improve tracking of dynamic metadata
• Fix core metadata for entries in project.optional-dependencies that use direct references

Changed:

• File pattern matching now more closely resembles Git's behavior

Added:

• Implement a minimal version of prepare_metadata_for_build_wheel and prepare_metadata_for_build_editable for non-frontend tools that only need to inspect a project's metadata
• Add metadata command to view PEP 621 project metadata
• Improve error messages for SPDX license errors
• Retroactively support License-File for core metadata starting at version 2.1
• Bump the minimum supported version of pathspec to 0.10.1

Fixed:

• Allow the valid non-SPDX license values LicenseRef-Public-Domain and LicenseRef-Proprietary
• Show the help text of the CLI when no subcommand is selected

Fixed:

• Fix default file inclusion for wheel build targets when both the project name and package directory name are not normalized

Added:

• Add get_known_classifiers method to metadata hooks

Fixed:

• Fix check for updating static versions with the version command when metadata hooks are in use

Fixed:

• Fix the value the relative_path attribute of included files, that some build plugins may use, when selecting explicit paths

Added:

• Add require-runtime-features option for builders and build hooks
• Check for unknown trove classifiers
• Update SPDX license information to version 3.18

Fixed:

• Add better error message for wheel target dev mode installations that define path rewrites with the sources option
• Note the allow-direct-references option in the relevant error messages

Changed:

• When no build targets are specified on the command line, now default to sdist and wheel targets rather than what happens to be defined in config
• The code version source now only supports files with known extensions
• Global build hooks now run before target-specific build hooks to better match expected behavior

Added:

• The code version source now supports loading extension modules
• Add search-paths option for the code version source

Fixed:

• Fix removing sources using an empty string value in the mapping
• The strict-naming option now also applies to the metadata directory of wheel targets

Added:

• Support the final draft of PEP 639
• Add strict-naming option for sdist and wheel targets

Fixed:

• Project names are now stored in sdist and wheel target core metadata exactly as defined in pyproject.toml without normalization to allow control of how PyPI displays them

Fixed:

• Fix forced inclusion of important files like licenses for sdist targets when using the explicit selection options
• Don't sort project URL metadata so that the rendered order on PyPI can be controlled

Changed:

• The packages option uses the new only-include option to provide targeted inclusion, since that is desired most of the time. You can retain the old behavior by using the include and sources options together.

Added:

• Support PEP 561 type hinting
• Add version build hook
• Add only-include option
• The editable version of wheel targets now respects the force-include option by default
• The force-include option now supports path rewriting with the sources option
• The wheel target shared-data and extra-metadata options now respect file selection options
• The wheel target now auto-detects single module layouts
• Improve performance by never entering directories that are guaranteed to be undesirable like __pycache__ rather than excluding individual files within
• Update SPDX license information to version 3.17

Fixed:

• Don't write empty entry points file for wheel targets if there are no entry points defined
• Allow metadata hooks to set the version in all cases
• Prevent duplicate file entries from inclusion when using the force-include option

Fixed:

• Better populate global variables for the code version source

Removed:

• Remove unused global args context string formatting field

Added:

• Improve error messages for the env context string formatting field

Fixed:

• Fix uri context string formatting modifier on Windows

Added:

• Allow context formatting for project.dependencies and project.optional-dependencies

Added:

• Add uri and real context string formatting modifiers for file system paths

Changed:

• Drop support for Python 2

Added:

• Improve error messaging for invalid versions
• Update project metadata to reflect support for Python 3.11

Fixed:

• Fix support for Windows on Python 2 by removing its support for symlinks