Skip to content

hatch

Usage:

hatch [OPTIONS] COMMAND [ARGS]...

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

hatch build

Build a project.

Usage:

hatch build [OPTIONS] [LOCATION]

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

hatch clean

Remove build artifacts.

Usage:

hatch clean [OPTIONS] [LOCATION]

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

hatch config

Manage the config file

Usage:

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

Options:

Name Type Description Default
--help boolean Show this message and exit. False

hatch config explore

Open the config location in your file manager.

Usage:

hatch config explore [OPTIONS]

Options:

Name Type Description Default
--help boolean Show this message and exit. False

hatch config find

Show the location of the config file.

Usage:

hatch config find [OPTIONS]

Options:

Name Type Description Default
--help boolean Show this message and exit. False

hatch config restore

Restore the config file to default settings.

Usage:

hatch config restore [OPTIONS]

Options:

Name Type Description Default
--help boolean Show this message and exit. False

hatch config set

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]

Options:

Name Type Description Default
--help boolean Show this message and exit. False

hatch config show

Show the contents of the config file.

Usage:

hatch config show [OPTIONS]

Options:

Name Type Description Default
--all, -a boolean Do not scrub secret fields False
--help boolean Show this message and exit. False

hatch config update

Update the config file with any new fields.

Usage:

hatch config update [OPTIONS]

Options:

Name Type Description Default
--help boolean Show this message and exit. False

hatch dep

Manage environment dependencies

Usage:

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

Options:

Name Type Description Default
--help boolean Show this message and exit. False

hatch dep hash

Output a hash of the currently defined dependencies.

Usage:

hatch dep hash [OPTIONS]

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

hatch dep show

Display dependencies in various formats

Usage:

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

Options:

Name Type Description Default
--help boolean Show this message and exit. False

hatch dep show requirements

Enumerate dependencies as a list of requirements.

Usage:

hatch dep show requirements [OPTIONS]

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

hatch dep show table

Enumerate dependencies in a tabular format.

Usage:

hatch dep show table [OPTIONS]

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

hatch env

Manage project environments

Usage:

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

Options:

Name Type Description Default
--help boolean Show this message and exit. False

hatch env create

Create environments.

Usage:

hatch env create [OPTIONS] [ENV_NAME]

Options:

Name Type Description Default
--help boolean Show this message and exit. False

hatch env find

Locate environments.

Usage:

hatch env find [OPTIONS] [ENV_NAME]

Options:

Name Type Description Default
--help boolean Show this message and exit. False

hatch env prune

Remove all environments.

Usage:

hatch env prune [OPTIONS]

Options:

Name Type Description Default
--help boolean Show this message and exit. False

hatch env remove

Remove environments.

Usage:

hatch env remove [OPTIONS] [ENV_NAME]

Options:

Name Type Description Default
--help boolean Show this message and exit. False

hatch env run

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:

[[tool.hatch.envs.test.matrix]]
python = ["3.9", "3.10"]
version = ["42", "3.14", "9000"]
[[envs.test.matrix]]
python = ["3.9", "3.10"]
version = ["42", "3.14", "9000"]

then running:

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

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

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

hatch env show

Show the available environments.

Usage:

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

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

hatch fmt

Format and lint source code.

Usage:

hatch fmt [OPTIONS] [ARGS]...

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

hatch new

Create or initialize a project.

Usage:

hatch new [OPTIONS] [NAME] [LOCATION]

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

hatch project

View project information

Usage:

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

Options:

Name Type Description Default
--help boolean Show this message and exit. False

hatch project metadata

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

Usage:

hatch project metadata [OPTIONS] [FIELD]

Options:

Name Type Description Default
--help boolean Show this message and exit. False

hatch publish

Publish build artifacts.

Usage:

hatch publish [OPTIONS] [ARTIFACTS]...

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

hatch python

Manage Python installations

Usage:

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

Options:

Name Type Description Default
--help boolean Show this message and exit. False

hatch python find

Locate Python binaries.

Usage:

hatch python find [OPTIONS] NAME

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

hatch python install

Install Python distributions.

You may select all to install all compatible distributions:

hatch python install all

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

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

hatch python remove

Remove Python distributions.

You may select all to remove all installed distributions:

hatch python remove all

Usage:

hatch python remove [OPTIONS] NAMES...

Options:

Name Type Description Default
--dir, -d text The directory in which distributions reside None
--help boolean Show this message and exit. False

hatch python show

Show the available Python distributions.

Usage:

hatch python show [OPTIONS]

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

hatch python update

Update Python distributions.

You may select all to update all installed distributions:

hatch python update all

Usage:

hatch python update [OPTIONS] NAMES...

Options:

Name Type Description Default
--dir, -d text The directory in which distributions reside None
--help boolean Show this message and exit. False

hatch run

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:

[[tool.hatch.envs.test.matrix]]
python = ["3.9", "3.10"]
version = ["42", "3.14", "9000"]
[[envs.test.matrix]]
python = ["3.9", "3.10"]
version = ["42", "3.14", "9000"]

then running:

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

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

Options:

Name Type Description Default
--help boolean Show this message and exit. False

hatch self

Manage Hatch

Usage:

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

Options:

Name Type Description Default
--help boolean Show this message and exit. False

hatch self report

Generate a pre-populated GitHub issue.

Usage:

hatch self report [OPTIONS]

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

hatch self restore

Restore the installation

Usage:

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

Options:

Name Type Description Default
--help boolean Show this message and exit. False

hatch self update

Install the latest version

Usage:

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

Options:

Name Type Description Default
--help boolean Show this message and exit. False

hatch shell

Enter a shell within a project's environment.

Usage:

hatch shell [OPTIONS] [ENV_NAME]

Options:

Name Type Description Default
--name text N/A None
--path text N/A None
--help boolean Show this message and exit. False

hatch status

Show information about the current environment.

Usage:

hatch status [OPTIONS]

Options:

Name Type Description Default
--help boolean Show this message and exit. False

hatch test

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:

[[tool.hatch.envs.hatch-test.matrix]]
python = ["3.9", "3.10"]
version = ["42", "3.14", "9000"]
[[envs.hatch-test.matrix]]
python = ["3.9", "3.10"]
version = ["42", "3.14", "9000"]

then running:

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

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

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

hatch version

View or set a project's version.

Usage:

hatch version [OPTIONS] [DESIRED_VERSION]

Options:

Name Type Description Default
--help boolean Show this message and exit. False