🐛 fix(pip): set PIP_USER=0 to prevent --user installs in virtualenvs (#3719)

Users with `pip config --user` configured globally experienced
installation failures in tox virtualenvs. 🐛 When pip attempted to honor
the `--user` flag inside virtualenvs, it crashed because user
site-packages aren't visible in isolated environments.

This regression was introduced during the tox 4 rewrite. Tox 3 correctly
set `PIP_USER=0` to override user configuration, but this protection was
lost in the rewrite. The fix restores this behavior by setting the
environment variable in all virtualenv-based Python environments.

The solution follows pip's documented environment variable precedence
where `PIP_USER=0` explicitly disables `--user` installs regardless of
config file settings. This preserves user workflows while ensuring tox
virtualenvs remain isolated. ✨

Fixes #3010

Author: gaborbernat

docs/changelog/3010.bugfix.rst

@@ -0,0 +1,2 @@
+Set ``PIP_USER=0`` environment variable when running pip commands in virtualenvs to prevent pip from attempting
+``--user`` installs when users have ``pip config --user`` configured globally — by :user:`gaborbernat`.

docs/explanation.rst

@@ -113,8 +113,8 @@ External commands need to be explicitly allowed via :ref:`allowlist_externals`.
    virtualenv first.
 4. **set_env** -- values defined here are applied last and can override anything from the previous steps, including
    ``PATH``.
-5. **Injected variables** -- tox adds ``TOX_ENV_NAME``, ``TOX_WORK_DIR``, ``TOX_ENV_DIR``, ``VIRTUAL_ENV``, and
-   ``PYTHONIOENCODING=utf-8``. These cannot be overridden.
+5. **Injected variables** -- tox adds ``TOX_ENV_NAME``, ``TOX_WORK_DIR``, ``TOX_ENV_DIR``, ``VIRTUAL_ENV``,
+   ``PIP_USER=0``, and ``PYTHONIOENCODING=utf-8``. These cannot be overridden.
 
 **PATH behavior**: because tox prepends the virtualenv ``bin/`` directory to ``PATH`` at step 3, commands like
 ``python`` and ``pip`` resolve to the virtualenv versions. If you override ``PATH`` in ``set_env``, be aware that this

docs/reference/config.rst

@@ -819,6 +819,9 @@ always set regardless of the ``pass_env`` or ``set_env`` configuration and canno
       - The directory of the current tox environment (e.g. ``.tox/3.12``).
     - - ``PYTHONIOENCODING``
       - Always set to ``utf-8`` to ensure consistent encoding for standard I/O.
+    - - ``PIP_USER``
+      - Always set to ``0`` to prevent pip from attempting ``--user`` installs inside virtualenvs, which would fail
+        because user site-packages aren't visible. Only set when using ``virtualenv``\-based environments.
     - - ``TOX_PACKAGE``
       - The path(s) to the built package artifact(s), joined by ``os.pathsep`` if there are multiple. Only set in run
         environments where a package has been built.

src/tox/tox_env/python/virtual_env/api.py

@@ -176,6 +176,7 @@ def runs_on_platform(self) -> str:
     def environment_variables(self) -> dict[str, str]:
         environment_variables = super().environment_variables
         environment_variables["VIRTUAL_ENV"] = str(self.conf["env_dir"])
+        environment_variables["PIP_USER"] = "0"
         return environment_variables
 
     @classmethod

tests/tox_env/python/virtual_env/test_virtualenv_api.py

@@ -172,3 +172,20 @@ def test_list_dependencies_command(tox_project: ToxProjectCreator) -> None:
     result.assert_success()
     request: ExecuteRequest = execute_calls.call_args[0][3]
     assert request.cmd == ["python", "-m", "pip", "freeze"]
+
+
+def test_pip_user_disabled(tox_project: ToxProjectCreator) -> None:
+    proj = tox_project(
+        {
+            "tox.toml": """
+                [env_run_base]
+                package = "skip"
+                commands = [
+                    ["python", "-c", "import os; print('PIP_USER=' + os.environ.get('PIP_USER', 'NOT_SET'))"]
+                ]
+            """,
+        },
+    )
+    result = proj.run("r", "-e", "py")
+    result.assert_success()
+    assert "PIP_USER=0" in result.out