Virtual environment¶

This uses virtual environments backed by the standard virtualenv tool.

Configuration¶

The environment plugin name is virtual.

pyproject.toml hatch.toml

[tool.hatch.envs.<ENV_NAME>]
type = "virtual"

[envs.<ENV_NAME>]
type = "virtual"

Options¶

Option	Default	Description
`system-packages`	`false`	Whether or not to give the virtual environment access to the system `site-packages` directory
`python`		The version of Python to find on your system and subsequently use to create the environment, defaulting to the `HATCH_PYTHON` environment variable, followed by the first Python executable found along your PATH, followed by the Python executable Hatch is running on. Setting the `HATCH_PYTHON` environment variable to `self` will force the use of the Python executable Hatch is running on. For more information, see the documentation.
`path`		An explicit path to the virtual environment. The path may be absolute or relative to the project root. Any environments that inherit this option will also use this path. The environment variable `HATCH_ENV_TYPE_VIRTUAL_PATH` may be used, which will take precedence.

Location¶

The location of environments is determined in the following heuristic order:

The path option
A directory named after the environment within the configured virtual environment directory if the directory resides somewhere within the project root or if it is set to a .virtualenvs directory within the user's home directory
Otherwise, environments are stored within the configured virtual environment directory in a deeply nested structure in order to support multiple projects

Additionally, when the path option is not used, the name of the directory for the default environment will be the normalized project name to provide a more meaningful default shell prompt.