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.

If environments provide matrices, then you may use the -i/--include and -x/--exclude options 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 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.

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`
`--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`
`--preview` / `--no-preview`	boolean	Preview new rules and formatting	None
`--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

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.

Usage:

hatch run [OPTIONS] [ENV:]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] [SHELL_NAME] [SHELL_PATH] [SHELL_ARGS]...

Options:

Name	Type	Description	Default
`--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 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`