diff --git a/dev/config/environment/advanced/index.html b/dev/config/environment/advanced/index.html index c64ed36e0..d15e314d9 100644 --- a/dev/config/environment/advanced/index.html +++ b/dev/config/environment/advanced/index.html @@ -13,11 +13,11 @@ ] [[tool.hatch.envs.test.matrix]] -python = ["2.7", "3.8"] +python = ["3.10", "3.11"] version = ["42", "3.14"] [[tool.hatch.envs.test.matrix]] -python = ["3.8", "3.9"] +python = ["3.11", "3.12"] version = ["9000"] feature = ["foo", "bar"] 
[envs.test]
@@ -26,11 +26,11 @@
 ]
 
 [[envs.test.matrix]]
-python = ["2.7", "3.8"]
+python = ["3.10", "3.11"]
 version = ["42", "3.14"]
 
 [[envs.test.matrix]]
-python = ["3.8", "3.9"]
+python = ["3.11", "3.12"]
 version = ["9000"]
 feature = ["foo", "bar"]

Doing so will result in the product of each variable combination being its own environment.

Naming

The name of the generated environments will be the variable values of each combination separated by hyphens, altogether prefixed by <ENV_NAME>.. For example, the following configuration:

[[tool.hatch.envs.test.matrix]]
@@ -74,7 +74,7 @@
 cov = 'pytest --cov-report=term-missing --cov-config=pyproject.toml --cov=pkg --cov=tests'
 
 [[tool.hatch.envs.test.matrix]]
-python = ["2.7", "3.8"]
+python = ["3.11", "3.12"]
 version = ["42", "3.14"]
 
[envs.test]
 dependencies = [
@@ -87,7 +87,7 @@
 cov = 'pytest --cov-report=term-missing --cov-config=pyproject.toml --cov=pkg --cov=tests'
 
 [[envs.test.matrix]]
-python = ["2.7", "3.8"]
+python = ["3.11", "3.12"]
 version = ["42", "3.14"]

you could then run your tests consecutively in all 4 environments with:

hatch run test:cov

Option overrides

You can modify options based on the conditions of different sources like matrix variables with the overrides table, using dotted key syntax for each declaration:

[tool.hatch.envs.<ENV_NAME>.overrides]
@@ -114,7 +114,7 @@
 ]
 
 [[tool.hatch.envs.test.matrix]]
-python = ["2.7", "3.8"]
+python = ["3.11", "3.12"]
 version = ["legacy", "latest"]
 auth = ["oauth2", "kerberos", "noauth"]
 
[envs.test.overrides]
@@ -125,7 +125,7 @@
 ]
 
 [[envs.test.matrix]]
-python = ["2.7", "3.8"]
+python = ["3.11", "3.12"]
 version = ["legacy", "latest"]
 auth = ["oauth2", "kerberos", "noauth"]

Name overrides

When a matrix is defined, the name source can be used for regular expression matching on the generated name, minus the prefix for non-default environments.

[tool.hatch.envs.test.overrides]
@@ -232,6 +232,6 @@
 
 [[envs.test.matrix]]
 version = ["42", "3.14"]
-
\ No newline at end of file diff --git a/dev/environment/index.html b/dev/environment/index.html index fc2f329c0..40745f827 100644 --- a/dev/environment/index.html +++ b/dev/environment/index.html @@ -58,26 +58,26 @@ ] [[tool.hatch.envs.test.matrix]] -python = ["2.7", "3.8"] +python = ["3.10", "3.11"] version = ["42", "3.14"] [[tool.hatch.envs.test.matrix]] -python = ["3.8", "3.9"] +python = ["3.11", "3.12"] version = ["9000"] -features = ["foo", "bar"] +feature = ["foo", "bar"] 
[envs.test]
 dependencies = [
   "pytest"
 ]
 
 [[envs.test.matrix]]
-python = ["2.7", "3.8"]
+python = ["3.10", "3.11"]
 version = ["42", "3.14"]
 
 [[envs.test.matrix]]
-python = ["3.8", "3.9"]
+python = ["3.11", "3.12"]
 version = ["9000"]
-features = ["foo", "bar"]
+feature = ["foo", "bar"]

Using the env show command would then display:

$ hatch env show --ascii
      Standalone
 +---------+---------+
@@ -85,19 +85,19 @@
 +=========+=========+
 | default | virtual |
 +---------+---------+
-                       Matrices
-+------+---------+---------------------+--------------+
-| Name | Type    | Envs                | Dependencies |
-+======+=========+=====================+==============+
-| test | virtual | test.py2.7-42       | pytest       |
-|      |         | test.py2.7-3.14     |              |
-|      |         | test.py3.8-42       |              |
-|      |         | test.py3.8-3.14     |              |
-|      |         | test.py3.8-9000-foo |              |
-|      |         | test.py3.8-9000-bar |              |
-|      |         | test.py3.9-9000-foo |              |
-|      |         | test.py3.9-9000-bar |              |
-+------+---------+---------------------+--------------+
-

Removal

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.

\ No newline at end of file diff --git a/dev/meta/faq/index.html b/dev/meta/faq/index.html index 3247fae29..1cf405e3a 100644 --- a/dev/meta/faq/index.html +++ b/dev/meta/faq/index.html @@ -106,8 +106,8 @@

Environments

Invocation:

tox
 
[tox]
 envlist =
-    py{27,38}-{42,3.14}
-    py{38,39}-{9000}-{foo,bar}
+    py{38,39}-{42,3.14}
+    py{39,310}-{9000}-{foo,bar}
 
 [testenv]
 usedevelop = true
@@ -136,19 +136,19 @@
 
 [tool.hatch.envs.default.overrides]
 matrix.version.env-vars = "PRODUCT_VERSION"
-matrix.features.env-vars = "EXPERIMENTAL=true"
-matrix.features.dependencies = [
+matrix.feature.env-vars = "EXPERIMENTAL=true"
+matrix.feature.dependencies = [
   { value = "cryptography", if = ["foo"] },
 ]
 
 [[tool.hatch.envs.default.matrix]]
-python = ["2.7", "3.8"]
+python = ["3.8", "3.9"]
 version = ["42", "3.14"]
 
 [[tool.hatch.envs.default.matrix]]
-python = ["3.8", "3.9"]
+python = ["3.9", "3.10"]
 version = ["9000"]
-features = ["foo", "bar"]
+feature = ["foo", "bar"]
 
[envs.default]
 dependencies = [
   "coverage[toml]",
@@ -161,19 +161,19 @@
 
 [envs.default.overrides]
 matrix.version.env-vars = "PRODUCT_VERSION"
-matrix.features.env-vars = "EXPERIMENTAL=true"
-matrix.features.dependencies = [
+matrix.feature.env-vars = "EXPERIMENTAL=true"
+matrix.feature.dependencies = [
   { value = "cryptography", if = ["foo"] },
 ]
 
 [[envs.default.matrix]]
-python = ["2.7", "3.8"]
+python = ["3.8", "3.9"]
 version = ["42", "3.14"]
 
 [[envs.default.matrix]]
-python = ["3.8", "3.9"]
+python = ["3.9", "3.10"]
 version = ["9000"]
-features = ["foo", "bar"]
-

Fast CLI?

The claim about being faster than other tools is based on timings that are always checked in CI.

Hatch achieves this by using lazy imports, lazily performing computation manually and with functools.cached_property, using hacks like not not ... instead of bool(...), etc.

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

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

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

Hatch is distributed under the terms of the MIT license.

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

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

Also, desktop readers can use special keyboard shortcuts:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Tip

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

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

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

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

Tip

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

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

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

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

Now confirm the project has been installed:

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

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

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

You can type exit to leave the environment.

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

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

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

Tip

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

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

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

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

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

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

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

Note

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

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

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

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

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

you could then serve your documentation by running:

hatch run docs:serve\n

Tip

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

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

Every environment can define its own set of matrices:

pyproject.toml hatch.toml 
[tool.hatch.envs.test]\ndependencies = [\n  \"pytest\"\n]\n\n[[tool.hatch.envs.test.matrix]]\npython = [\"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/#github-actions","title":"GitHub Actions","text":"
- name: Install Hatch\n  uses: pypa/hatch@install\n

Refer to the official action for more information.

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

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

    $ hatch --version\n1.11.1\n

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

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

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

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

  3. Restart your terminal.

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

    $ hatch --version\n1.11.1\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.1\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.1\n
"},{"location":"install/#standalone-binaries","title":"Standalone binaries","text":"

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

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

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

pip install hatch\n

Warning

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

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

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

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

See the formula for more details.

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

See the feedstock for more details.

conda install -c conda-forge hatch\n

or with mamba:

mamba install hatch\n

Warning

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

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

See the port for more details.

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

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

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

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

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

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

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

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

hatch new \"Hatch Demo\"\n

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

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

Tip

There are many ways to customize project generation.

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

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

hatch new --init\n

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

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

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

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

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

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

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

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

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

Tip

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

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

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

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

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

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

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

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

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

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

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

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

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

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

You can instead pass specific paths as arguments:

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

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

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

Please refer to the publisher plugin reference for configuration options.

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

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

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

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

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

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

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

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

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

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

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

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

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

You can update the version like so:

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

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

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

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

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

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

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

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

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

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

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

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

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

Why not?:

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

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

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

Why not?:

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

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

Here we compare Python management to that of pyenv.

Why not?:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

As an example, consider the following script:

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

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

hatch run script.py\n

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

See the how-to guide for more information.

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

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

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

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

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

See the how-to guide for detailed instructions.

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

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

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

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

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

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

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

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

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

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

Upcoming features include:

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

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

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

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

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

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

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

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

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

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

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

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

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

hatch project metadata readme\n

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

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

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

For example, if you define the following Hatch configuration:

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

and the following matrix:

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

then locating environments with the following command:

hatch env find test\n

will show that the general directory structure is:

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

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

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

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

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

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

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

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

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

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

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

This use case comes from Project Jupyter:

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

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

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

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

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

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

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

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

Windows signing

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The levels are documented here.

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

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

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

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

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

BashZ shellfish

Save the script somewhere:

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

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

. ~/.hatch-complete.bash\n

Save the script somewhere:

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

Source the file in ~/.zshrc:

. ~/.hatch-complete.zsh\n

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

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

Usage:

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

Options:

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

Build a project.

Usage:

hatch build [OPTIONS] [LOCATION]\n

Options:

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

Remove build artifacts.

Usage:

hatch clean [OPTIONS] [LOCATION]\n

Options:

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

Manage the config file

Usage:

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

Options:

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

Open the config location in your file manager.

Usage:

hatch config explore [OPTIONS]\n

Options:

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

Show the location of the config file.

Usage:

hatch config find [OPTIONS]\n

Options:

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

Restore the config file to default settings.

Usage:

hatch config restore [OPTIONS]\n

Options:

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

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

Usage:

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

Options:

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

Show the contents of the config file.

Usage:

hatch config show [OPTIONS]\n

Options:

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

Update the config file with any new fields.

Usage:

hatch config update [OPTIONS]\n

Options:

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

Manage environment dependencies

Usage:

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

Options:

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

Output a hash of the currently defined dependencies.

Usage:

hatch dep hash [OPTIONS]\n

Options:

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

Display dependencies in various formats

Usage:

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

Options:

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

Enumerate dependencies as a list of requirements.

Usage:

hatch dep show requirements [OPTIONS]\n

Options:

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

Enumerate dependencies in a tabular format.

Usage:

hatch dep show table [OPTIONS]\n

Options:

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

Manage project environments

Usage:

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

Options:

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

Create environments.

Usage:

hatch env create [OPTIONS] [ENV_NAME]\n

Options:

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

Locate environments.

Usage:

hatch env find [OPTIONS] [ENV_NAME]\n

Options:

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

Remove all environments.

Usage:

hatch env prune [OPTIONS]\n

Options:

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

Remove environments.

Usage:

hatch env remove [OPTIONS] [ENV_NAME]\n

Options:

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

Run commands within project environments.

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

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

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

then running:

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

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

Note

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

Usage:

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

Options:

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

Show the available environments.

Usage:

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

Options:

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

Format and lint source code.

Usage:

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

Options:

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

Create or initialize a project.

Usage:

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

Options:

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

View project information

Usage:

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

Options:

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

Display project metadata.

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

hatch project metadata | jq -r .readme\n

Usage:

hatch project metadata [OPTIONS] [FIELD]\n

Options:

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

Publish build artifacts.

Usage:

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

Options:

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

Manage Python installations

Usage:

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

Options:

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

Locate Python binaries.

Usage:

hatch python find [OPTIONS] NAME\n

Options:

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

Install Python distributions.

You may select all to install all compatible distributions:

hatch python install all\n

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

Usage:

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

Options:

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

Remove Python distributions.

You may select all to remove all installed distributions:

hatch python remove all\n

Usage:

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

Options:

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

Show the available Python distributions.

Usage:

hatch python show [OPTIONS]\n

Options:

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

Update Python distributions.

You may select all to update all installed distributions:

hatch python update all\n

Usage:

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

Options:

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

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

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

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

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

then running:

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

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

Note

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

Usage:

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

Options:

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

Manage Hatch

Usage:

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

Options:

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

Generate a pre-populated GitHub issue.

Usage:

hatch self report [OPTIONS]\n

Options:

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

Restore the installation

Usage:

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

Options:

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

Install the latest version

Usage:

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

Options:

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

Enter a shell within a project's environment.

Usage:

hatch shell [OPTIONS] [ENV_NAME]\n

Options:

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

Show information about the current environment.

Usage:

hatch status [OPTIONS]\n

Options:

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

Run tests using the hatch-test environment matrix.

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

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

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

then running:

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

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

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

Note

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

Usage:

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

Options:

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

View or set a project's version.

Usage:

hatch version [OPTIONS] [DESIRED_VERSION]\n

Options:

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

The usual process to make a contribution is to:

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

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

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

Run the test suite while developing:

hatch run dev\n

Run the test suite with coverage report:

hatch run cov\n

Run the extended test suite with coverage:

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

Run automated formatting:

hatch run lint:fmt\n

Run full linting and type checking:

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

Start the documentation in development:

hatch run docs:serve\n

Build and validate the documentation website:

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

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

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

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

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