Environments¶

Environments are designed to allow for isolated workspaces for testing, building documentation, or anything else projects need.

Unless an environment is chosen explicitly, Hatch will use the default environment.

Tip

For a more comprehensive walk-through, see the Basic usage tutorial.

Creation¶

You can create environments by using the env create command. Let's enter the directory of the project we created in the setup phase:

$ hatch env create
Creating environment: default
Installing project in development mode
Syncing dependencies

Tip

You never need to manually create environments as spawning a shell or running commands within one will automatically trigger creation.

Entering environments¶

You can spawn a shell within an environment by using the shell command.

$ hatch shell
(hatch-demo) $

Now confirm the project has been installed:

(hatch-demo) $ pip show hatch-demo
Name: hatch-demo
Version: 0.0.1
...

Finally, see where your environment's Python is located:

(hatch-demo) $ python -c "import sys;print(sys.executable)"
...

You can type exit to leave the environment.

Command execution¶

The run command allows you to execute commands in an environment as if you had already entered it. For example, running the following command will output the same path as before:

hatch run python -c "import sys;print(sys.executable)"

Tip

Be sure to check out how to define scripts for your project.

Dependencies¶

Hatch ensures that environments are always compatible with the currently defined project dependencies (if installed and in dev mode) and environment dependencies.

To add cowsay as a dependency, open pyproject.toml and add it to the dependencies array:

pyproject.toml

[project]
...
dependencies = [
  "cowsay"
]

This dependency will be installed the next time you spawn a shell or run a command. For example:

$ hatch run cowsay -t "Hello, world!"
Syncing dependencies
  _____________
| Hello, world! |
  =============
             \
              \
                ^__^
                (oo)\_______
                (__)\       )\/\
                    ||----w |
                    ||     ||

Note

The Syncing dependencies status will display temporarily when Hatch updates environments in response to any dependency changes that you make.

Selection¶

You can select which environment to enter or run commands in by using the -e/--env root option or by setting the HATCH_ENV environment variable.

The run command allows for more explicit selection by prepending <ENV_NAME>: to commands. For example, if you had the following configuration:

pyproject.toml hatch.toml

[tool.hatch.envs.docs]
dependencies = [
  "mkdocs"
]
[tool.hatch.envs.docs.scripts]
build = "mkdocs build --clean --strict"
serve = "mkdocs serve --dev-addr localhost:8000"

[envs.docs]
dependencies = [
  "mkdocs"
]
[envs.docs.scripts]
build = "mkdocs build --clean --strict"
serve = "mkdocs serve --dev-addr localhost:8000"

you could then serve your documentation by running:

hatch run docs:serve

Tip

If you've already entered an environment, commands will target it by default.

Matrix¶

Every environment can define its own set of matrices:

pyproject.toml hatch.toml

[tool.hatch.envs.test]
dependencies = [
  "pytest"
]

[[tool.hatch.envs.test.matrix]]
python = ["3.10", "3.11"]
version = ["42", "3.14"]

[[tool.hatch.envs.test.matrix]]
python = ["3.11", "3.12"]
version = ["9000"]
feature = ["foo", "bar"]

[envs.test]
dependencies = [
  "pytest"
]

[[envs.test.matrix]]
python = ["3.10", "3.11"]
version = ["42", "3.14"]

[[envs.test.matrix]]
python = ["3.11", "3.12"]
version = ["9000"]
feature = ["foo", "bar"]

Using the env show command would then display:

$ hatch env show --ascii
     Standalone
+---------+---------+
| Name    | Type    |
+=========+=========+
| default | virtual |
+---------+---------+
                        Matrices
+------+---------+----------------------+--------------+
| Name | Type    | Envs                 | Dependencies |
+======+=========+======================+==============+
| test | virtual | test.py3.10-42       | pytest       |
|      |         | test.py3.10-3.14     |              |
|      |         | test.py3.11-42       |              |
|      |         | test.py3.11-3.14     |              |
|      |         | test.py3.11-9000-foo |              |
|      |         | test.py3.11-9000-bar |              |
|      |         | test.py3.12-9000-foo |              |
|      |         | test.py3.12-9000-bar |              |
+------+---------+----------------------+--------------+

Removal¶

You can remove a single environment or environment matrix by using the env remove command or all of a project's environments by using the env prune command.