pypa-hatch/docs/config/environment/overview.md

Environment configuration

---

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

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

!!! info Environments prefixed by hatch- are used for special purposes e.g. testing.

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

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

!!! note Environments do not inherit matrices.

Self-referential environments

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

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

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",
]

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",
]

!!! tip Hatch uses pip to install dependencies so any configuration it supports Hatch does as well. For example, if you wanted to only use a private repository you could set the PIP_INDEX_URL environment variable.

Installation

Features (extras) ### {: #features }

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

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

!!! note Features/optional dependencies are also known as extras in other tools.

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

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

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"

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",
]

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"

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",
]

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",
]

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 = [
  "...",
]

Post-install

You can run commands immediately after environments install your project.

[tool.hatch.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"

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"]

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

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.