Environment configuration¶

All environments are defined as sections within the tool.hatch.envs table.

[tool.hatch.envs.<ENV_NAME>]

[envs.<ENV_NAME>]

The storage location for environments is completely configurable.

Unless an environment is explicitly selected on the command line, the default environment will be used. The type of this environment defaults to virtual.

Inheritance¶

All environments inherit from the environment defined by its template option, which defaults to default.

So for the following configuration:

[tool.hatch.envs.foo]
type = "baz"
skip-install = true

[tool.hatch.envs.bar]
template = "foo"
skip-install = false

[envs.foo]
type = "baz"
skip-install = true

[envs.bar]
template = "foo"
skip-install = false

the environment bar will be of type baz with skip-install set to false.

Self-referential environments¶

You can disable inheritance by setting template to the environment's own name:

[tool.hatch.envs.foo]
template = "foo"

[envs.foo]
template = "foo"

Detached environments¶

A common use case is standalone environments that do not require inheritance nor the installation of the project, such as for linting or sometimes building documentation. Enabling the detached option will make the environment self-referential and will skip project installation:

[tool.hatch.envs.lint]
detached = true

[envs.lint]
detached = true

Dependencies¶

You can install dependencies in addition to the ones defined by your project's metadata. Entries support context formatting.

[tool.hatch.envs.test]
dependencies = [
  "coverage[toml]",
  "pytest",
  "pytest-cov",
  "pytest-mock",
]

[envs.test]
dependencies = [
  "coverage[toml]",
  "pytest",
  "pytest-cov",
  "pytest-mock",
]

If you define environments with dependencies that only slightly differ from their inherited environments, you can use the extra-dependencies option to avoid redeclaring the dependencies option:

[tool.hatch.envs.default]
dependencies = [
  "foo",
  "bar",
]

[tool.hatch.envs.experimental]
extra-dependencies = [
  "baz",
]

[envs.default]
dependencies = [
  "foo",
  "bar",
]

[envs.experimental]
extra-dependencies = [
  "baz",
]

Installation¶

Features (extras)¶

If your project defines optional dependencies, you can select which groups to install using the features option:

[tool.hatch.envs.nightly]
features = [
  "server",
  "grpc",
]

[envs.nightly]
features = [
  "server",
  "grpc",
]

Dev mode¶

By default, environments will always reflect the current state of your project on disk, for example, by installing it in editable mode in a Python environment. Set dev-mode to false to disable this behavior and have your project installed only upon creation of a new environment. From then on, you need to manage your project installation manually.

[tool.hatch.envs.static]
dev-mode = false

[envs.static]
dev-mode = false

Skip install¶

By default, environments will install your project during creation. To ignore this step, set skip-install to true:

[tool.hatch.envs.lint]
skip-install = true

[envs.lint]
skip-install = true

Environment variables¶

Defined¶

You can define environment variables with the env-vars option:

[tool.hatch.envs.docs]
dependencies = [
  "mkdocs"
]
[tool.hatch.envs.docs.env-vars]
SOURCE_DATE_EPOCH = "1580601600"

[envs.docs]
dependencies = [
  "mkdocs"
]
[envs.docs.env-vars]
SOURCE_DATE_EPOCH = "1580601600"

Values support context formatting.

Filters¶

By default, environments will have access to all environment variables. You can filter with wildcard patterns using the env-include/env-exclude options:

[tool.hatch.envs.<ENV_NAME>]
env-include = [
  "FOO*",
]
env-exclude = [
  "BAR",
]

[envs.<ENV_NAME>]
env-include = [
  "FOO*",
]
env-exclude = [
  "BAR",
]

Exclusion patterns take precedence but will never affect defined environment variables.

Scripts¶

You can define named scripts that may be executed or referenced at the beginning of other scripts. Context formatting is supported.

For example, in the following configuration:

[tool.hatch.envs.test]
dependencies = [
  "coverage[toml]",
  "pytest",
  "pytest-cov",
  "pytest-mock",
]
[tool.hatch.envs.test.scripts]
run-coverage = "pytest --cov-config=pyproject.toml --cov=pkg --cov=tests"
run = "run-coverage --no-cov"

[envs.test]
dependencies = [
  "coverage[toml]",
  "pytest",
  "pytest-cov",
  "pytest-mock",
]
[envs.test.scripts]
run-coverage = "pytest --cov-config=pyproject.toml --cov=pkg --cov=tests"
run = "run-coverage --no-cov"

the run script would be expanded to:

pytest --cov-config=pyproject.toml --cov=pkg --cov=tests --no-cov

Scripts can also be defined as an array of strings.

[tool.hatch.envs.style]
detached = true
dependencies = [
  "flake8",
  "black",
  "isort",
]
[tool.hatch.envs.style.scripts]
check = [
  "flake8 .",
  "black --check --diff .",
  "isort --check-only --diff .",
]
fmt = [
  "isort .",
  "black .",
  "check",
]

[envs.style]
detached = true
dependencies = [
  "flake8",
  "black",
  "isort",
]
[envs.style.scripts]
check = [
  "flake8 .",
  "black --check --diff .",
  "isort --check-only --diff .",
]
fmt = [
  "isort .",
  "black .",
  "check",
]

Similar to make, you can ignore the exit code of commands that start with - (a hyphen). For example, the script error defined by the following configuration would halt after the second command with 3 as the exit code:

[tool.hatch.envs.test.scripts]
error = [
  "- exit 1",
  "exit 3",
  "exit 0",
]

[envs.test.scripts]
error = [
  "- exit 1",
  "exit 3",
  "exit 0",
]

Extra scripts¶

Individual scripts inherit from parent environments just like options. To guarantee that individual scripts do not override those defined by parent environments, you can use the extra-scripts option instead which is only capable of adding scripts that have not been defined.

Commands¶

All commands are able to use any defined scripts. Also like scripts, context formatting is supported and the exit code of commands that start with a hyphen will be ignored.

Pre-install¶

You can run commands immediately before environments install your project.

[tool.hatch.envs.<ENV_NAME>]
pre-install-commands = [
  "...",
]

[envs.<ENV_NAME>]
pre-install-commands = [
  "...",
]

Post-install¶

You can run commands immediately after environments install your project.

[tool.hatch.envs.<ENV_NAME>]
post-install-commands = [
  "...",
]

[envs.<ENV_NAME>]
post-install-commands = [
  "...",
]

Python version¶

The python option specifies which version of Python to use, or an absolute path to a Python interpreter:

[tool.hatch.envs.<ENV_NAME>]
python = "3.10"

[envs.<ENV_NAME>]
python = "3.10"

All environment types should respect this option.

Supported platforms¶

The platforms option indicates the operating systems with which the environment is compatible:

[tool.hatch.envs.<ENV_NAME>]
platforms = ["linux", "windows", "macos"]

[envs.<ENV_NAME>]
platforms = ["linux", "windows", "macos"]

The following platforms are supported:

• linux
• windows
• macos

If unspecified, the environment is assumed to be compatible with all platforms.

Description¶

The description option is purely informational and is displayed in the output of the env show command:

[tool.hatch.envs.<ENV_NAME>]
description = """
Lorem ipsum ...
"""

[envs.<ENV_NAME>]
description = """
Lorem ipsum ...
"""

Type¶

An environment's type determines which environment plugin will be used for management. The only built-in environment type is virtual, which uses virtual Python environments.