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.

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

Scripts

You can also run any scripts that have been defined.

You'll notice that in the pyproject.toml file there are already scripts defined in the default environment. Try running the test command, which invokes pytest with some default arguments:

hatch run test

All additional arguments are passed through to that script, so for example if you wanted to see the version of pytest and which plugins are installed you could do:

hatch run test -VV

Dependencies

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

For example, add cowsay as a dependency then try to run it:

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

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 = ["2.7", "3.8"]
version = ["42", "3.14"]

[[tool.hatch.envs.test.matrix]]
python = ["3.8", "3.9"]
version = ["9000"]
features = ["foo", "bar"]
[envs.test]
dependencies = [
  "pytest"
]

[[envs.test.matrix]]
python = ["2.7", "3.8"]
version = ["42", "3.14"]

[[envs.test.matrix]]
python = ["3.8", "3.9"]
version = ["9000"]
features = ["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.py2.7-42       | pytest       |
|      |         | test.py2.7-3.14     |              |
|      |         | test.py3.8-42       |              |
|      |         | test.py3.8-3.14     |              |
|      |         | test.py3.8-9000-foo |              |
|      |         | test.py3.8-9000-bar |              |
|      |         | test.py3.9-9000-foo |              |
|      |         | test.py3.9-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.