Skip to content

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:

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

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

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