Commit ec44803

.. _work-dir-placement:

Work directory placement

Everything tox generates lives under one directory, :ref:`work_dir`: the virtual environments, their logs, packaging

artifacts, and the provisioned tox itself when :ref:`auto-provisioning` kicks in. The default is ``.tox`` next to the

configuration file, which makes a project self-contained: deleting the checkout deletes its environments, and two

checkouts of the same project never share state.

Placing environments in the tree also has costs. Editor indexers and file watchers crawl the virtual environments unless

told otherwise, and backup or cloud-sync tools pick up thousands of files tox can regenerate at will. A project on a

network or otherwise slow filesystem drags each environment operation down with it too. In those situations move the

environments to a per-project directory under your home folder, the way ``virtualenvwrapper`` centralizes its virtual

environments; the ``{home}`` and ``{tox_root_name}`` substitutions in :ref:`work_dir` express this without hard-coding a

path.

The trade-off mirrors the benefit of the default: ``{tox_root_name}`` is only the name of the project directory, so two

projects checked out under the same name resolve to the same work directory, and removing a checkout leaves its

environments behind until you delete them yourself. For the recipe, see :ref:`howto_out_of_tree_envs`.

.. _howto_out_of_tree_envs:

Keep environments outside the project tree

By default tox creates its environments in a ``.tox`` directory next to the configuration file. To keep them out of the

project tree, point :ref:`work_dir` at a location built from the ``{home}`` and ``{tox_root_name}`` substitutions:

.. tab:: TOML

.. code-block:: toml

.. tab:: INI (deprecated)

.. code-block:: ini

With this configuration a project checked out at ``~/src/magic`` keeps its environments in ``~/.local/state/tox/magic``.

Verify the resolved location with:

.. code-block:: bash

Substitutions resolve in the project configuration file only: the ``--workdir`` CLI flag and the user-level

configuration file take literal paths, so this setting belongs in ``tox.toml``. Since ``{tox_root_name}`` is the name of

the project directory, two projects checked out under the same directory name share a work directory; give one of them

an explicit path if that happens. See :ref:`work-dir-placement` for the trade-offs of moving environments out of the

tree.

:version_changed: 4.60

Use the ``{home}`` and ``{tox_root_name}`` substitutions to keep tox environments outside of the project tree, in a

location unique per project, similar to ``virtualenvwrapper``:

.. code-block:: toml

The ``--workdir`` CLI flag and the user-level configuration file take the value as a literal path, without

substitution. See :ref:`howto_out_of_tree_envs` for a walk-through and :ref:`work-dir-placement` for the

trade-offs.

- - ``{tox_root_name}``

- Name of the project root directory (the last path component of ``{tox_root}``).

- - ``{home}``

- The current user's home directory.

On the first run, tox creates virtual environments and installs dependencies. The environments land in a ``.tox``

directory next to your configuration file; add it to your version control ignore file, or relocate it entirely as shown

in :ref:`howto_out_of_tree_envs`. Subsequent runs reuse existing environments unless dependencies change:

self.add_constant("tox_root_name", "name of the root directory", self._root.name)

self.add_constant("home", "the user's home directory", Path.home)

def test_config_work_dir_substitutions(tox_project: ToxProjectCreator, monkeypatch: pytest.MonkeyPatch) -> None:

project = tox_project({"tox.toml": 'work_dir = "{home}/.local/state/tox/{tox_root_name}"'})

home = project.path.parent / "home"

for var in ("HOME", "USERPROFILE"): # Path.home() reads HOME on POSIX, USERPROFILE on Windows

monkeypatch.setenv(var, str(home))

result = project.run("c")

assert result.state.conf.core["work_dir"] == home / ".local" / "state" / "tox" / project.path.name

def test_config_work_dir_substitutions_cli_override(tox_project: ToxProjectCreator) -> None:

project = tox_project({"tox.toml": 'work_dir = "{home}/.local/state/tox/{tox_root_name}"'})

result = project.run("c", "--workdir", str(project.path / "wd"))

assert result.state.conf.core["work_dir"] == project.path / "wd"