diff --git a/1.11/history/hatch/index.html b/1.11/history/hatch/index.html index 8c0092c8a..040493bf8 100644 --- a/1.11/history/hatch/index.html +++ b/1.11/history/hatch/index.html @@ -7,4 +7,4 @@ .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

Hatch history

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

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

Unreleased

1.11.0 - 2024-05-14

Added:

  • Upgrade PyApp to 0.21.1 for binary builds

Fixed:

  • On Linux, install the highest compatible Python distribution variant based on CPU architecture rather than assuming recent hardware

1.10.0 - 2024-05-02

Changed:

  • The run/env run, fmt and shell commands now only change the current working directory to the project root if not already inside the project
  • The shell command now accepts a single argument to specify the environment to enter which overrides the standard choice mechanisms. The arguments determining shell options have been converted to flags.

Added:

  • Add test command
  • The run command can now execute scripts that define inline metadata for dependencies and Python version constraints
  • The virtual environment type now supports the ability to use UV in place of pip & virtualenv
  • Add self report command for submitting pre-populated bug reports to GitHub
  • The reserved environment used for static analysis is now completely configurable
  • Add the following methods to the environment interface for complete control over output during life cycle management: app_status_creation, app_status_pre_installation, app_status_post_installation, app_status_project_installation, app_status_dependency_state_check, app_status_dependency_installation_check, app_status_dependency_synchronization
  • Add binaries for 32-bit versions of Windows
  • Read configuration from any ~/.pypirc file for the index publisher
  • Use the Git user as the default username for new project URL metadata
  • Add HATCH_DEBUG environment variable that when enabled will show local variables in the case of unhandled tracebacks
  • The env show command now outputs data about all internal environments when using the --json flag
  • Upgrade default CPython distributions to 20240415
  • Upgrade default PyPy distributions to 7.3.15
  • Upgrade Ruff to 0.4.2
  • Upgrade PyApp to 0.19.0 for binary builds
  • Bump the minimum supported version of Hatchling to 1.24.2
  • Bump the minimum supported version of virtualenv to 20.26.1

Fixed:

  • Maintain consistent data paths for case insensitive file systems
  • When projects derive dependencies from metadata hooks, there is now by default a status indicator for when the hooks are executed for better responsiveness
  • Properly support projects with a pyproject.toml file but no project table e.g. applications
  • Fix the fmt command when automatically installing plugin dependencies
  • Fix dependency inheritance for the template of the types environment for new projects
  • Fix warnings related to tar file extraction on Python 3.12+ when unpacking Python distributions for installation
  • De-select Ruff rule E501 for the fmt command by default since it conflicts with the formatter
  • Fix colored output from build targets on the first run (build environment creation status indicator issue)
  • Set the packaging dependency version as >=23.2 to avoid its URL validation which can conflict with context formatting
  • Fix the exit code when there happens to be an unhandled exception
  • No longer capture both stdout and stderr streams when parsing metadata payloads from build environments
  • Fix the README.md file template for new projects to avoid Markdown linting issues

1.9.7 - 2024-04-24

Fixed:

  • Limit the maximum version of virtualenv due to a backward incompatible change
  • Upgrade PyApp to 0.12.0 for binary builds

1.9.4 - 2024-03-12

Fixed:

  • Limit the maximum version of Hatchling in anticipation of backward incompatible changes

1.9.3 - 2024-01-25

Fixed:

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

1.9.2 - 2024-01-21

Fixed:

  • Fix the default token variable name for publishing to PyPI

1.9.1 - 2023-12-25

Fixed:

  • Ensure that the dependency_hash method of the environment interface is called after sync_dependencies for cases where the hash is only known at that point, such as for dependency lockers
  • Only acknowledge the HATCH_PYTHON_VARIANT_* environment variables for Python resolution for supported platforms and architectures
  • Fix Python resolution when there are metadata hooks with unsatisfied dependencies

1.9.0 - 2023-12-19

Changed:

  • Environments prefixed by hatch- are now considered internal and used for special purposes such as configuration for static analysis

Added:

  • Enable docstring formatting by default for static analysis
  • Allow for overriding config of internal environments
  • Concretely state the expected API contract for the environment interface methods find and check_compatibility
  • Upgrade Ruff to 0.1.8
  • Bump the minimum supported version of Hatchling to 1.21.0

Fixed:

  • Ignore a project's Python requirement for environments where the project is not installed
  • When not persisting config for static analysis, properly manage internal settings when Ruff's top level table already exists
  • Ignore compatibility checks when environments have already been created, significantly improving performance of environment usage
  • Properly allow overriding of the path option for the virtual environment type
  • Fix nushell activation on non-Windows systems

1.8.1 - 2023-12-14

Fixed:

  • Fix regression in calling subprocesses with updated PATH
  • Fix automatic installation of environment plugins when running as a standalone binary
  • Change default location of Python installations

1.8.0 - 2023-12-11

Changed:

  • Drop support for Python 3.7
  • The get_build_process method of the environment interface has been removed; plugins should use the new run_builder method instead
  • Remove pyperclip dependency and the --copy flag of the config find command
  • When running the build command all output from builders is now displayed as-is in real time without the stripping of ANSI codes
  • Version information (for Hatch itself) is now derived from Git

Added:

  • Support Python 3.12
  • Add installers and standalone binaries
  • Add the ability to manage Python installations
  • Add fmt command
  • The virtual environment type can now automatically download requested versions of Python that are not installed
  • Add dependency_hash method to the environment interface
  • The state of installed dependencies for environments is saved as metadata so if dependency definitions have not changed then no checking is performed, which can be computationally expensive
  • The build command now supports backends other than Hatchling
  • Allow the use of features for environments when skip-install is enabled
  • The default is now __token__ when prompting for a username for the publish command
  • Add a new run_builder method to the environment interface
  • Bump the minimum supported version of Hatchling to 1.19.0
  • Bump the minimum supported version of click to 8.0.6

Fixed:

  • Fix nushell activation
  • Better handling of flat storage directory hierarchies for the virtual environment type
  • Display useful information when running the version command outside of a project rather than erroring
  • Fix the project metadata command by only capturing stdout from the backend
  • Properly support Google Artifact Registry
  • Fix parsing dependencies for environments when warnings are emitted

1.7.0 - 2023-04-03

Changed:

  • The src-layout project template option is now enabled by default
  • Non-critical output now goes to stderr

Added:

  • Add tool.hatch.env.requires configuration to automatically install dependencies for environment and environment collector plugins
  • Add custom environment collector
  • Improve syncing of dependencies provided through Git direct references
  • Add isolated_data_directory attribute to the environment interface
  • Increase the timeout for and add retries to the index publisher
  • Expand home and environment variables in configured cache and data directories
  • Improve readability of exceptions
  • Update project templates
  • Bump the minimum supported version of Hatchling to 1.14.0

Fixed:

  • Fix displaying the version with the version command when the version is static and build dependencies are unmet
  • Fix build environments for the virtual environment type when storing within a relative path
  • Work around System Integrity Protection on macOS when running commands
  • Allow setuptools metadata migration for projects without setup.py if setup.cfg is present
  • Handle additional edge cases for setuptools metadata migration
  • Support boolean values for the config set command

1.6.3 - 2022-10-24

Fixed:

  • Fix version command when the version is dynamic and build dependencies are unmet

1.6.2 - 2022-10-20

Fixed:

  • Fix getting dynamic metadata from hooks for environments when dependencies are not dynamic

1.6.1 - 2022-10-16

Fixed:

  • Computing the path to the user's home directory now gracefully falls back to ~ when it cannot be determined

1.6.0 - 2022-10-08

Changed:

  • The run_shell_command environment interface method now accepts arbitrary subprocess.Popen keyword arguments. This is not strictly breaking, but will be utilized in upcoming features.
  • The internal directory structure for storing virtual environments is now more nested. This is not breaking, but any local environments will be created anew.

Added:

  • Add project command group to view details about the project like PEP 621 metadata
  • Better support for auto-detection of environments by tools like Visual Studio Code now that the storage directory of virtual environments will be flat if Hatch's configured virtual environment directory resides somewhere within the project root or if it is set to a .virtualenvs directory within the user's home directory
  • Build environments for the virtual environment type are now cached for improved performance
  • Add build_environment_exists method to the environment interface for implementations that cache the build environment
  • Add path option to the virtual environment type
  • Add --initialize-auth flag to the index publisher to allow for the saving of authentication information before publishing
  • Support Bash on Windows for the shell command
  • The setuptools migration script no longer modifies the formatting of existing pyproject.toml configuration
  • Bump the minimum supported version of Hatchling to 1.11.0

Fixed:

  • Environments now respect dynamically defined project dependencies
  • The dep hash and all dep show commands now respect dynamically defined project dependencies
  • The env show, dep hash, and all dep show commands now honor context formatting
  • Fix matrix variable inclusion filtering of the run and env run commands when there are multiple possible variables
  • Build environment compatibility is now checked before use
  • Decreasing verbosity now has no affect on output that should always be displayed
  • Handle more edge cases in the setuptools migration script
  • Environments now respect user defined environment variables for context formatting
  • Update the scripts in the generated test environment template for new projects to reflect the documentation
  • Allow extra-dependencies in environment overrides
  • Depend on packaging explicitly rather than relying on it being a transitive dependency of Hatchling

1.5.0 - 2022-08-28

Added:

  • The index publisher now recognizes repository-specific options
  • Add the --ignore-compat flag to the env run command
  • Setting the HATCH_PYTHON environment variable to self will now force the use of the Python executable Hatch is running on for virtual environment creation

Fixed:

  • Fix the --force-continue flag of the env run command
  • Handle more edge cases in the setuptools migration script

1.4.2 - 2022-08-16

Fixed:

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

1.4.1 - 2022-08-13

Fixed:

  • Fix non-detached inheritance disabling for environments

1.4.0 - 2022-08-06

Added:

  • The default Python for virtual environments now checks PATH before using the one Hatch is running on
  • Values for environment env-vars now support context formatting
  • Add name override for environments to allow for regular expression matching
  • The index publisher now better supports non-PyPI indices
  • Add certificate options to the index publisher
  • Display waiting text when checking dependencies and removing environments
  • Display help text the first time the shell command is executed
  • Update project templates with Python 3.11 and the latest versions of various GitHub Actions
  • Add support for Almquist (ash) shells
  • Add hyperlink as a dependency for better handling of package index URLs
  • Bump the minimum supported version of virtualenv to 20.16.2
  • Bump the minimum supported version of tomlkit to 0.11.1

Fixed:

  • Acknowledge extra-dependencies for the env show command
  • Fix locating executables within virtual environments on Debian
  • Fix managing the terminal size inside the shell command
  • Fix default code coverage file omission for the src-layout project template option

1.3.1 - 2022-07-11

Fixed:

  • Support -h/--help flag for the run command

1.3.0 - 2022-07-10

Changed:

  • Rename the default publishing plugin from pypi to the more generic index

Added:

  • Support the absence of pyproject.toml files, as is the case for apps and non-Python projects
  • Hide scripts that start with an underscore for the env show command by default
  • Ignoring the exit codes of commands by prefixing with hyphens now works with entire named scripts
  • Add a way to require confirmation for publishing
  • Add --force-continue flag to the env run command
  • Make tracebacks colorful and less verbose
  • When shell configuration has not been defined, attempt to use the current shell based on parent processes before resorting to the defaults
  • The shell name pwsh is now an alias for powershell
  • Remove atomicwrites dependency
  • Relax constraint on userpath dependency
  • Bump the minimum supported version of Hatchling to 1.4.1

Fixed:

  • Keep environments in sync with the dependencies of the selected features
  • Use utf-8 for all files generated for new projects
  • Escape special characters Git may return in the user name when writing generated files for new projects
  • Normalize the package name to lowercase in setuptools migration script
  • Fix parsing of source distributions during publishing

1.2.1 - 2022-05-30

Fixed:

  • Fix handling of top level data_files in setuptools migration script

1.2.0 - 2022-05-22

Changed:

  • The enter_shell environment plugin method now accepts an additional args parameter

Added:

  • Allow context string formatting for environment dependencies
  • Add environment context string formatting fields env_name, env_type, matrix, verbosity, and args
  • Support overriding the default arguments used to spawn shells on non-Windows systems
  • Bump the minimum supported version of Hatchling to 1.3.0

Fixed:

  • Improve setuptools migration script

1.1.2 - 2022-05-20

Fixed:

  • Bump the minimum supported version of Hatchling to 1.2.0
  • Update project metadata to reflect support for Python 3.11

1.1.1 - 2022-05-12

Fixed:

  • Fix setuptools migration script for non-Windows systems

1.1.0 - 2022-05-12

Changed:

  • In order to simplify the implementation of command execution for environment plugins, the run_shell_commands method has been replaced by the singular run_shell_command. A new command_context method has been added to more easily satisfy complex use cases.
  • The finalize_command environment plugin method has been removed in favor of the newly introduced context formatting functionality.

Added:

  • Add context formatting functionality i.e. the ability to insert values into configuration like environment variables and command line arguments
  • Any verbosity for command execution will now always display headers, even for single environments
  • Every executed command is now displayed when running multiple commands or when verbosity is enabled
  • Similar to make, ignore the exit code of executed commands that start with - (a hyphen)
  • Add ability for the --init flag of the new command to automatically migrate setuptools configuration
  • Update project metadata to reflect the adoption by PyPA and production stability

1.0.0 - 2022-04-28

This is the first stable release of Hatch v1, a complete rewrite. Enjoy!

\ No newline at end of file + body[data-md-color-scheme="slate"] .gslide-desc { color: var(--md-default-fg-color);}
Skip to content

Hatch history

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

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

Unreleased

1.11.1 - 2024-05-23

Added:

  • Add official GitHub Action for installing Hatch

Fixed:

  • Fix terminal.styles.spinner configuration
  • Fix entry points in the pre-built distributions that binaries use

1.11.0 - 2024-05-14

Added:

  • Upgrade PyApp to 0.21.1 for binary builds

Fixed:

  • On Linux, install the highest compatible Python distribution variant based on CPU architecture rather than assuming recent hardware

1.10.0 - 2024-05-02

Changed:

  • The run/env run, fmt and shell commands now only change the current working directory to the project root if not already inside the project
  • The shell command now accepts a single argument to specify the environment to enter which overrides the standard choice mechanisms. The arguments determining shell options have been converted to flags.

Added:

  • Add test command
  • The run command can now execute scripts that define inline metadata for dependencies and Python version constraints
  • The virtual environment type now supports the ability to use UV in place of pip & virtualenv
  • Add self report command for submitting pre-populated bug reports to GitHub
  • The reserved environment used for static analysis is now completely configurable
  • Add the following methods to the environment interface for complete control over output during life cycle management: app_status_creation, app_status_pre_installation, app_status_post_installation, app_status_project_installation, app_status_dependency_state_check, app_status_dependency_installation_check, app_status_dependency_synchronization
  • Add binaries for 32-bit versions of Windows
  • Read configuration from any ~/.pypirc file for the index publisher
  • Use the Git user as the default username for new project URL metadata
  • Add HATCH_DEBUG environment variable that when enabled will show local variables in the case of unhandled tracebacks
  • The env show command now outputs data about all internal environments when using the --json flag
  • Upgrade default CPython distributions to 20240415
  • Upgrade default PyPy distributions to 7.3.15
  • Upgrade Ruff to 0.4.2
  • Upgrade PyApp to 0.19.0 for binary builds
  • Bump the minimum supported version of Hatchling to 1.24.2
  • Bump the minimum supported version of virtualenv to 20.26.1

Fixed:

  • Maintain consistent data paths for case insensitive file systems
  • When projects derive dependencies from metadata hooks, there is now by default a status indicator for when the hooks are executed for better responsiveness
  • Properly support projects with a pyproject.toml file but no project table e.g. applications
  • Fix the fmt command when automatically installing plugin dependencies
  • Fix dependency inheritance for the template of the types environment for new projects
  • Fix warnings related to tar file extraction on Python 3.12+ when unpacking Python distributions for installation
  • De-select Ruff rule E501 for the fmt command by default since it conflicts with the formatter
  • Fix colored output from build targets on the first run (build environment creation status indicator issue)
  • Set the packaging dependency version as >=23.2 to avoid its URL validation which can conflict with context formatting
  • Fix the exit code when there happens to be an unhandled exception
  • No longer capture both stdout and stderr streams when parsing metadata payloads from build environments
  • Fix the README.md file template for new projects to avoid Markdown linting issues

1.9.7 - 2024-04-24

Fixed:

  • Limit the maximum version of virtualenv due to a backward incompatible change
  • Upgrade PyApp to 0.12.0 for binary builds

1.9.4 - 2024-03-12

Fixed:

  • Limit the maximum version of Hatchling in anticipation of backward incompatible changes

1.9.3 - 2024-01-25

Fixed:

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

1.9.2 - 2024-01-21

Fixed:

  • Fix the default token variable name for publishing to PyPI

1.9.1 - 2023-12-25

Fixed:

  • Ensure that the dependency_hash method of the environment interface is called after sync_dependencies for cases where the hash is only known at that point, such as for dependency lockers
  • Only acknowledge the HATCH_PYTHON_VARIANT_* environment variables for Python resolution for supported platforms and architectures
  • Fix Python resolution when there are metadata hooks with unsatisfied dependencies

1.9.0 - 2023-12-19

Changed:

  • Environments prefixed by hatch- are now considered internal and used for special purposes such as configuration for static analysis

Added:

  • Enable docstring formatting by default for static analysis
  • Allow for overriding config of internal environments
  • Concretely state the expected API contract for the environment interface methods find and check_compatibility
  • Upgrade Ruff to 0.1.8
  • Bump the minimum supported version of Hatchling to 1.21.0

Fixed:

  • Ignore a project's Python requirement for environments where the project is not installed
  • When not persisting config for static analysis, properly manage internal settings when Ruff's top level table already exists
  • Ignore compatibility checks when environments have already been created, significantly improving performance of environment usage
  • Properly allow overriding of the path option for the virtual environment type
  • Fix nushell activation on non-Windows systems

1.8.1 - 2023-12-14

Fixed:

  • Fix regression in calling subprocesses with updated PATH
  • Fix automatic installation of environment plugins when running as a standalone binary
  • Change default location of Python installations

1.8.0 - 2023-12-11

Changed:

  • Drop support for Python 3.7
  • The get_build_process method of the environment interface has been removed; plugins should use the new run_builder method instead
  • Remove pyperclip dependency and the --copy flag of the config find command
  • When running the build command all output from builders is now displayed as-is in real time without the stripping of ANSI codes
  • Version information (for Hatch itself) is now derived from Git

Added:

  • Support Python 3.12
  • Add installers and standalone binaries
  • Add the ability to manage Python installations
  • Add fmt command
  • The virtual environment type can now automatically download requested versions of Python that are not installed
  • Add dependency_hash method to the environment interface
  • The state of installed dependencies for environments is saved as metadata so if dependency definitions have not changed then no checking is performed, which can be computationally expensive
  • The build command now supports backends other than Hatchling
  • Allow the use of features for environments when skip-install is enabled
  • The default is now __token__ when prompting for a username for the publish command
  • Add a new run_builder method to the environment interface
  • Bump the minimum supported version of Hatchling to 1.19.0
  • Bump the minimum supported version of click to 8.0.6

Fixed:

  • Fix nushell activation
  • Better handling of flat storage directory hierarchies for the virtual environment type
  • Display useful information when running the version command outside of a project rather than erroring
  • Fix the project metadata command by only capturing stdout from the backend
  • Properly support Google Artifact Registry
  • Fix parsing dependencies for environments when warnings are emitted

1.7.0 - 2023-04-03

Changed:

  • The src-layout project template option is now enabled by default
  • Non-critical output now goes to stderr

Added:

  • Add tool.hatch.env.requires configuration to automatically install dependencies for environment and environment collector plugins
  • Add custom environment collector
  • Improve syncing of dependencies provided through Git direct references
  • Add isolated_data_directory attribute to the environment interface
  • Increase the timeout for and add retries to the index publisher
  • Expand home and environment variables in configured cache and data directories
  • Improve readability of exceptions
  • Update project templates
  • Bump the minimum supported version of Hatchling to 1.14.0

Fixed:

  • Fix displaying the version with the version command when the version is static and build dependencies are unmet
  • Fix build environments for the virtual environment type when storing within a relative path
  • Work around System Integrity Protection on macOS when running commands
  • Allow setuptools metadata migration for projects without setup.py if setup.cfg is present
  • Handle additional edge cases for setuptools metadata migration
  • Support boolean values for the config set command

1.6.3 - 2022-10-24

Fixed:

  • Fix version command when the version is dynamic and build dependencies are unmet

1.6.2 - 2022-10-20

Fixed:

  • Fix getting dynamic metadata from hooks for environments when dependencies are not dynamic

1.6.1 - 2022-10-16

Fixed:

  • Computing the path to the user's home directory now gracefully falls back to ~ when it cannot be determined

1.6.0 - 2022-10-08

Changed:

  • The run_shell_command environment interface method now accepts arbitrary subprocess.Popen keyword arguments. This is not strictly breaking, but will be utilized in upcoming features.
  • The internal directory structure for storing virtual environments is now more nested. This is not breaking, but any local environments will be created anew.

Added:

  • Add project command group to view details about the project like PEP 621 metadata
  • Better support for auto-detection of environments by tools like Visual Studio Code now that the storage directory of virtual environments will be flat if Hatch's configured virtual environment directory resides somewhere within the project root or if it is set to a .virtualenvs directory within the user's home directory
  • Build environments for the virtual environment type are now cached for improved performance
  • Add build_environment_exists method to the environment interface for implementations that cache the build environment
  • Add path option to the virtual environment type
  • Add --initialize-auth flag to the index publisher to allow for the saving of authentication information before publishing
  • Support Bash on Windows for the shell command
  • The setuptools migration script no longer modifies the formatting of existing pyproject.toml configuration
  • Bump the minimum supported version of Hatchling to 1.11.0

Fixed:

  • Environments now respect dynamically defined project dependencies
  • The dep hash and all dep show commands now respect dynamically defined project dependencies
  • The env show, dep hash, and all dep show commands now honor context formatting
  • Fix matrix variable inclusion filtering of the run and env run commands when there are multiple possible variables
  • Build environment compatibility is now checked before use
  • Decreasing verbosity now has no affect on output that should always be displayed
  • Handle more edge cases in the setuptools migration script
  • Environments now respect user defined environment variables for context formatting
  • Update the scripts in the generated test environment template for new projects to reflect the documentation
  • Allow extra-dependencies in environment overrides
  • Depend on packaging explicitly rather than relying on it being a transitive dependency of Hatchling

1.5.0 - 2022-08-28

Added:

  • The index publisher now recognizes repository-specific options
  • Add the --ignore-compat flag to the env run command
  • Setting the HATCH_PYTHON environment variable to self will now force the use of the Python executable Hatch is running on for virtual environment creation

Fixed:

  • Fix the --force-continue flag of the env run command
  • Handle more edge cases in the setuptools migration script

1.4.2 - 2022-08-16

Fixed:

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

1.4.1 - 2022-08-13

Fixed:

  • Fix non-detached inheritance disabling for environments

1.4.0 - 2022-08-06

Added:

  • The default Python for virtual environments now checks PATH before using the one Hatch is running on
  • Values for environment env-vars now support context formatting
  • Add name override for environments to allow for regular expression matching
  • The index publisher now better supports non-PyPI indices
  • Add certificate options to the index publisher
  • Display waiting text when checking dependencies and removing environments
  • Display help text the first time the shell command is executed
  • Update project templates with Python 3.11 and the latest versions of various GitHub Actions
  • Add support for Almquist (ash) shells
  • Add hyperlink as a dependency for better handling of package index URLs
  • Bump the minimum supported version of virtualenv to 20.16.2
  • Bump the minimum supported version of tomlkit to 0.11.1

Fixed:

  • Acknowledge extra-dependencies for the env show command
  • Fix locating executables within virtual environments on Debian
  • Fix managing the terminal size inside the shell command
  • Fix default code coverage file omission for the src-layout project template option

1.3.1 - 2022-07-11

Fixed:

  • Support -h/--help flag for the run command

1.3.0 - 2022-07-10

Changed:

  • Rename the default publishing plugin from pypi to the more generic index

Added:

  • Support the absence of pyproject.toml files, as is the case for apps and non-Python projects
  • Hide scripts that start with an underscore for the env show command by default
  • Ignoring the exit codes of commands by prefixing with hyphens now works with entire named scripts
  • Add a way to require confirmation for publishing
  • Add --force-continue flag to the env run command
  • Make tracebacks colorful and less verbose
  • When shell configuration has not been defined, attempt to use the current shell based on parent processes before resorting to the defaults
  • The shell name pwsh is now an alias for powershell
  • Remove atomicwrites dependency
  • Relax constraint on userpath dependency
  • Bump the minimum supported version of Hatchling to 1.4.1

Fixed:

  • Keep environments in sync with the dependencies of the selected features
  • Use utf-8 for all files generated for new projects
  • Escape special characters Git may return in the user name when writing generated files for new projects
  • Normalize the package name to lowercase in setuptools migration script
  • Fix parsing of source distributions during publishing

1.2.1 - 2022-05-30

Fixed:

  • Fix handling of top level data_files in setuptools migration script

1.2.0 - 2022-05-22

Changed:

  • The enter_shell environment plugin method now accepts an additional args parameter

Added:

  • Allow context string formatting for environment dependencies
  • Add environment context string formatting fields env_name, env_type, matrix, verbosity, and args
  • Support overriding the default arguments used to spawn shells on non-Windows systems
  • Bump the minimum supported version of Hatchling to 1.3.0

Fixed:

  • Improve setuptools migration script

1.1.2 - 2022-05-20

Fixed:

  • Bump the minimum supported version of Hatchling to 1.2.0
  • Update project metadata to reflect support for Python 3.11

1.1.1 - 2022-05-12

Fixed:

  • Fix setuptools migration script for non-Windows systems

1.1.0 - 2022-05-12

Changed:

  • In order to simplify the implementation of command execution for environment plugins, the run_shell_commands method has been replaced by the singular run_shell_command. A new command_context method has been added to more easily satisfy complex use cases.
  • The finalize_command environment plugin method has been removed in favor of the newly introduced context formatting functionality.

Added:

  • Add context formatting functionality i.e. the ability to insert values into configuration like environment variables and command line arguments
  • Any verbosity for command execution will now always display headers, even for single environments
  • Every executed command is now displayed when running multiple commands or when verbosity is enabled
  • Similar to make, ignore the exit code of executed commands that start with - (a hyphen)
  • Add ability for the --init flag of the new command to automatically migrate setuptools configuration
  • Update project metadata to reflect the adoption by PyPA and production stability

1.0.0 - 2022-04-28

This is the first stable release of Hatch v1, a complete rewrite. Enjoy!

\ No newline at end of file diff --git a/1.11/index.html b/1.11/index.html index 4d156c739..0ccb5cbf9 100644 --- a/1.11/index.html +++ b/1.11/index.html @@ -7,4 +7,4 @@ .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

Hatch

Hatch logo
CI/CD CI - Test CD - Build Hatch CD - Build Hatchling
Docs Docs - Release Docs - Dev
Package PyPI - Version PyPI - Downloads PyPI - Python Version
Meta Hatch project linting - Ruff types - Mypy License - MIT GitHub Sponsors

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

  • Build system

    Reproducible builds by default with a rich ecosystem of plugins

    Configure builds

  • Environments

    Robust environment management with support for custom scripts and UV

    Getting started

  • Python management

    Choose between easy manual installations or automatic as part of environments

    Try it

  • Testing

    Test execution with known best practices

    Run

  • Static analysis

    Static analysis backed by Ruff with up-to-date, sane defaults

    Learn

  • Script runner

    Execute Python scripts with specific dependencies and Python versions

    Execute

  • Publishing

    Easily upload to PyPI or other indices

    See how

  • Versioning

    Streamlined workflow for bumping versions

    Managing versions

  • Project generation

    Create new projects from templates with known best practices

    Project setup

  • Responsive CLI

    Hatch is up to 3x faster than equivalent tools

    CLI reference

License

Hatch is distributed under the terms of the MIT license.

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
  • , (comma)
  • p
 Navigate to the "previous" page
  • . (period)
  • n
 Navigate to the "next" page
  • /
  • s
 Display the search modal
\ No newline at end of file + body[data-md-color-scheme="slate"] .gslide-desc { color: var(--md-default-fg-color);}
Skip to content

Hatch

Hatch logo
CI/CD CI - Test CD - Build Hatch CD - Build Hatchling
Docs Docs - Release Docs - Dev
Package PyPI - Version PyPI - Python Version PyPI - Installs Release - Downloads
Meta Hatch project linting - Ruff types - Mypy License - MIT GitHub Sponsors

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

  • Build system

    Reproducible builds by default with a rich ecosystem of plugins

    Configure builds

  • Environments

    Robust environment management with support for custom scripts and UV

    Getting started

  • Python management

    Choose between easy manual installations or automatic as part of environments

    Try it

  • Testing

    Test execution with known best practices

    Run

  • Static analysis

    Static analysis backed by Ruff with up-to-date, sane defaults

    Learn

  • Script runner

    Execute Python scripts with specific dependencies and Python versions

    Execute

  • Publishing

    Easily upload to PyPI or other indices

    See how

  • Versioning

    Streamlined workflow for bumping versions

    Managing versions

  • Project generation

    Create new projects from templates with known best practices

    Project setup

  • Responsive CLI

    Hatch is up to 3x faster than equivalent tools

    CLI reference

License

Hatch is distributed under the terms of the MIT license.

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
  • , (comma)
  • p
 Navigate to the "previous" page
  • . (period)
  • n
 Navigate to the "next" page
  • /
  • s
 Display the search modal
\ No newline at end of file diff --git a/1.11/install/index.html b/1.11/install/index.html index 9fac5c7ac..54726d320 100644 --- a/1.11/install/index.html +++ b/1.11/install/index.html @@ -7,19 +7,21 @@ .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

Installation

Installers

  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
-1.11.0
-

  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 -o hatch-universal.pkg https://github.com/pypa/hatch/releases/latest/download/hatch-universal.pkg
+    body[data-md-color-scheme="slate"] .gslide-desc { color: var(--md-default-fg-color);}      
     
      
       
     
     
     
     
     
     
      
     
     
     
     
     
      
     
     
     
     
        
    Installation
     
     
    GitHub Actions
     
    - name: Install Hatch
+  uses: pypa/hatch@install
+
     
    Refer to the official action for more information.
     
    Installers
     
     
     
     
     
     
     
       
    1. In your browser, download the .pkg file: hatch-universal.pkg
      2.  
    2. Run your downloaded file and follow the on-screen instructions.
      3.  
    3. Restart your terminal.
      4.  
    4.  
      To verify that the shell can find and run the hatch command in your PATH, use the following command.
       
      $ hatch --version
+1.11.1
+
       
      5.  
     
     
     
       
    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
 
       
      2.  
    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 /
 
       
      3.  
    3.  
      Restart your terminal.
       
      4.  
    4.  
      To verify that the shell can find and run the hatch command in your PATH, use the following command.
       
      $ hatch --version
-1.11.0
+1.11.1
 
       
      5.  
     
     
     
     
     
     
     
     
     
       
    1. In your browser, download one the .msi files: 
      2.  
    2. Run your downloaded file and follow the on-screen instructions.
      3.  
    3. Restart your terminal.
      4.  
    4.  
      To verify that the shell can find and run the hatch command in your PATH, use the following command.
       
      $ hatch --version
-1.11.0
+1.11.1
 
       
      5.  
     
     
     
       
    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.
       
       
       
       
      msiexec /passive /i https://github.com/pypa/hatch/releases/latest/download/hatch-x64.msi
 
       
       
       
      msiexec /passive /i https://github.com/pypa/hatch/releases/latest/download/hatch-x86.msi
 
       
       
       
       
      2.  
    2.  
      Restart your terminal.
       
      3.  
    3.  
      To verify that the shell can find and run the hatch command in your PATH, use the following command.
       
      $ hatch --version
-1.11.0
-
       
      4.  
     
     
     
     
     
     
     
    Standalone binaries
     
    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.
     
     
     
      
     
      
     
      
     
     
     
    pip
     
    Hatch is available on PyPI and can be installed with pip.
     
    pip install hatch
+1.11.1
+

Standalone binaries

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.

pip

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

pip install hatch

Warning

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

pipx

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

pipx install hatch

Homebrew

See the formula for more details.

brew install hatch

Conda

See the feedstock for more details.

conda install -c conda-forge hatch
@@ -27,4 +29,4 @@

Warning

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

MacPorts

See the port for more details.

sudo port install hatch

Fedora

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

sudo dnf install hatch

Void Linux

xbps-install hatch
-

Build system availability

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

Packaging status

\ No newline at end of file +

Build system availability

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

Packaging status

\ No newline at end of file diff --git a/1.11/plugins/builder/wheel/index.html b/1.11/plugins/builder/wheel/index.html index af599f1a3..25c8e0865 100644 --- a/1.11/plugins/builder/wheel/index.html +++ b/1.11/plugins/builder/wheel/index.html @@ -9,4 +9,4 @@ 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

Wheel builder

A wheel is a binary distribution of a Python package that can be installed directly into an environment.

Configuration

The builder plugin name is wheel.

[tool.hatch.build.targets.wheel]
 
[build.targets.wheel]
-

Options

Option Default Description
core-metadata-version "2.3" The version of core metadata to use
shared-data A mapping similar to the forced inclusion option corresponding to the data subdirectory within the standard data directory that will be installed globally in a given Python environment, usually under sys.prefix
shared-scripts A mapping similar to the forced inclusion option corresponding to the scripts subdirectory within the standard data directory that will be installed in a given Python environment, usually under Scripts on Windows or bin otherwise, and would normally be available on PATH
extra-metadata A mapping similar to the forced inclusion option corresponding to extra metadata that will be shipped in a directory named extra_metadata
strict-naming true Whether or not file names should contain the normalized version of the project name
macos-max-compat true Whether or not on macOS, when build hooks have set the infer_tag build data, the wheel name should signal broad support rather than specific versions for newer SDK versions.

Note: The default will become false, and this option eventually removed, sometime after consumers like pip start supporting these newer SDK versions.
bypass-selection false Whether or not to suppress the error when one has not defined any file selection options and all heuristics have failed to determine what to ship

Versions

Version Description
standard (default) The latest standardized format
editable A wheel that only ships .pth files or import hooks for real-time development

Default file selection

When the user has not set any file selection options, the project name will be used to determine the package to ship in the following heuristic order:

  1. <NAME>/__init__.py
  2. src/<NAME>/__init__.py
  3. <NAME>.py
  4. <NAMESPACE>/<NAME>/__init__.py

If none of these heuristics are satisfied, an error will be raised.

Reproducibility

Reproducible builds are supported.

Build data

This is data that can be modified by build hooks.

Data Default Description
tag The full tag part of the filename (e.g. py3-none-any), defaulting to a cross-platform wheel with the supported major versions of Python based on project metadata
infer_tag False When tag is not set, this may be enabled to use the one most specific to the platform, Python interpreter, and ABI
pure_python True Whether or not to write metadata indicating that the package does not contain any platform-specific files
dependencies Extra project dependencies
shared_data Additional shared-data entries, which take precedence in case of conflicts
shared_scripts Additional shared-scripts entries, which take precedence in case of conflicts
extra_metadata Additional extra-metadata entries, which take precedence in case of conflicts
force_include_editable Similar to the force_include option but specifically for the editable version and takes precedence
\ No newline at end of file +

Options

Option Default Description
core-metadata-version "2.3" The version of core metadata to use
shared-data A mapping similar to the forced inclusion option corresponding to the data subdirectory within the standard data directory that will be installed globally in a given Python environment, usually under sys.prefix
shared-scripts A mapping similar to the forced inclusion option corresponding to the scripts subdirectory within the standard data directory that will be installed in a given Python environment, usually under Scripts on Windows or bin otherwise, and would normally be available on PATH
extra-metadata A mapping similar to the forced inclusion option corresponding to extra metadata that will be shipped in a directory named extra_metadata
strict-naming true Whether or not file names should contain the normalized version of the project name
macos-max-compat false Whether or not on macOS, when build hooks have set the infer_tag build data, the wheel name should signal broad support rather than specific versions for newer SDK versions.

Note: This option will eventually be removed.
bypass-selection false Whether or not to suppress the error when one has not defined any file selection options and all heuristics have failed to determine what to ship

Versions

Version Description
standard (default) The latest standardized format
editable A wheel that only ships .pth files or import hooks for real-time development

Default file selection

When the user has not set any file selection options, the project name will be used to determine the package to ship in the following heuristic order:

  1. <NAME>/__init__.py
  2. src/<NAME>/__init__.py
  3. <NAME>.py
  4. <NAMESPACE>/<NAME>/__init__.py

If none of these heuristics are satisfied, an error will be raised.

Reproducibility

Reproducible builds are supported.

Build data

This is data that can be modified by build hooks.

Data Default Description
tag The full tag part of the filename (e.g. py3-none-any), defaulting to a cross-platform wheel with the supported major versions of Python based on project metadata
infer_tag False When tag is not set, this may be enabled to use the one most specific to the platform, Python interpreter, and ABI
pure_python True Whether or not to write metadata indicating that the package does not contain any platform-specific files
dependencies Extra project dependencies
shared_data Additional shared-data entries, which take precedence in case of conflicts
shared_scripts Additional shared-scripts entries, which take precedence in case of conflicts
extra_metadata Additional extra-metadata entries, which take precedence in case of conflicts
force_include_editable Similar to the force_include option but specifically for the editable version and takes precedence
\ No newline at end of file diff --git a/1.11/search/search_index.json b/1.11/search/search_index.json index 5c63f88d4..d73cbf62f 100644 --- a/1.11/search/search_index.json +++ b/1.11/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 = [\"2.7\", \"3.8\"]\nversion = [\"42\", \"3.14\"]\n\n[[tool.hatch.envs.test.matrix]]\npython = [\"3.8\", \"3.9\"]\nversion = [\"9000\"]\nfeatures = [\"foo\", \"bar\"]\n
[envs.test]\ndependencies = [\n  \"pytest\"\n]\n\n[[envs.test.matrix]]\npython = [\"2.7\", \"3.8\"]\nversion = [\"42\", \"3.14\"]\n\n[[envs.test.matrix]]\npython = [\"3.8\", \"3.9\"]\nversion = [\"9000\"]\nfeatures = [\"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.py2.7-42       | pytest       |\n|      |         | test.py2.7-3.14     |              |\n|      |         | test.py3.8-42       |              |\n|      |         | test.py3.8-3.14     |              |\n|      |         | test.py3.8-9000-foo |              |\n|      |         | test.py3.8-9000-bar |              |\n|      |         | test.py3.9-9000-foo |              |\n|      |         | test.py3.9-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/#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.11.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 -o 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.11.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.11.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.11.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.

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

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.

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=....

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 Wiki | FastAPI | filelock | github3.py | Gradio | HTTPX | iCalendar for Humans | LinkChecker | Litestar | Material for MkDocs | 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

"},{"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":"