Hatch configuration¶

Configuration for Hatch itself is stored in a config.toml file located by default in one of the following platform-specific directories.

Platform	Path
macOS	`~/Library/Application Support/hatch`
Windows	`%USERPROFILE%\AppData\Local\hatch`
Unix	`$XDG_CONFIG_HOME/hatch` (the XDG_CONFIG_HOME environment variable default is `~/.config`)

You can select a custom path to the file using the --config root option or by setting the HATCH_CONFIG environment variable.

The file can be managed by the config command group.

Mode¶

The mode key controls how Hatch selects the project to work on.

Local¶

config.toml


mode = "local"

By default, Hatch will look for a pyproject.toml file in the current working directory and any parent directories. The directory storing the first found file will be considered the project root.

Project¶

config.toml


mode = "project"
project = "proj1"

[projects]
proj1 = "/path/to/project1"
proj2 = {"location": "/path/to/project2"}

[dirs]
project = ["/path/to/monorepo1", "/path/to/monorepo2"]

In this mode, Hatch will only work on the selected project. The project is located using multiple heuristics:

If the project is defined in the projects table then it must be a string, or an inline table with a location key, that is the full path to the project.
If the project matches a subdirectory in any of the directories listed in dirs.project, then that will be used as the project root.

An error will occur if the project cannot be found.

You can use the config set command to change the project you are working on:


$ hatch config set project proj2
New setting:
project = "proj2"

The project can be selected on a per-command basis with the -p/--project (environment variable HATCH_PROJECT) root option.

Aware¶

config.toml


mode = "aware"

This is essentially the local mode with a fallback to the project mode.

Shell¶

You can control the shell used to enter environments with the shell key.

If defined as a string, it must be the name of one of the supported shells and be available along your PATH.

config.toml


shell = "fish"

If the executable name of your shell differs from the supported name, you can define the shell as a table with name and path keys.

config.toml


[shell]
name = "bash"
path = "/bin/ash"

You can change the default arguments used to spawn most shells with the args key. The default for such supported shells is usually ["-i"].

config.toml


[shell]
name = "bash"
args = ["--login"]

Supported¶

Shell	Name	Arguments
Almquist shell	`ash`	`["-i"]`
Bash	`bash`	`["-i"]`
Command Prompt	`cmd`
C shell	`csh`	`["-i"]`
fish	`fish`	`["-i"]`
Nushell	`nu`	`[]`
PowerShell	`pwsh`, `powershell`
tcsh	`tcsh`	`["-i"]`
xonsh	`xonsh`	`["-i"]`
Z shell	`zsh`	`["-i"]`

Default¶

Hatch will attempt to use the current shell based on parent processes. If the shell cannot be determined, then on Windows systems Hatch will use the SHELL environment variable, if present, followed by the COMSPEC environment variable, defaulting to cmd. On all other platforms only the SHELL environment variable will be used, defaulting to bash.

Directories¶

Data¶

config.toml


[dirs]
data = "..."

This is the directory that is used to persist data. By default it is set to one of the following platform-specific directories.

Platform	Path
macOS	`~/Library/Application Support/hatch`
Windows	`%USERPROFILE%\AppData\Local\hatch`
Unix	`$XDG_DATA_HOME/hatch` (the XDG_DATA_HOME environment variable default is `~/.local/share`)

You can select a custom path to the directory using the --data-dir root option or by setting the HATCH_DATA_DIR environment variable.

Cache¶

config.toml


[dirs]
cache = "..."

This is the directory that is used to cache data. By default it is set to one of the following platform-specific directories.

Platform	Path
macOS	`~/Library/Caches/hatch`
Windows	`%USERPROFILE%\AppData\Local\hatch\Cache`
Unix	`$XDG_CACHE_HOME/hatch` (the XDG_CACHE_HOME environment variable default is `~/.cache`)

You can select a custom path to the directory using the --cache-dir root option or by setting the HATCH_CACHE_DIR environment variable.

Environments¶

config.toml


[dirs.env]
<ENV_TYPE> = "..."

This determines where to store environments, with every key being the type of environment and the value being the desired storage location.

For example, if you wanted to store virtual environments in a .virtualenvs directory within your home directory, you could specify the following:

config.toml


[dirs.env]
virtual = "~/.virtualenvs"

Any environment variables are also expanded.

If the path is not absolute, then it will be relative to the project root. So if you wanted to use a directory named .hatch in each project directory, you could do:

config.toml


[dirs.env]
virtual = ".hatch"

Any type of environment that is not explicitly defined will default to <DATA_DIR>/env/<ENV_TYPE>.

Python installations¶

config.toml


[dirs]
python = "..."

This determines where to install specific versions of Python.

The following values have special meanings:

Value	Path
`isolated` (default)	`<DATA_DIR>/pythons`

Terminal¶

You can configure how all output is displayed using the terminal.styles table. These settings are also applied to all plugins.

config.toml


[terminal.styles]
error = "..."
...

Cross-platform terminal capabilities are provided by Rich.

Output levels¶

The levels of output are as follows. Note that the verbosity indicates the minimum level at which the output is displayed.

Level	Default	Verbosity	Description
`debug`	`bold`	1 - 3	Messages that are not useful for most user experiences
`error`	`bold red`	-2	Messages indicating some unrecoverable error
`info`	`bold`	0	Messages conveying basic information
`success`	`bold cyan`	0	Messages indicating some positive outcome
`waiting`	`bold magenta`	0	Messages shown before potentially time consuming operations
`warning`	`bold yellow`	-1	Messages conveying important information

See the documentation and color reference for guidance on valid values.

Spinner¶

You can select the sequence used for waiting animations with the spinner option.

config.toml


[terminal.styles]
spinner = "..."