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
--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
--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
--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
--copy, -c boolean Copy the path to the config file to the clipboard False
--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:

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

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