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:

pyproject.toml hatch.toml

[[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:

pyproject.toml hatch.toml

[[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:

pyproject.toml hatch.toml

[[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
`--force`, `-f`	boolean	Allow an explicit downgrading version to be given	`False`
`--help`	boolean	Show this message and exit.	`False`