Allow disabling plugins on a one-off

Signed-off-by: Bernát Gábor <[email protected]>

Author: gaborbernat

.github/workflows/check.yaml

@@ -30,9 +30,9 @@ jobs:
           - "3.10"
           - "3.9"
         os:
-          - ubuntu-latest
-          - windows-latest
-          - macos-latest
+          - ubuntu-24.04
+          - windows-2025
+          - macos-15
     steps:
       - uses: actions/checkout@v4
         with:
@@ -70,8 +70,8 @@ jobs:
           - docs
           - pkg_meta
         os:
-          - ubuntu-latest
-          - windows-latest
+          - ubuntu-24.04
+          - windows-2025
         exclude:
           - { os: windows-latest, tox_env: docs }
     steps:

.github/workflows/release.yaml

@@ -9,7 +9,7 @@ env:
 
 jobs:
   build:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
     steps:
       - uses: actions/checkout@v4
         with:
@@ -31,7 +31,7 @@ jobs:
   release:
     needs:
       - build
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
     environment:
       name: release
       url: https://pypi.org/project/tox/${{ github.ref_name }}

docs/changelog/3468.feature.rst

@@ -0,0 +1 @@
+Allow disabling tox plugins via the ``TOX_DISABLED_EXTERNAL_PLUGINS`` environment variable - by :user:`gaborbernat`.

docs/plugins.rst

@@ -27,6 +27,13 @@ installed. For example:
 
 For more information, refer to :ref:`the user guide <auto-provisioning>`.
 
+Plugins can be disabled via the ``TOX_DISABLED_EXTERNAL_PLUGINS`` environment variable. This variable can be set to a
+comma separated list of plugin names, e.g.:
+
+```bash
+env TOX_DISABLED_EXTERNAL_PLUGINS=tox-uv,tox-extra tox --version
+```
+
 Developing your own plugin
 --------------------------
 

pyproject.toml

@@ -1,7 +1,7 @@
 [build-system]
 build-backend = "hatchling.build"
 requires = [
-  "hatch-vcs>=0.4",
+  "hatch-vcs>=0.5",
   "hatchling>=1.27",
 ]
 
@@ -50,22 +50,17 @@ dynamic = [
   "version",
 ]
 dependencies = [
-  "cachetools>=5.5.1",
+  "cachetools>=6.1",
   "chardet>=5.2",
   "colorama>=0.4.6",
-  "filelock>=3.16.1",
-  "packaging>=24.2",
-  "platformdirs>=4.3.6",
-  "pluggy>=1.5",
-  "pyproject-api>=1.8",
+  "filelock>=3.18",
+  "packaging>=25",
+  "platformdirs>=4.3.8",
+  "pluggy>=1.6",
+  "pyproject-api>=1.9.1",
   "tomli>=2.2.1; python_version<'3.11'",
-  "typing-extensions>=4.12.2; python_version<'3.11'",
-  "virtualenv>=20.31",
-]
-optional-dependencies.test = [
-  "devpi-process>=1.0.2",
-  "pytest>=8.3.4",
-  "pytest-mock>=3.14",
+  "typing-extensions>=4.14.1; python_version<'3.11'",
+  "virtualenv>=20.31.2",
 ]
 urls.Documentation = "https://tox.wiki"
 urls.Homepage = "http://tox.readthedocs.org"
@@ -83,35 +78,35 @@ dev = [
 test = [
   "build[virtualenv]>=1.2.2.post1",
   "covdefaults>=2.3",
-  "coverage>=7.9.1",
+  "coverage>=7.9.2",
   "detect-test-pollution>=1.2",
   "devpi-process>=1.0.2",
-  "diff-cover>=9.2",
-  "distlib>=0.3.9",
+  "diff-cover>=9.6",
+  "distlib>=0.4",
   "flaky>=3.8.1",
-  "hatch-vcs>=0.4",
+  "hatch-vcs>=0.5",
   "hatchling>=1.27",
-  "psutil>=6.1.1",
-  "pytest>=8.3.4",
-  "pytest-cov>=5",
-  "pytest-mock>=3.14",
-  "pytest-xdist>=3.6.1",
+  "psutil>=7",
+  "pytest>=8.4.1",
+  "pytest-cov>=6.2.1",
+  "pytest-mock>=3.14.1",
+  "pytest-xdist>=3.8",
   "re-assert>=1.1",
-  "setuptools>=75.8",
-  "time-machine>=2.15; implementation_name!='pypy'",
+  "setuptools>=80.9",
+  "time-machine>=2.16; implementation_name!='pypy'",
   "wheel>=0.45.1",
 ]
 type = [
-  "mypy==1.15",
-  "types-cachetools>=5.5.0.20240820",
+  "mypy==1.17",
+  "types-cachetools>=6.1.0.20250717",
   "types-chardet>=5.0.4.6",
   { include-group = "test" },
 ]
 docs = [
-  "furo>=2024.8.6",
-  "sphinx>=8.1.3",
+  "furo>=2025.7.19",
+  "sphinx>=8.2.3",
   "sphinx-argparse-cli>=1.19",
-  "sphinx-autodoc-typehints>=3.0.1",
+  "sphinx-autodoc-typehints>=3.2",
   "sphinx-copybutton>=0.5.2",
   "sphinx-inline-tabs>=2023.4.21",
   "sphinxcontrib-towncrier>=0.2.1a0",
@@ -121,13 +116,13 @@ fix = [
   "pre-commit-uv>=4.1.4",
 ]
 pkg-meta = [
-  "check-wheel-contents>=0.6.1",
+  "check-wheel-contents>=0.6.2",
   "twine>=6.1",
-  "uv>=0.5.29",
+  "uv>=0.8",
 ]
 release = [
   "gitpython>=3.1.44",
-  "packaging>=24.2",
+  "packaging>=25",
   "towncrier>=24.8",
 ]
 

src/tox/config/cli/parser.py

@@ -263,7 +263,7 @@ def add_argument_group(self, *args: Any, **kwargs: Any) -> Any:
 
             def add_mutually_exclusive_group(**e_kwargs: Any) -> Any:
                 def add_argument(*a_args: str, of_type: type[Any] | None = None, **a_kwargs: Any) -> Action:
-                    res_args: Action = prev_add_arg(*a_args, **a_kwargs)  # type: ignore[has-type]
+                    res_args: Action = prev_add_arg(*a_args, **a_kwargs)
                     arguments.append((a_args, of_type, a_kwargs))
                     return res_args
 

src/tox/config/loader/api.py

@@ -151,13 +151,13 @@ def load(
             converted_override = _STR_CONVERT.to(override.value, of_type, factory)
             if override.append and converted is not None:
                 if isinstance(converted, list) and isinstance(converted_override, list):
-                    converted += converted_override
+                    converted += converted_override  # type: ignore[assignment]
                 elif isinstance(converted, dict) and isinstance(converted_override, dict):
                     converted.update(converted_override)
                 elif isinstance(converted, SetEnv) and isinstance(converted_override, SetEnv):
                     converted.update(converted_override, override=True)
                 elif isinstance(converted, PythonDeps) and isinstance(converted_override, PythonDeps):
-                    converted += converted_override
+                    converted += converted_override   # type: ignore[operator]
                 else:
                     msg = "Only able to append to lists and dicts"
                     raise ValueError(msg)

src/tox/config/loader/convert.py

@@ -47,7 +47,7 @@ def to(self, raw: T, of_type: type[V], factory: Factory[V]) -> V:  # noqa: PLR09
             return list(self.to_list(raw, of_type=of_type))  # type: ignore[return-value]
         if isinstance(raw, of_type):  # already target type no need to transform it
             # do it this late to allow normalization - e.g. string strip
-            return raw  # type: ignore[no-any-return]
+            return raw
         if factory:
             return factory(raw)
         return of_type(raw)  # type: ignore[no-any-return]

src/tox/plugin/manager.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import os
 from typing import TYPE_CHECKING, Any
 
 import pluggy
@@ -49,7 +50,7 @@ def _register_plugins(self, inline: ModuleType | None) -> None:
 
         if inline is not None:
             self.manager.register(inline)
-        self.manager.load_setuptools_entrypoints(NAME)
+        self._load_external_plugins()
         internal_plugins = (
             loader_api,
             provision,
@@ -74,6 +75,11 @@ def _register_plugins(self, inline: ModuleType | None) -> None:
         self.manager.register(state)
         self.manager.check_pending()
 
+    def _load_external_plugins(self) -> None:
+        for name in os.environ.get("TOX_DISABLED_EXTERNAL_PLUGINS", "").split(","):
+            self.manager.set_blocked(name)
+        self.manager.load_setuptools_entrypoints(NAME)
+
     def tox_add_option(self, parser: ToxParser) -> None:
         self.manager.hook.tox_add_option(parser=parser)
 

src/tox/pytest.py

@@ -82,7 +82,10 @@ def _load_inline(path: Path) -> ModuleType | None:  # register only on first run
 @contextmanager
 def check_os_environ() -> Iterator[None]:
     old = os.environ.copy()
-    to_clean = {k: os.environ.pop(k, None) for k in (ENV_VAR_KEY, "TOX_WORK_DIR", "PYTHONPATH", "COV_CORE_CONTEXT")}
+    to_clean = {
+        k: os.environ.pop(k, None)
+        for k in (ENV_VAR_KEY, "TOX_WORK_DIR", "PYTHONPATH", "COV_CORE_CONTEXT", "TOX_DISABLED_EXTERNAL_PLUGINS")
+    }
 
     yield
 
@@ -93,6 +96,7 @@ def check_os_environ() -> Iterator[None]:
     new = os.environ
     extra = {k: new[k] for k in set(new) - set(old)}
     extra.pop("PLAT", None)
+    extra.pop("TOX_DISABLED_EXTERNAL_PLUGINS", None)
     miss = {k: old[k] for k in set(old) - set(new)}
     diff = {
         f"{k} = {old[k]} vs {new[k]}" for k in set(old) & set(new) if old[k] != new[k] and not k.startswith("PYTEST_")