diff --git a/dev/history/hatchling/index.html b/dev/history/hatchling/index.html index 648f1cdf8..5d152d4f8 100644 --- a/dev/history/hatchling/index.html +++ b/dev/history/hatchling/index.html @@ -7,6 +7,6 @@ .gdesc-inner { font-size: 0.75rem; } body[data-md-color-scheme="slate"] .gdesc-inner { background: var(--md-default-bg-color);} body[data-md-color-scheme="slate"] .gslide-title { color: var(--md-default-fg-color);} - body[data-md-color-scheme="slate"] .gslide-desc { color: var(--md-default-fg-color);}
Skip to content

Hatchling history

All notable changes to Hatchling will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

Unreleased

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

1.24.2 - 2024-04-22

Fixed:

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

1.24.1 - 2024-04-18

Fixed:

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

1.24.0 - 2024-04-16

Added:

  • Add shared_data and shared_scripts build data for the wheel target

1.23.0 - 2024-04-14

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

1.22.5 - 2024-04-04

Fixed:

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

1.22.4 - 2024-03-23

Fixed:

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

1.22.3 - 2024-03-19

Fixed:

  • Fix the custom build hook when using dynamic dependencies

1.22.2 - 2024-03-16

Fixed:

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

1.22.1 - 2024-03-16

Fixed:

  • Update the default version of core metadata to 2.3

1.22.0 - 2024-03-16

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

1.21.1 - 2024-01-25

Fixed:

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

1.21.0 - 2023-12-18

Added:

  • Add parent context modifier for path fields

1.20.0 - 2023-12-13

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

1.19.1 - 2023-12-12

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

1.19.0 - 2023-12-11

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

1.18.0 - 2023-06-12

Changed:

  • Drop support for Python 3.7

Added:

  • Update the list of directories that are always excluded for builds

1.17.1 - 2023-06-03

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

1.17.0 - 2023-05-12

Added:

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

1.16.1 - 2023-05-11

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

1.16.0 - 2023-05-11

Added:

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

1.15.0 - 2023-05-09

Added:

  • Add app build target

1.14.1 - 2023-04-23

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

1.14.0 - 2023-04-02

Added:

  • Add trove-classifiers as a dependency

Fixed:

  • Properly normalize metadata descriptions that contain line breaks

1.13.0 - 2023-02-09

Added:

  • Update the set of known trove classifiers to version 2023.2.8

1.12.2 - 2023-01-05

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

1.12.1 - 2022-12-31

Fixed:

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

1.12.0 - 2022-12-30

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

1.11.1 - 2022-10-19

Fixed:

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

1.11.0 - 2022-10-08

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

1.10.0 - 2022-09-18

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

1.9.0 - 2022-09-09

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

1.8.1 - 2022-08-25

Fixed:

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

1.8.0 - 2022-08-16

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

1.7.1 - 2022-08-13

Fixed:

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

1.7.0 - 2022-08-12

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

1.6.0 - 2022-07-23

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

1.5.0 - 2022-07-11

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

1.4.1 - 2022-07-04

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

1.4.0 - 2022-07-03

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

1.3.1 - 2022-05-30

Fixed:

  • Better populate global variables for the code version source

1.3.0 - 2022-05-22

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

1.2.0 - 2022-05-20

Added:

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

1.1.0 - 2022-05-19

Added:

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

1.0.0 - 2022-05-17

Changed:

  • Drop support for Python 2

Added:

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

0.25.1 - 2022-06-14

Fixed:

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

0.25.0 - 2022-05-15

Added:

  • Add skip-excluded-dirs build option
  • Allow build data to add additional project dependencies for wheel and sdist build targets
  • Add force_include_editable build data for the wheel build target
  • Add build_hooks build data
  • Add support for Mercurial's .hgignore files when using glob syntax
  • Update project metadata to reflect the adoption by PyPA

Fixed:

  • Properly use underscores for the name of force_include build data
  • No longer greedily skip excluded directories by default

0.24.0 - 2022-04-28

This is the initial public release of the Hatchling build system. Support for Python 2 will be dropped in version 1.

Skip to content

Hatchling history

All notable changes to Hatchling will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

Unreleased

1.25.0 - 2024-06-22

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

1.24.2 - 2024-04-22

Fixed:

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

1.24.1 - 2024-04-18

Fixed:

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

1.24.0 - 2024-04-16

Added:

  • Add shared_data and shared_scripts build data for the wheel target

1.23.0 - 2024-04-14

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

1.22.5 - 2024-04-04

Fixed:

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

1.22.4 - 2024-03-23

Fixed:

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

1.22.3 - 2024-03-19

Fixed:

  • Fix the custom build hook when using dynamic dependencies

1.22.2 - 2024-03-16

Fixed:

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

1.22.1 - 2024-03-16

Fixed:

  • Update the default version of core metadata to 2.3

1.22.0 - 2024-03-16

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

1.21.1 - 2024-01-25

Fixed:

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

1.21.0 - 2023-12-18

Added:

  • Add parent context modifier for path fields

1.20.0 - 2023-12-13

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

1.19.1 - 2023-12-12

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

1.19.0 - 2023-12-11

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

1.18.0 - 2023-06-12

Changed:

  • Drop support for Python 3.7

Added:

  • Update the list of directories that are always excluded for builds

1.17.1 - 2023-06-03

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

1.17.0 - 2023-05-12

Added:

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

1.16.1 - 2023-05-11

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

1.16.0 - 2023-05-11

Added:

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

1.15.0 - 2023-05-09

Added:

  • Add app build target

1.14.1 - 2023-04-23

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

1.14.0 - 2023-04-02

Added:

  • Add trove-classifiers as a dependency

Fixed:

  • Properly normalize metadata descriptions that contain line breaks

1.13.0 - 2023-02-09

Added:

  • Update the set of known trove classifiers to version 2023.2.8

1.12.2 - 2023-01-05

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

1.12.1 - 2022-12-31

Fixed:

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

1.12.0 - 2022-12-30

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

1.11.1 - 2022-10-19

Fixed:

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

1.11.0 - 2022-10-08

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

1.10.0 - 2022-09-18

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

1.9.0 - 2022-09-09

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

1.8.1 - 2022-08-25

Fixed:

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

1.8.0 - 2022-08-16

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

1.7.1 - 2022-08-13

Fixed:

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

1.7.0 - 2022-08-12

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

1.6.0 - 2022-07-23

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

1.5.0 - 2022-07-11

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

1.4.1 - 2022-07-04

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

1.4.0 - 2022-07-03

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

1.3.1 - 2022-05-30

Fixed:

  • Better populate global variables for the code version source

1.3.0 - 2022-05-22

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

1.2.0 - 2022-05-20

Added:

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

1.1.0 - 2022-05-19

Added:

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

1.0.0 - 2022-05-17

Changed:

  • Drop support for Python 2

Added:

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

0.25.1 - 2022-06-14

Fixed:

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

0.25.0 - 2022-05-15

Added:

  • Add skip-excluded-dirs build option
  • Allow build data to add additional project dependencies for wheel and sdist build targets
  • Add force_include_editable build data for the wheel build target
  • Add build_hooks build data
  • Add support for Mercurial's .hgignore files when using glob syntax
  • Update project metadata to reflect the adoption by PyPA

Fixed:

  • Properly use underscores for the name of force_include build data
  • No longer greedily skip excluded directories by default

0.24.0 - 2022-04-28

This is the initial public release of the Hatchling build system. Support for Python 2 will be dropped in version 1.

\ No newline at end of file diff --git a/dev/search/search_index.json b/dev/search/search_index.json index 51994c830..993ee4d9c 100644 --- a/dev/search/search_index.json +++ b/dev/search/search_index.json @@ -1 +1 @@ -{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"],"fields":{"title":{"boost":1000.0},"text":{"boost":1.0},"tags":{"boost":1000000.0}}},"docs":[{"location":"","title":"Hatch","text":"CI/CD Docs Package Meta

Hatch is a modern, extensible Python project manager. See the Why Hatch? page for more information.

"},{"location":"#license","title":"License","text":"

Hatch is distributed under the terms of the MIT license.

"},{"location":"#navigation","title":"Navigation","text":"

Documentation for specific MAJOR.MINOR versions can be chosen by using the dropdown on the top of every page. The dev version reflects changes that have not yet been released.

Also, desktop readers can use special keyboard shortcuts:

Keys Action Navigate to the \"previous\" page Navigate to the \"next\" page Display the search modal"},{"location":"build/","title":"Builds","text":""},{"location":"build/#configuration","title":"Configuration","text":"

Builds are configured using the tool.hatch.build table. Every target is defined by a section within tool.hatch.build.targets, for example:

pyproject.toml hatch.toml 
[tool.hatch.build.targets.sdist]\nexclude = [\n  \"/.github\",\n  \"/docs\",\n]\n\n[tool.hatch.build.targets.wheel]\npackages = [\"src/foo\"]\n
[build.targets.sdist]\nexclude = [\n  \"/.github\",\n  \"/docs\",\n]\n\n[build.targets.wheel]\npackages = [\"src/foo\"]\n
"},{"location":"build/#building","title":"Building","text":"

Invoking the build command without any arguments will build the sdist and wheel targets:

$ hatch build\n[sdist]\ndist/hatch_demo-1rc0.tar.gz\n\n[wheel]\ndist/hatch_demo-1rc0-py3-none-any.whl\n

To only build specific targets, use the -t/--target option:

$ hatch build -t wheel\n[wheel]\ndist/hatch_demo-1rc0-py3-none-any.whl\n

If the target supports multiple versions, you can specify the exact versions to build by appending a colon followed by the desired versions separated by commas:

$ hatch -v build -t wheel:standard\n[wheel]\nBuilding `wheel` version `standard`\ndist/hatch_demo-1rc0-py3-none-any.whl\n
"},{"location":"build/#packaging-ecosystem","title":"Packaging ecosystem","text":"

Hatch complies with modern Python packaging specs and therefore your projects can be used by other tools with Hatch serving as just the build backend.

So you could use tox as an alternative to Hatch's environment management, or cibuildwheel to distribute packages for every platform, and they both will transparently use Hatch without any extra modification.

"},{"location":"environment/","title":"Environments","text":"

Environments are designed to allow for isolated workspaces for testing, building documentation, or anything else projects need.

Unless an environment is chosen explicitly, Hatch will use the default environment.

Tip

For a more comprehensive walk-through, see the Basic usage tutorial.

"},{"location":"environment/#creation","title":"Creation","text":"

You can create environments by using the env create command. Let's enter the directory of the project we created in the setup phase:

$ hatch env create\nCreating environment: default\nInstalling project in development mode\nSyncing dependencies\n

Tip

You never need to manually create environments as spawning a shell or running commands within one will automatically trigger creation.

"},{"location":"environment/#entering-environments","title":"Entering environments","text":"

You can spawn a shell within an environment by using the shell command.

$ hatch shell\n(hatch-demo) $\n

Now confirm the project has been installed:

(hatch-demo) $ pip show hatch-demo\nName: hatch-demo\nVersion: 0.0.1\n...\n

Finally, see where your environment's Python is located:

(hatch-demo) $ python -c \"import sys;print(sys.executable)\"\n...\n

You can type exit to leave the environment.

"},{"location":"environment/#command-execution","title":"Command execution","text":"

The run command allows you to execute commands in an environment as if you had already entered it. For example, running the following command will output the same path as before:

hatch run python -c \"import sys;print(sys.executable)\"\n

Tip

Be sure to check out how to define scripts for your project.

"},{"location":"environment/#dependencies","title":"Dependencies","text":"

Hatch ensures that environments are always compatible with the currently defined project dependencies (if installed and in dev mode) and environment dependencies.

To add cowsay as a dependency, open pyproject.toml and add it to the dependencies array:

pyproject.toml 
[project]\n...\ndependencies = [\n  \"cowsay\"\n]\n

This dependency will be installed the next time you spawn a shell or run a command. For example:

$ hatch run cowsay -t \"Hello, world!\"\nSyncing dependencies\n  _____________\n| Hello, world! |\n  =============\n             \\\n              \\\n                ^__^\n                (oo)\\_______\n                (__)\\       )\\/\\\n                    ||----w |\n                    ||     ||\n

Note

The Syncing dependencies status will display temporarily when Hatch updates environments in response to any dependency changes that you make.

"},{"location":"environment/#selection","title":"Selection","text":"

You can select which environment to enter or run commands in by using the -e/--env root option or by setting the HATCH_ENV environment variable.

The run command allows for more explicit selection by prepending <ENV_NAME>: to commands. For example, if you had the following configuration:

pyproject.toml hatch.toml 
[tool.hatch.envs.docs]\ndependencies = [\n  \"mkdocs\"\n]\n[tool.hatch.envs.docs.scripts]\nbuild = \"mkdocs build --clean --strict\"\nserve = \"mkdocs serve --dev-addr localhost:8000\"\n
[envs.docs]\ndependencies = [\n  \"mkdocs\"\n]\n[envs.docs.scripts]\nbuild = \"mkdocs build --clean --strict\"\nserve = \"mkdocs serve --dev-addr localhost:8000\"\n

you could then serve your documentation by running:

hatch run docs:serve\n

Tip

If you've already entered an environment, commands will target it by default.

"},{"location":"environment/#matrix","title":"Matrix","text":"

Every environment can define its own set of matrices:

pyproject.toml hatch.toml 
[tool.hatch.envs.test]\ndependencies = [\n  \"pytest\"\n]\n\n[[tool.hatch.envs.test.matrix]]\npython = [\"3.10\", \"3.11\"]\nversion = [\"42\", \"3.14\"]\n\n[[tool.hatch.envs.test.matrix]]\npython = [\"3.11\", \"3.12\"]\nversion = [\"9000\"]\nfeature = [\"foo\", \"bar\"]\n
[envs.test]\ndependencies = [\n  \"pytest\"\n]\n\n[[envs.test.matrix]]\npython = [\"3.10\", \"3.11\"]\nversion = [\"42\", \"3.14\"]\n\n[[envs.test.matrix]]\npython = [\"3.11\", \"3.12\"]\nversion = [\"9000\"]\nfeature = [\"foo\", \"bar\"]\n

Using the env show command would then display:

$ hatch env show --ascii\n     Standalone\n+---------+---------+\n| Name    | Type    |\n+=========+=========+\n| default | virtual |\n+---------+---------+\n                        Matrices\n+------+---------+----------------------+--------------+\n| Name | Type    | Envs                 | Dependencies |\n+======+=========+======================+==============+\n| test | virtual | test.py3.10-42       | pytest       |\n|      |         | test.py3.10-3.14     |              |\n|      |         | test.py3.11-42       |              |\n|      |         | test.py3.11-3.14     |              |\n|      |         | test.py3.11-9000-foo |              |\n|      |         | test.py3.11-9000-bar |              |\n|      |         | test.py3.12-9000-foo |              |\n|      |         | test.py3.12-9000-bar |              |\n+------+---------+----------------------+--------------+\n
"},{"location":"environment/#removal","title":"Removal","text":"

You can remove a single environment or environment matrix by using the env remove command or all of a project's environments by using the env prune command.

"},{"location":"install/","title":"Installation","text":""},{"location":"install/#github-actions","title":"GitHub Actions","text":"
- name: Install Hatch\n  uses: pypa/hatch@install\n

Refer to the official action for more information.

"},{"location":"install/#installers","title":"Installers","text":"macOSWindows GUI installerCommand line installer
  1. In your browser, download the .pkg file: hatch-universal.pkg
  2. Run your downloaded file and follow the on-screen instructions.
  3. Restart your terminal.

  4. To verify that the shell can find and run the hatch command in your PATH, use the following command.

    $ hatch --version\n1.12.0\n

  1. Download the file using the curl command. The -o option specifies the file name that the downloaded package is written to. In this example, the file is written to hatch-universal.pkg in the current directory.

    curl -Lo hatch-universal.pkg https://github.com/pypa/hatch/releases/latest/download/hatch-universal.pkg\n

  2. Run the standard macOS installer program, specifying the downloaded .pkg file as the source. Use the -pkg parameter to specify the name of the package to install, and the -target / parameter for the drive in which to install the package. The files are installed to /usr/local/hatch, and an entry is created at /etc/paths.d/hatch that instructs shells to add the /usr/local/hatch directory to. You must include sudo on the command to grant write permissions to those folders.

    sudo installer -pkg ./hatch-universal.pkg -target /\n

  3. Restart your terminal.

  4. To verify that the shell can find and run the hatch command in your PATH, use the following command.

    $ hatch --version\n1.12.0\n
GUI installerCommand line installer
  1. In your browser, download one the .msi files:
  2. Run your downloaded file and follow the on-screen instructions.
  3. Restart your terminal.

  4. To verify that the shell can find and run the hatch command in your PATH, use the following command.

    $ hatch --version\n1.12.0\n

  1. Download and run the installer using the standard Windows msiexec program, specifying one of the .msi files as the source. Use the /passive and /i parameters to request an unattended, normal installation.

    x64x86 
    msiexec /passive /i https://github.com/pypa/hatch/releases/latest/download/hatch-x64.msi\n
    msiexec /passive /i https://github.com/pypa/hatch/releases/latest/download/hatch-x86.msi\n

  2. Restart your terminal.

  3. To verify that the shell can find and run the hatch command in your PATH, use the following command.

    $ hatch --version\n1.12.0\n
"},{"location":"install/#standalone-binaries","title":"Standalone binaries","text":"

After downloading the archive corresponding to your platform and architecture, extract the binary to a directory that is on your PATH and rename to hatch.

LinuxmacOSWindows "},{"location":"install/#pip","title":"pip","text":"

Hatch is available on PyPI and can be installed with pip.

pip install hatch\n

Warning

This method modifies the Python environment in which you choose to install. Consider instead using pipx to avoid dependency conflicts.

"},{"location":"install/#pipx","title":"pipx","text":"

pipx allows for the global installation of Python applications in isolated environments.

pipx install hatch\n
"},{"location":"install/#homebrew","title":"Homebrew","text":"

See the formula for more details.

brew install hatch\n
"},{"location":"install/#conda","title":"Conda","text":"

See the feedstock for more details.

conda install -c conda-forge hatch\n

or with mamba:

mamba install hatch\n

Warning

This method modifies the Conda environment in which you choose to install. Consider instead using pipx or condax to avoid dependency conflicts.

"},{"location":"install/#macports","title":"MacPorts","text":"

See the port for more details.

sudo port install hatch\n
"},{"location":"install/#fedora","title":"Fedora","text":"

The minimum supported version is 37, currently in development as Rawhide.

sudo dnf install hatch\n
"},{"location":"install/#void-linux","title":"Void Linux","text":"
xbps-install hatch\n
"},{"location":"install/#build-system-availability","title":"Build system availability","text":"

Hatchling is Hatch's build backend which you will never need to install manually. See its changelog for version information.

"},{"location":"intro/","title":"Introduction","text":""},{"location":"intro/#setup","title":"Setup","text":"

Projects can be set up for use by Hatch using the new command.

"},{"location":"intro/#new-project","title":"New project","text":"

Let's say you want to create a project named Hatch Demo. You would run:

hatch new \"Hatch Demo\"\n

This would create the following structure in your current working directory:

hatch-demo\n\u251c\u2500\u2500 src\n\u2502   \u2514\u2500\u2500 hatch_demo\n\u2502       \u251c\u2500\u2500 __about__.py\n\u2502       \u2514\u2500\u2500 __init__.py\n\u251c\u2500\u2500 tests\n\u2502   \u2514\u2500\u2500 __init__.py\n\u251c\u2500\u2500 LICENSE.txt\n\u251c\u2500\u2500 README.md\n\u2514\u2500\u2500 pyproject.toml\n

Tip

There are many ways to customize project generation.

"},{"location":"intro/#existing-project","title":"Existing project","text":"

To initialize an existing project, enter the directory containing the project and run the following:

hatch new --init\n

If your project has a setup.py file the command will automatically migrate setuptools configuration for you. Otherwise, this will interactively guide you through the setup process.

"},{"location":"intro/#project-metadata","title":"Project metadata","text":"

Next you'll want to define more of your project's metadata located in the pyproject.toml file. You can specify things like its license, the supported versions of Python, and URLs referring to various parts of your project, like documentation.

"},{"location":"intro/#dependencies","title":"Dependencies","text":"

The last step of the setup process is to define any dependencies that you'd like your project to begin with.

"},{"location":"intro/#configuration","title":"Configuration","text":"

All project-specific configuration recognized by Hatch can be defined in either the pyproject.toml file, or a file named hatch.toml where options are not contained within the tool.hatch table:

pyproject.toml hatch.toml 
[tool.hatch]\noption = \"...\"\n\n[tool.hatch.table1]\noption = \"...\"\n\n[tool.hatch.table2]\noption = \"...\"\n
option = \"...\"\n\n[table1]\noption = \"...\"\n\n[table2]\noption = \"...\"\n

Top level keys in the latter file take precedence when defined in both.

Tip

If you want to make your file more compact, you can use dotted keys, turning the above example into:

pyproject.toml hatch.toml 
[tool.hatch]\noption = \"...\"\ntable1.option = \"...\"\ntable2.option = \"...\"\n
option = \"...\"\ntable1.option = \"...\"\ntable2.option = \"...\"\n
"},{"location":"next-steps/","title":"Next steps","text":""},{"location":"next-steps/#learn-more","title":"Learn more","text":"

At this point you should have a basic understanding of how to use Hatch.

Now you may want to check out advanced configuration for environments or builds, set up your preferred shell, or read more about Hatch's CLI.

After that, check out the Hatch Showcase project to see examples of what is possible.

Finally, if you see a need, feel free to write a plugin for extended functionality.

"},{"location":"next-steps/#community","title":"Community","text":"

For any projects using Hatch, you may add its official badge somewhere prominent like the README.

MarkdownreStructuredText 
[![Hatch project](https://img.shields.io/badge/%F0%9F%A5%9A-Hatch-4051b5.svg)](https://github.com/pypa/hatch)\n
.. image:: https://img.shields.io/badge/%F0%9F%A5%9A-Hatch-4051b5.svg\n   :alt: Hatch project\n   :target: https://github.com/pypa/hatch\n
"},{"location":"publish/","title":"Publishing","text":"

After your project is built, you can distribute it using the publish command.

The -p/--publisher option controls which publisher to use, with the default being index.

"},{"location":"publish/#artifact-selection","title":"Artifact selection","text":"

By default, the dist directory located at the root of your project will be used:

$ hatch publish\ndist/hatch_demo-1rc0-py3-none-any.whl ... success\ndist/hatch_demo-1rc0.tar.gz ... success\n\n[hatch-demo]\nhttps://pypi.org/project/hatch-demo/1rc0/\n

You can instead pass specific paths as arguments:

hatch publish /path/to/artifacts foo-1.tar.gz\n

Only files ending with .whl or .tar.gz will be published.

"},{"location":"publish/#further-resources","title":"Further resources","text":"

Please refer to the publisher plugin reference for configuration options.

There's a How-To on authentication and on options to select the target repository.

The publish command is implemented as a built-in plugin, if you're planning your own plugin, read about the publisher plugin API.

"},{"location":"version/","title":"Versioning","text":""},{"location":"version/#configuration","title":"Configuration","text":"

When the version is not statically set, configuration is defined in the tool.hatch.version table. The source option determines the source to use for retrieving and updating the version. The regex source is used by default.

The regex source requires an option path that represents a relative path to a file containing the project's version:

pyproject.toml hatch.toml 
[tool.hatch.version]\npath = \"src/hatch_demo/__about__.py\"\n
[version]\npath = \"src/hatch_demo/__about__.py\"\n

The default pattern looks for a variable named __version__ or VERSION that is set to a string containing the version, optionally prefixed with the lowercase letter v.

If this doesn't reflect how you store the version, you can define a different regular expression using the pattern option:

pyproject.toml hatch.toml 
[tool.hatch.version]\npath = \"pkg/__init__.py\"\npattern = \"BUILD = 'b(?P<version>[^']+)'\"\n
[version]\npath = \"pkg/__init__.py\"\npattern = \"BUILD = 'b(?P<version>[^']+)'\"\n

The pattern must have a named group called version that represents the version.

"},{"location":"version/#display","title":"Display","text":"

Invoking the version command without any arguments will display the current version of the project:

$ hatch version\n0.0.1\n
"},{"location":"version/#updating","title":"Updating","text":"

You can update the version like so:

$ hatch version \"0.1.0\"\nOld: 0.0.1\nNew: 0.1.0\n

The scheme option determines the scheme to use for parsing both the existing and new versions. The standard scheme is used by default, which is based on PEP 440.

Rather than setting the version explicitly, you can select the name of a segment used to increment the version:

$ hatch version minor\nOld: 0.1.0\nNew: 0.2.0\n

You can chain multiple segment updates with a comma. For example, if you wanted to release a preview of your project's first major version, you could do:

$ hatch version major,rc\nOld: 0.2.0\nNew: 1.0.0rc0\n

When you want to release the final version, you would do:

$ hatch version release\nOld: 1.0.0rc0\nNew: 1.0.0\n
"},{"location":"version/#supported-segments","title":"Supported segments","text":"

Here are the supported segments and how they would influence an existing version of 1.0.0:

Segments New version release 1.0.0 major 2.0.0 minor 1.1.0 micropatchfix 1.0.1 aalpha 1.0.0a0 bbeta 1.0.0b0 crcprepreview 1.0.0rc0 rrevpost 1.0.0.post0 dev 1.0.0.dev0"},{"location":"why/","title":"Why Hatch?","text":"

The high level value proposition of Hatch is that if one adopts all functionality then many other tools become unnecessary since there is support for everything one might require. Further, if one chooses to use only specific features then there are still benefits compared to alternatives.

"},{"location":"why/#build-backend","title":"Build backend","text":"

Hatchling, the build backend sister project, has many benefits compared to setuptools. Here we only compare setuptools as that is the one most people are familiar with.

Why not?:

If building extension modules is required then it is recommended that you continue using setuptools, or even other backends that specialize in interfacing with compilers.

"},{"location":"why/#environment-management","title":"Environment management","text":"

Here we compare to both tox and nox. At a high level, there are a few common advantages:

Why not?:

If you are using nox and you wish to migrate, and for some reason you notify sessions, then migration wouldn't be a straight translation but rather you might have to redesign that conditional step.

"},{"location":"why/#python-management","title":"Python management","text":"

Here we compare Python management to that of pyenv.

Why not?:

Currently, Hatch does not allow for the installation of specific patch release versions but rather only uses minor release granularity that tracks the latest patch release. If specific patch releases are important to you then it is best to use an alternative installation mechanism.

"},{"location":"blog/","title":"Blog","text":""},{"location":"blog/2024/05/02/hatch-v1100/","title":"Hatch v1.10.0","text":"

Hatch v1.10.0 brings a test command, support for UV, and a Python script runner.

"},{"location":"blog/2024/05/02/hatch-v1100/#test-command","title":"Test command","text":"

The new test command allows you to easily run tests for your project on multiple versions of Python. The default behavior follows best practices, using pytest with select plugins for test execution and coverage.py for code coverage measurement.

The command is designed to be both simple to use while also satisfying the needs of most projects. For example, the following shows Hatch running tests for Jinja in all environments in the default matrix:

Here is us testing Rich, with a bit of configuration:

See the tutorial for a detailed walk-through and the config reference for options.

"},{"location":"blog/2024/05/02/hatch-v1100/#uv","title":"UV","text":"

The package installer UV, brought to you by the same folks behind Ruff, is now supported. In any environment, you can set the installer option to uv to use UV in place of virtualenv & pip for virtual environment creation and dependency management, respectively. This often results in a significant performance benefit.

For example, if you wanted to enable this functionality for the default environment, you could set the following:

pyproject.toml hatch.toml 
[tool.hatch.envs.default]\ninstaller = \"uv\"\n
[envs.default]\ninstaller = \"uv\"\n

Semi-internal environments like those used for testing and static analysis have this enabled by default.

See the how-to guide for more information about switching the installer.

"},{"location":"blog/2024/05/02/hatch-v1100/#python-script-runner","title":"Python script runner","text":"

The run command now supports executing Python scripts with inline metadata as standardized by PEP 723.

As an example, consider the following script:

script.py 
# /// script\n# requires-python = \">=3.11\"\n# dependencies = [\n#   \"httpx\",\n#   \"rich\",\n# ]\n# ///\n\nimport httpx\nfrom rich.pretty import pprint\n\nresp = httpx.get(\"https://peps.python.org/api/peps.json\")\ndata = resp.json()\npprint([(k, v[\"title\"]) for k, v in data.items()][:10])\n

If you run the script for the first time as follows:

hatch run script.py\n

Hatch will create a dedicated environment for that script using a version of Python greater than or equal to 3.11 with dependencies httpx and rich.

See the how-to guide for more information.

"},{"location":"blog/2024/05/02/hatch-v1100/#static-analysis","title":"Static analysis","text":"

The environment used for static analysis is now completely configurable such that you can fully alter the underlying behavior of the fmt command (see the how-to).

Additionally, Ruff has been updated to version 1.4.0 and the rules selected by default have been updated accordingly. Check out their blog post about how the new hand-written parser has made it twice as fast!

"},{"location":"blog/2024/05/02/hatch-v1100/#community-highlights","title":"Community highlights","text":""},{"location":"blog/2024/05/02/hatch-v1100/#visual-studio-code","title":"Visual Studio Code","text":"

Visual Studio Code announced support for Hatch environments in their latest release. This means that you can now easily discover and select Hatch environments for your projects directly from the editor.

See the how-to guide for detailed instructions.

"},{"location":"blog/2024/05/02/hatch-v1100/#cmake-build-plugin","title":"CMake build plugin","text":"

A new release of the extension module builder scikit-build-core has introduced a build plugin for Hatchling. This means that you can use Hatchling as your build backend while also shipping extension modules built with CMake.

To get started, add the dependency to your build requirements:

pyproject.toml 
[build-system]\nrequires = [\"hatchling>=1.24.2\", \"scikit-build-core~=0.9.3\"]\nbuild-backend = \"hatchling.build\"\n

Then explicitly enable the experimental option (acknowledging that the plugin will move to a dedicated package in the future):

pyproject.toml hatch.toml 
[tool.hatch.build.targets.wheel.hooks.scikit-build]\nexperimental = true\n
[build.targets.wheel.hooks.scikit-build]\nexperimental = true\n

At this point, you can create your CMakeLists.txt file as usual and start building your extension modules with CMake! Check out the dedicated example project for a complete demonstration.

"},{"location":"blog/2024/05/02/hatch-v1100/#meta","title":"Meta","text":""},{"location":"blog/2024/05/02/hatch-v1100/#docs","title":"Docs","text":"

The efforts toward documentation improvements have increased substantially and the priorities have shifted. From now on expect to see far more tutorials and how-to guides rather than just reference material.

"},{"location":"blog/2024/05/02/hatch-v1100/#future","title":"Future","text":"

Upcoming features include:

"},{"location":"blog/2024/05/02/hatch-v1100/#support","title":"Support","text":"

If you or your organization finds value in what Hatch provides, consider a sponsorship to assist with maintenance and more rapid development!

"},{"location":"blog/2022/10/08/hatch-v160/","title":"Hatch v1.6.0","text":"

Hatch v1.6.0 brings improvements to build environments, better handling of dynamic metadata, and support for tools like Visual Studio Code.

"},{"location":"blog/2022/10/08/hatch-v160/#build-environments","title":"Build environments","text":"

Originally, the environment interface method for providing builder sub-environments was intended to be used in conjunction with some cleanup logic in order to provide a fresh setup every time. However, this is unnecessary in practice because build dependencies rarely change.

Without caching, repeat build environment use is slow which affects the following scenarios:

Now a new environment interface method build_environment_exists is used by Hatch to determine whether or not it has already been created, for implementations that have a caching mechanism.

The virtual environment type now uses this method to cache build environments.

"},{"location":"blog/2022/10/08/hatch-v160/#project-metadata","title":"Project metadata","text":"

Dynamically defined metadata is now supported everywhere, thanks to the new caching of virtual build environments.

A project metadata command is introduced that displays the fully resolved metadata. The output format is JSON unless a field is specified as an argument.

For example, if you checkout a project that is built by Hatch, like FastAPI, and run:

hatch project metadata readme\n

only the readme text will be displayed. If the content is in Markdown, then Rich will render it directly in your terminal:

"},{"location":"blog/2022/10/08/hatch-v160/#virtual-environment-location","title":"Virtual environment location","text":"

The virtual environment type now uses a flat layout for storage in the configured virtual environment directory if the directory resides somewhere within the project root or if it is set to a .virtualenvs directory within the user's home directory.

For example, if you define the following Hatch configuration:

config.toml 
[dirs.env]\nvirtual = \".hatch\"\n

and the following matrix:

pyproject.toml hatch.toml 
[[tool.hatch.envs.test.matrix]]\npython = [\"3.7\", \"3.8\", \"3.9\", \"3.10\", \"3.11\"]\n
[[envs.test.matrix]]\npython = [\"3.7\", \"3.8\", \"3.9\", \"3.10\", \"3.11\"]\n

then locating environments with the following command:

hatch env find test\n

will show that the general directory structure is:

.hatch\n\u251c\u2500\u2500 test.py3.7\n\u251c\u2500\u2500 test.py3.8\n\u251c\u2500\u2500 test.py3.9\n\u251c\u2500\u2500 test.py3.10\n\u2514\u2500\u2500 test.py3.11\n

This flat structure is required for detection of virtual environments by tools like Visual Studio Code and PyCharm.

Additionally, the virtual environment type now supports a path option to specify an explicit path that all inherited environments will share, such as the common .venv.

"},{"location":"blog/2022/10/08/hatch-v160/#migration-script-improvements","title":"Migration script improvements","text":"

The script used to migrate existing projects from setuptools has been improved to handle more edge cases that were encountered in the wild and now no longer modifies the formatting of existing pyproject.toml configuration.

"},{"location":"blog/2022/10/08/hatch-v160/#hatchling","title":"Hatchling","text":"

Hatch now depends on Hatchling v1.11.0, which was also just released.

"},{"location":"blog/2022/10/08/hatch-v160/#environment-version-source","title":"Environment version source","text":"

A new env version source is available that allows for the project version to be defined by an environment variable.

"},{"location":"blog/2022/10/08/hatch-v160/#relaxed-version-bumping","title":"Relaxed version bumping","text":"

The standard version scheme now supports a validate-bump option that when set to false will forego the check when updating the version that the desired version is higher than the current version.

This use case comes from Project Jupyter:

A common pattern we use in Jupyter is to bump to a .dev0 minor version bump after making a release. If we have a bug fix that needs to go out in the interim, we'd rather not be forced to create a branch every time.

"},{"location":"blog/2023/12/11/hatch-v180/","title":"Hatch v1.8.0","text":"

Hatch v1.8.0 brings Python distribution management, static analysis and formatting backed by Ruff, and binaries for every platform.

"},{"location":"blog/2023/12/11/hatch-v180/#installation-made-easy","title":"Installation made easy","text":"

One thing that has been a perpetual problem for Hatch and other Python applications is that Python itself is a dependency. You, and more importantly your users, need to in some way get Python before your software can even be used. The recommended way to go about that is platform-dependent and even differs based on your target audience. I viewed this as a central UX problem for Hatch and so severe that I took a bit of a hiatus to solve it.

Luckily, I have to my satisfaction solved this problem in the form of PyApp. It is a runtime installer for Python projects written in Rust. Apps are distributed as standalone executables as users have come to expect and bootstrapping occurs upon the first invocation. Here is an example of what you would see the first time you run a binary from this release:

Now that we have binaries, creating installers for different platforms becomes trivial. Starting with this release not only are binaries available for every platform but also we have installers for Windows and macOS. The installer for macOS is signed using a certificate from the same account used to sign the official distributions from https://www.python.org, so users will not get any security pop-ups. Shout out to @ewdurbin for their extreme generosity in setting up multiple certificates in their free time!

These installers and binaries are now the recommended way to install and update Hatch. These binaries have built-in management so you can update to the latest version by running hatch self update.

Windows signing

In future we will sign the installers for Windows but I did not have time to look into how that works. macOS signing took way longer than I anticipated

"},{"location":"blog/2023/12/11/hatch-v180/#python-management","title":"Python management","text":"

For a long time I and other users have desired that Hatch gain the ability to manage Python distributions. In my mind this was always blocked on a better installation experience because there was sort of a chicken-or-egg problem where you want a Python manager but you first need Python. No longer is that the case!

The new python command group allows for easy installation of various distributions to arbitrary locations which are then added to your PATH by default. Hatch supports CPython and PyPy distributions:

"},{"location":"blog/2023/12/11/hatch-v180/#virtual-environment-python-resolution","title":"Virtual environment Python resolution","text":"

The virtual environment type is now far more intelligent when resolving the parent distribution to use and guarantees that, when no specific version is requested, the resolved distribution will always be compatible with the project.

Additionally, when a requested version cannot be found on PATH it will automatically be downloaded and managed internally.

"},{"location":"blog/2023/12/11/hatch-v180/#static-analysis","title":"Static analysis","text":"

There is a new fmt command, backed entirely by Ruff, that checks and fixes your code for formatting and linting issues.

Starting with this release, Hatch maintains default settings that are guaranteed to be up-to-date and represent best practices for programming in modern Python. The idea is to provide defaults that are so broadly applicable that the majority of users will maintain little if any of their own overrides.

The default behavior is internal management of settings to provide an OOTB experience that works. It is recommended however that you persist the default config file in version control so that other tools like IDEs can utilize your full configuration.

Since Ruff is now provided as a built-in feature, new project templates no longer have such configuration and are much less verbose.

"},{"location":"blog/2023/12/11/hatch-v180/#build-improvements","title":"Build improvements","text":"

Building projects that do not use Hatchling as a backend is now supported and such builds are managed with the standard build tool.

The bridge between Hatch and the Hatchling CLI has been removed. Previously, the builder would send serialized messages to Hatch that would contain the desired content and style for each line of output. This was done in an effort to allow builder and build hook plugins to output pretty messages without actually requiring a dependency like Rich. A problem that arises with this is that builders that invoke subprocesses will not display ANSI codes as one might expect and will lose out on the interactive experience of such invocations, like the built-in binary builder plugin calling cargo build. So now everything is simpler at the expense of no colored output without manual logic, or adding a dependency if you're a third-party plugin.

"},{"location":"blog/2023/12/11/hatch-v180/#faster-environment-usage","title":"Faster environment usage","text":"

Spawning a shell or running commands within environments always first checks that your project's dependencies are satisfied and if not synchronizes the environment with what is defined. Previously, this had the potential to be quite slow for projects that have many dependencies.

Now the set of dependency definitions is hashed and no check is performed if the hash is the same as before, significantly speeding up environment usage in most cases.

"},{"location":"blog/2023/12/11/hatch-v180/#hatchling","title":"Hatchling","text":"

Hatch now depends on Hatchling v1.19.0, which was also just released.

"},{"location":"blog/2023/12/11/hatch-v180/#better-defaults","title":"Better defaults","text":"

Hatchling is all about providing the best possible defaults, even at the expense of backward compatibility. In this release, there are two breaking changes that provide a much better user experience and were in fact requested by users.

"},{"location":"blog/2023/12/11/hatch-v180/#binary-build-target","title":"Binary build target","text":"

A new binary build target is now stable that allows for the building of standalone binaries for projects. This is what Hatch itself uses for its binaries.

"},{"location":"blog/2023/12/11/hatch-v180/#meta","title":"Meta","text":""},{"location":"blog/2023/12/11/hatch-v180/#why-hatch","title":"Why Hatch?","text":"

A new page has been introduced that discusses the value proposition of Hatch and Hatchling in comparison to alternatives. Currently, it only addresses a few features but in future this page will become more comprehensive.

"},{"location":"blog/2023/12/11/hatch-v180/#future","title":"Future","text":"

Upcoming features include a test command, commands to manage dependencies, and workspaces functionality similar to Cargo that will make managing monorepos far easier.

Next year there will be two large efforts that you should expect to see:

  1. A significant amount of my free time (and some at work) will be devoted to introducing lock file functionality in Hatch and trying to get whatever that happens to be standardized.

    I met with @brettcannon about his thoughts post-PEP 665 and about mousebender. I also met with the prefix.dev team about rip and was fortunate enough to be shown a demo before its official announcement.

    At the moment, the two options I see are to either go all in and contribute to mousebender or rely on the Prefix folks and use rip. The latter has the benefit of potentially supporting Conda as a side effect with the downside of being quite new with the spec firmly out of our control. The former has the benefit of being able to easily gain institutional support from the Python packaging team and each of our employers with the downside being a significant amount of work needing to be done.

  2. When @henryiii is able to get some free time away from teaching I plan to work with him once again and push very hard for the Python build ecosystem to adopt the extensionlib approach.

    I am of the opinion that the Python community has not fully completed the expressed outcome of PEP 517 in that build backends are still (for the most part) reliant on setuptools for building non-Python code bases.

    Basically, there are components that interact with compilers to produce extension modules and components that pack files into an archive which we call a build backend. These are two distinct pieces of functionality and my view is that there should be an API that allows backends to consume extension module builders to find out where things got created and where they should be shipped inside archives.

    In this hypothetical future any build backend would be able to trigger the building of extension modules based on user configuration.

"},{"location":"blog/2023/12/11/hatch-v180/#support","title":"Support","text":"

If you or your organization finds value in what Hatch provides, consider a sponsorship to assist with maintenance and more rapid development!

"},{"location":"blog/2023/12/18/hatch-v190/","title":"Hatch v1.9.0","text":"

Hatch v1.9.0 brings improvements to static analysis and important bug fixes.

"},{"location":"blog/2023/12/18/hatch-v190/#static-analysis","title":"Static analysis","text":"

The default version of Ruff has been increased to v0.1.8. This release brings formatting capabilities to docstrings and Hatch enables this by default with line length set to 80. This length was chosen as the default because it plays nicely with the rendering of the most popular themes for Python documentation, such as Material for MkDocs and Furo.

Additionally, it is now possible for projects to pin to specific versions of Ruff for upgrading at a later time:

pyproject.toml hatch.toml 
[tool.hatch.envs.hatch-static-analysis]\ndependencies = [\"ruff==X.Y.Z\"]\n
[envs.hatch-static-analysis]\ndependencies = [\"ruff==X.Y.Z\"]\n
"},{"location":"blog/2023/12/18/hatch-v190/#notable-fixes","title":"Notable fixes","text":""},{"location":"cli/about/","title":"CLI usage","text":""},{"location":"cli/about/#verbosity","title":"Verbosity","text":"

The amount of displayed output is controlled solely by the -v/--verbose (environment variable HATCH_VERBOSE) and -q/--quiet (environment variable HATCH_QUIET) root options.

The levels are documented here.

"},{"location":"cli/about/#project-awareness","title":"Project awareness","text":"

No matter the mode, Hatch will always change to the project's root directory for entering or running commands in environments.

"},{"location":"cli/about/#tab-completion","title":"Tab completion","text":"

Completion is achieved by saving a script and then executing it as a part of your shell's startup sequence.

Afterward, you'll need to start a new shell in order for the changes to take effect.

BashZ shellfish

Save the script somewhere:

_HATCH_COMPLETE=bash_source hatch > ~/.hatch-complete.bash\n

Source the file in ~/.bashrc (or ~/.bash_profile if on macOS):

. ~/.hatch-complete.bash\n

Save the script somewhere:

_HATCH_COMPLETE=zsh_source hatch > ~/.hatch-complete.zsh\n

Source the file in ~/.zshrc:

. ~/.hatch-complete.zsh\n

Save the script in ~/.config/fish/completions:

_HATCH_COMPLETE=fish_source hatch > ~/.config/fish/completions/hatch.fish\n
"},{"location":"cli/reference/","title":"hatch","text":"

Usage:

hatch [OPTIONS] COMMAND [ARGS]...\n

Options:

Name Type Description Default --env, -e text The name of the environment to use [env var: HATCH_ENV] default --project, -p text The name of the project to work on [env var: HATCH_PROJECT] None --verbose, -v integer range (0 and above) Increase verbosity (can be used additively) [env var: HATCH_VERBOSE] 0 --quiet, -q integer range (0 and above) Decrease verbosity (can be used additively) [env var: HATCH_QUIET] 0 --color / --no-color boolean Whether or not to display colored output (default is auto-detection) [env vars: FORCE_COLOR/NO_COLOR] None --interactive / --no-interactive boolean Whether or not to allow features like prompts and progress bars (default is auto-detection) [env var: HATCH_INTERACTIVE] None --data-dir text The path to a custom directory used to persist data [env var: HATCH_DATA_DIR] None --cache-dir text The path to a custom directory used to cache data [env var: HATCH_CACHE_DIR] None --config text The path to a custom config file to use [env var: HATCH_CONFIG] None --version boolean Show the version and exit. False --help boolean Show this message and exit. False"},{"location":"cli/reference/#hatch-build","title":"hatch build","text":"

Build a project.

Usage:

hatch build [OPTIONS] [LOCATION]\n

Options:

Name Type Description Default --target, -t text The target to build, overriding project defaults. This may be selected multiple times e.g. -t sdist -t wheel None --hooks-only boolean Whether or not to only execute build hooks [env var: HATCH_BUILD_HOOKS_ONLY] False --no-hooks boolean Whether or not to disable build hooks [env var: HATCH_BUILD_NO_HOOKS] False --ext boolean Whether or not to only execute build hooks for distributing binary Python packages, such as compiling extensions. Equivalent to --hooks-only -t wheel False --clean, -c boolean Whether or not existing artifacts should first be removed [env var: HATCH_BUILD_CLEAN] False --clean-hooks-after boolean Whether or not build hook artifacts should be removed after each build [env var: HATCH_BUILD_CLEAN_HOOKS_AFTER] False --help boolean Show this message and exit. False"},{"location":"cli/reference/#hatch-clean","title":"hatch clean","text":"

Remove build artifacts.

Usage:

hatch clean [OPTIONS] [LOCATION]\n

Options:

Name Type Description Default --target, -t text The target with which to remove artifacts, overriding project defaults. This may be selected multiple times e.g. -t sdist -t wheel None --hooks-only boolean Whether or not to only remove artifacts from build hooks [env var: HATCH_BUILD_HOOKS_ONLY] False --no-hooks boolean Whether or not to ignore artifacts from build hooks [env var: HATCH_BUILD_NO_HOOKS] False --ext boolean Whether or not to only remove artifacts from build hooks for distributing binary Python packages, such as compiled extensions. Equivalent to --hooks-only -t wheel False --help boolean Show this message and exit. False"},{"location":"cli/reference/#hatch-config","title":"hatch config","text":"

Manage the config file

Usage:

hatch config [OPTIONS] COMMAND [ARGS]...\n

Options:

Name Type Description Default --help boolean Show this message and exit. False"},{"location":"cli/reference/#hatch-config-explore","title":"hatch config explore","text":"

Open the config location in your file manager.

Usage:

hatch config explore [OPTIONS]\n

Options:

Name Type Description Default --help boolean Show this message and exit. False"},{"location":"cli/reference/#hatch-config-find","title":"hatch config find","text":"

Show the location of the config file.

Usage:

hatch config find [OPTIONS]\n

Options:

Name Type Description Default --help boolean Show this message and exit. False"},{"location":"cli/reference/#hatch-config-restore","title":"hatch config restore","text":"

Restore the config file to default settings.

Usage:

hatch config restore [OPTIONS]\n

Options:

Name Type Description Default --help boolean Show this message and exit. False"},{"location":"cli/reference/#hatch-config-set","title":"hatch config set","text":"

Assign values to config file entries. If the value is omitted, you will be prompted, with the input hidden if it is sensitive.

Usage:

hatch config set [OPTIONS] KEY [VALUE]\n

Options:

Name Type Description Default --help boolean Show this message and exit. False"},{"location":"cli/reference/#hatch-config-show","title":"hatch config show","text":"

Show the contents of the config file.

Usage:

hatch config show [OPTIONS]\n

Options:

Name Type Description Default --all, -a boolean Do not scrub secret fields False --help boolean Show this message and exit. False"},{"location":"cli/reference/#hatch-config-update","title":"hatch config update","text":"

Update the config file with any new fields.

Usage:

hatch config update [OPTIONS]\n

Options:

Name Type Description Default --help boolean Show this message and exit. False"},{"location":"cli/reference/#hatch-dep","title":"hatch dep","text":"

Manage environment dependencies

Usage:

hatch dep [OPTIONS] COMMAND [ARGS]...\n

Options:

Name Type Description Default --help boolean Show this message and exit. False"},{"location":"cli/reference/#hatch-dep-hash","title":"hatch dep hash","text":"

Output a hash of the currently defined dependencies.

Usage:

hatch dep hash [OPTIONS]\n

Options:

Name Type Description Default --project-only, -p boolean Whether or not to exclude environment dependencies False --env-only, -e boolean Whether or not to exclude project dependencies False --help boolean Show this message and exit. False"},{"location":"cli/reference/#hatch-dep-show","title":"hatch dep show","text":"

Display dependencies in various formats

Usage:

hatch dep show [OPTIONS] COMMAND [ARGS]...\n

Options:

Name Type Description Default --help boolean Show this message and exit. False"},{"location":"cli/reference/#hatch-dep-show-requirements","title":"hatch dep show requirements","text":"

Enumerate dependencies as a list of requirements.

Usage:

hatch dep show requirements [OPTIONS]\n

Options:

Name Type Description Default --project-only, -p boolean Whether or not to exclude environment dependencies False --env-only, -e boolean Whether or not to exclude project dependencies False --feature, -f text Whether or not to only show the dependencies of the specified features None --all boolean Whether or not to include the dependencies of all features False --help boolean Show this message and exit. False"},{"location":"cli/reference/#hatch-dep-show-table","title":"hatch dep show table","text":"

Enumerate dependencies in a tabular format.

Usage:

hatch dep show table [OPTIONS]\n

Options:

Name Type Description Default --project-only, -p boolean Whether or not to exclude environment dependencies False --env-only, -e boolean Whether or not to exclude project dependencies False --lines, -l boolean Whether or not to show lines between table rows False --ascii boolean Whether or not to only use ASCII characters False --help boolean Show this message and exit. False"},{"location":"cli/reference/#hatch-env","title":"hatch env","text":"

Manage project environments

Usage:

hatch env [OPTIONS] COMMAND [ARGS]...\n

Options:

Name Type Description Default --help boolean Show this message and exit. False"},{"location":"cli/reference/#hatch-env-create","title":"hatch env create","text":"

Create environments.

Usage:

hatch env create [OPTIONS] [ENV_NAME]\n

Options:

Name Type Description Default --help boolean Show this message and exit. False"},{"location":"cli/reference/#hatch-env-find","title":"hatch env find","text":"

Locate environments.

Usage:

hatch env find [OPTIONS] [ENV_NAME]\n

Options:

Name Type Description Default --help boolean Show this message and exit. False"},{"location":"cli/reference/#hatch-env-prune","title":"hatch env prune","text":"

Remove all environments.

Usage:

hatch env prune [OPTIONS]\n

Options:

Name Type Description Default --help boolean Show this message and exit. False"},{"location":"cli/reference/#hatch-env-remove","title":"hatch env remove","text":"

Remove environments.

Usage:

hatch env remove [OPTIONS] [ENV_NAME]\n

Options:

Name Type Description Default --help boolean Show this message and exit. False"},{"location":"cli/reference/#hatch-env-run","title":"hatch env run","text":"

Run commands within project environments.

The -e/--env option overrides the equivalent root option and the HATCH_ENV environment variable.

The -i/--include and -x/--exclude options may be used to include or exclude certain variables, optionally followed by specific comma-separated values, and may be selected multiple times. For example, if you have the following configuration:

pyproject.toml hatch.toml 
[[tool.hatch.envs.test.matrix]]\npython = [\"3.9\", \"3.10\"]\nversion = [\"42\", \"3.14\", \"9000\"]\n
[[envs.test.matrix]]\npython = [\"3.9\", \"3.10\"]\nversion = [\"42\", \"3.14\", \"9000\"]\n

then running:

hatch env run -i py=3.10 -x version=9000 test:pytest\n

would execute pytest in the environments test.py3.10-42 and test.py3.10-3.14. Note that py may be used as an alias for python.

Note

The inclusion option is treated as an intersection while the exclusion option is treated as a union i.e. an environment must match all of the included variables to be selected while matching any of the excluded variables will prevent selection.

Usage:

hatch env run [OPTIONS] ARGS...\n

Options:

Name Type Description Default --env, -e text The environments to target None --include, -i text The matrix variables to include None --exclude, -x text The matrix variables to exclude None --filter, -f text The JSON data used to select environments None --force-continue boolean Run every command and if there were any errors exit with the first code False --ignore-compat boolean Ignore incompatibility when selecting specific environments False --help boolean Show this message and exit. False"},{"location":"cli/reference/#hatch-env-show","title":"hatch env show","text":"

Show the available environments.

Usage:

hatch env show [OPTIONS] [ENVS]...\n

Options:

Name Type Description Default --ascii boolean Whether or not to only use ASCII characters False --json boolean Whether or not to output in JSON format False --internal, -i boolean Show internal environments False --help boolean Show this message and exit. False"},{"location":"cli/reference/#hatch-fmt","title":"hatch fmt","text":"

Format and lint source code.

Usage:

hatch fmt [OPTIONS] [ARGS]...\n

Options:

Name Type Description Default --check boolean Only check for errors rather than fixing them False --linter, -l boolean Only run the linter False --formatter, -f boolean Only run the formatter False --sync boolean Sync the default config file with the current version of Hatch False --help boolean Show this message and exit. False"},{"location":"cli/reference/#hatch-new","title":"hatch new","text":"

Create or initialize a project.

Usage:

hatch new [OPTIONS] [NAME] [LOCATION]\n

Options:

Name Type Description Default --interactive, -i boolean Interactively choose details about the project False --cli boolean Give the project a command line interface False --init boolean Initialize an existing project False --help boolean Show this message and exit. False"},{"location":"cli/reference/#hatch-project","title":"hatch project","text":"

View project information

Usage:

hatch project [OPTIONS] COMMAND [ARGS]...\n

Options:

Name Type Description Default --help boolean Show this message and exit. False"},{"location":"cli/reference/#hatch-project-metadata","title":"hatch project metadata","text":"

Display project metadata.

If you want to view the raw readme file without rendering, you can use a JSON parser like jq:

hatch project metadata | jq -r .readme\n

Usage:

hatch project metadata [OPTIONS] [FIELD]\n

Options:

Name Type Description Default --help boolean Show this message and exit. False"},{"location":"cli/reference/#hatch-publish","title":"hatch publish","text":"

Publish build artifacts.

Usage:

hatch publish [OPTIONS] [ARTIFACTS]...\n

Options:

Name Type Description Default --repo, -r text The repository with which to publish artifacts [env var: HATCH_INDEX_REPO] None --user, -u text The user with which to authenticate [env var: HATCH_INDEX_USER] None --auth, -a text The credentials to use for authentication [env var: HATCH_INDEX_AUTH] None --ca-cert text The path to a CA bundle [env var: HATCH_INDEX_CA_CERT] None --client-cert text The path to a client certificate, optionally containing the private key [env var: HATCH_INDEX_CLIENT_CERT] None --client-key text The path to the client certificate's private key [env var: HATCH_INDEX_CLIENT_KEY] None --no-prompt, -n boolean Disable prompts, such as for missing required fields False --initialize-auth boolean Save first-time authentication information even if nothing was published False --publisher, -p text The publisher plugin to use (default is index) [env var: HATCH_PUBLISHER] index --option, -o text Options to pass to the publisher plugin. This may be selected multiple times e.g. -o foo=bar -o baz=23 [env var: HATCH_PUBLISHER_OPTIONS] None --yes, -y boolean Confirm without prompting when the plugin is disabled False --help boolean Show this message and exit. False"},{"location":"cli/reference/#hatch-python","title":"hatch python","text":"

Manage Python installations

Usage:

hatch python [OPTIONS] COMMAND [ARGS]...\n

Options:

Name Type Description Default --help boolean Show this message and exit. False"},{"location":"cli/reference/#hatch-python-find","title":"hatch python find","text":"

Locate Python binaries.

Usage:

hatch python find [OPTIONS] NAME\n

Options:

Name Type Description Default -p, --parent boolean Show the parent directory of the Python binary False --dir, -d text The directory in which distributions reside None --help boolean Show this message and exit. False"},{"location":"cli/reference/#hatch-python-install","title":"hatch python install","text":"

Install Python distributions.

You may select all to install all compatible distributions:

hatch python install all\n

You can set custom sources for distributions by setting the HATCH_PYTHON_SOURCE_<NAME> environment variable where <NAME> is the uppercased version of the distribution name with periods replaced by underscores e.g. HATCH_PYTHON_SOURCE_PYPY3_10.

Usage:

hatch python install [OPTIONS] NAMES...\n

Options:

Name Type Description Default --private boolean Do not add distributions to the user PATH False --update, -u boolean Update existing installations False --dir, -d text The directory in which to install distributions, overriding configuration None --help boolean Show this message and exit. False"},{"location":"cli/reference/#hatch-python-remove","title":"hatch python remove","text":"

Remove Python distributions.

You may select all to remove all installed distributions:

hatch python remove all\n

Usage:

hatch python remove [OPTIONS] NAMES...\n

Options:

Name Type Description Default --dir, -d text The directory in which distributions reside None --help boolean Show this message and exit. False"},{"location":"cli/reference/#hatch-python-show","title":"hatch python show","text":"

Show the available Python distributions.

Usage:

hatch python show [OPTIONS]\n

Options:

Name Type Description Default --ascii boolean Whether or not to only use ASCII characters False --dir, -d text The directory in which distributions reside None --help boolean Show this message and exit. False"},{"location":"cli/reference/#hatch-python-update","title":"hatch python update","text":"

Update Python distributions.

You may select all to update all installed distributions:

hatch python update all\n

Usage:

hatch python update [OPTIONS] NAMES...\n

Options:

Name Type Description Default --dir, -d text The directory in which distributions reside None --help boolean Show this message and exit. False"},{"location":"cli/reference/#hatch-run","title":"hatch run","text":"

Run commands within project environments. This is a convenience wrapper around the env run command.

If the first argument contains a colon, then the preceding component will be interpreted as the name of the environment to target, overriding the -e/--env root option and the HATCH_ENV environment variable.

If the environment provides matrices, then you may also provide leading arguments starting with a + or - to select or exclude certain variables, optionally followed by specific comma-separated values. For example, if you have the following configuration:

pyproject.toml hatch.toml 
[[tool.hatch.envs.test.matrix]]\npython = [\"3.9\", \"3.10\"]\nversion = [\"42\", \"3.14\", \"9000\"]\n
[[envs.test.matrix]]\npython = [\"3.9\", \"3.10\"]\nversion = [\"42\", \"3.14\", \"9000\"]\n

then running:

hatch run +py=3.10 -version=9000 test:pytest\n

would execute pytest in the environments test.py3.10-42 and test.py3.10-3.14. Note that py may be used as an alias for python.

Note

Inclusions are treated as an intersection while exclusions are treated as a union i.e. an environment must match all of the included variables to be selected while matching any of the excluded variables will prevent selection.

Usage:

hatch run [OPTIONS] [ENV:]ARGS...\n

Options:

Name Type Description Default --help boolean Show this message and exit. False"},{"location":"cli/reference/#hatch-self","title":"hatch self","text":"

Manage Hatch

Usage:

hatch self [OPTIONS] COMMAND [ARGS]...\n

Options:

Name Type Description Default --help boolean Show this message and exit. False"},{"location":"cli/reference/#hatch-self-report","title":"hatch self report","text":"

Generate a pre-populated GitHub issue.

Usage:

hatch self report [OPTIONS]\n

Options:

Name Type Description Default --no-open, -n boolean Show the URL instead of opening it False --help boolean Show this message and exit. False"},{"location":"cli/reference/#hatch-self-restore","title":"hatch self restore","text":"

Restore the installation

Usage:

hatch self restore [OPTIONS] [ARGS]...\n

Options:

Name Type Description Default --help boolean Show this message and exit. False"},{"location":"cli/reference/#hatch-self-update","title":"hatch self update","text":"

Install the latest version

Usage:

hatch self update [OPTIONS] [ARGS]...\n

Options:

Name Type Description Default --help boolean Show this message and exit. False"},{"location":"cli/reference/#hatch-shell","title":"hatch shell","text":"

Enter a shell within a project's environment.

Usage:

hatch shell [OPTIONS] [ENV_NAME]\n

Options:

Name Type Description Default --name text N/A None --path text N/A None --help boolean Show this message and exit. False"},{"location":"cli/reference/#hatch-status","title":"hatch status","text":"

Show information about the current environment.

Usage:

hatch status [OPTIONS]\n

Options:

Name Type Description Default --help boolean Show this message and exit. False"},{"location":"cli/reference/#hatch-test","title":"hatch test","text":"

Run tests using the hatch-test environment matrix.

If no filtering options are selected, then tests will be run in the first compatible environment found in the matrix with priority given to those matching the current interpreter.

The -i/--include and -x/--exclude options may be used to include or exclude certain variables, optionally followed by specific comma-separated values, and may be selected multiple times. For example, if you have the following configuration:

pyproject.toml hatch.toml 
[[tool.hatch.envs.hatch-test.matrix]]\npython = [\"3.9\", \"3.10\"]\nversion = [\"42\", \"3.14\", \"9000\"]\n
[[envs.hatch-test.matrix]]\npython = [\"3.9\", \"3.10\"]\nversion = [\"42\", \"3.14\", \"9000\"]\n

then running:

hatch test -i py=3.10 -x version=9000\n

would run tests in the environments hatch-test.py3.10-42 and hatch-test.py3.10-3.14.

The -py/--python option is a shortcut for specifying the inclusion -i py=....

Note

The inclusion option is treated as an intersection while the exclusion option is treated as a union i.e. an environment must match all of the included variables to be selected while matching any of the excluded variables will prevent selection.

Usage:

hatch test [OPTIONS] [ARGS]...\n

Options:

Name Type Description Default --randomize, -r boolean Randomize the order of test execution False --parallel, -p boolean Parallelize test execution False --retries integer Number of times to retry failed tests None --retry-delay float Seconds to wait between retries None --cover, -c boolean Measure code coverage False --cover-quiet boolean Disable coverage reporting after tests, implicitly enabling --cover False --all, -a boolean Test all environments in the matrix False --python, -py text The Python versions to test, equivalent to: -i py=... None --include, -i text The matrix variables to include None --exclude, -x text The matrix variables to exclude None --show, -s boolean Show information about environments in the matrix False --help boolean Show this message and exit. False"},{"location":"cli/reference/#hatch-version","title":"hatch version","text":"

View or set a project's version.

Usage:

hatch version [OPTIONS] [DESIRED_VERSION]\n

Options:

Name Type Description Default --help boolean Show this message and exit. False"},{"location":"community/contributing/","title":"Contributing","text":"

The usual process to make a contribution is to:

  1. Check for existing related issues
  2. Fork the repository and create a new branch
  3. Make your changes
  4. Make sure formatting, linting and tests passes.
  5. Add tests if possible to cover the lines you added.
  6. Commit, and send a Pull Request.
"},{"location":"community/contributing/#clone-the-repository","title":"Clone the repository","text":"

Clone the hatch repository, cd into it, and create a new branch for your contribution:

cd hatch\ngit checkout -b add-my-contribution\n
"},{"location":"community/contributing/#run-the-tests","title":"Run the tests","text":"

Run the test suite while developing:

hatch run dev\n

Run the test suite with coverage report:

hatch run cov\n

Run the extended test suite with coverage:

hatch run full\n
"},{"location":"community/contributing/#lint","title":"Lint","text":"

Run automated formatting:

hatch run lint:fmt\n

Run full linting and type checking:

hatch run lint:all\n
"},{"location":"community/contributing/#docs","title":"Docs","text":"

Start the documentation in development:

hatch run docs:serve\n

Build and validate the documentation website:

hatch run docs:build-check\n
"},{"location":"community/highlights/","title":"Community highlights","text":""},{"location":"community/highlights/#integration","title":"Integration","text":""},{"location":"community/highlights/#adoption","title":"Adoption","text":""},{"location":"community/users/","title":"Users","text":"

The following is not intended to be a complete enumeration. Be sure to view the development version of this page for an up-to-date listing.

"},{"location":"community/users/#projects","title":"Projects","text":"

aiogram | Apache Airflow | argon2-cffi | attrs | Black | coffea | Colorama | Django Anymail | Django Debug Toolbar | Django NYT | Django OTP | Django OTP Agents | Django OTP Twilio | Django OTP YubiKey | Django Places | Django Wiki | FastAPI | filelock | Fluentd | github3.py | Gradio | HTTPX | iCalendar for Humans | LinkChecker | Litestar | Material for MkDocs | MicroPython | MkDocs | openSUSE | Nox | Packit | pipx | platformdirs | Pydantic | Pygments | PyHamcrest | PyMdown Extensions | Python JSON Schema | Rye | SALib | Spack | Starlette | structlog | tox | Twisted | urllib3 | Uvicorn | virtualenv | Voil\u00e0 | XGBoost | Ypy | yt-dlp

"},{"location":"community/users/#industry","title":"Industry","text":""},{"location":"community/users/#organizations","title":"Organizations","text":""},{"location":"community/users/#government","title":"Government","text":""},{"location":"community/users/#academia","title":"Academia","text":""},{"location":"community/users/#research","title":"Research","text":"