🐛 fix(seed): refuse to seed unsupported Python versions (#3173)

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

Author: gaborbernat

docs/changelog/3171.bugfix.rst

@@ -0,0 +1,4 @@
+Refuse to create environments whose Python the bundled wheels no longer cover (currently below 3.9). virtualenv used to
+substitute the newest bundled ``pip``, which cannot run on such a target, leaving a broken environment; seeder selection
+now rejects it up front with a clear error. ``--no-seed`` and third-party seeders that ship compatible wheels still work
+- by :user:`gaborbernat`.

docs/explanation.rst

@@ -116,8 +116,10 @@ it can discover on the system, provided a matching creator exists.
       - Linux, macOS, Windows
       - Minimal test coverage, marked experimental.
 
-Seed packages (``pip``, ``setuptools``) are bundled for CPython 3.9 through 3.16. Target interpreters outside this range
-use the highest available bundled version as a fallback, which may or may not be compatible.
+Seed packages (``pip``, ``setuptools``) are bundled for CPython 3.9 through 3.16. A target newer than the highest
+bundled version reuses the newest bundle. A target older than the oldest bundled version has no compatible bundled
+wheel, so the bundled seeders refuse it before the environment is created; pass ``--no-seed`` for an empty environment,
+or select a seeder that ships wheels for that version.
 
 **********************
  How virtualenv works
@@ -448,7 +450,9 @@ uses. They want to align virtualenv's bundled packages with system package versi
 
 Distributions can patch the ``virtualenv.seed.wheels.embed`` module, replacing the ``get_embed_wheel`` function with
 their own implementation that returns distribution-provided wheels. If they want to use virtualenv's test suite for
-validation, they should also provide the ``BUNDLE_FOLDER``, ``BUNDLE_SUPPORT``, and ``MAX`` variables.
+validation, they should also provide the ``BUNDLE_FOLDER``, ``BUNDLE_SUPPORT``, ``MIN``, ``MAX``, and
+``OLDEST_SUPPORTED`` variables. ``OLDEST_SUPPORTED`` (the parsed form of ``MIN``) sets the floor below which the bundled
+seeders refuse to seed, so a distribution that bundles wheels for an older Python must lower it to match.
 
 Distributions should also consider patching ``virtualenv.seed.embed.base_embed.PERIODIC_UPDATE_ON_BY_DEFAULT`` to
 ``False``, allowing the system package manager to control seed package updates rather than virtualenv's periodic update

docs/plugin/how-to.rst

@@ -14,27 +14,31 @@ Implement the ``Discover`` interface:
 
 .. code-block:: python
 
+    from __future__ import annotations
+
+    from argparse import ArgumentParser
+
+    from virtualenv.config.cli.parser import VirtualEnvOptions
     from virtualenv.discovery.discover import Discover
     from virtualenv.discovery.py_info import PythonInfo
 
 
     class CustomDiscovery(Discover):
         @classmethod
-        def add_parser_arguments(cls, parser):
+        def add_parser_arguments(cls, parser: ArgumentParser) -> None:
             parser.add_argument("--custom-opt", help="custom discovery option")
 
-        def __init__(self, options):
+        def __init__(self, options: VirtualEnvOptions) -> None:
             super().__init__(options)
             self.custom_opt = options.custom_opt
 
-        def run(self):
+        def run(self) -> PythonInfo | None:
             # Locate Python interpreter and return PythonInfo
-            python_exe = self._find_python()
-            return PythonInfo.from_exe(str(python_exe))
+            return PythonInfo.from_exe(str(self._find_python()))
 
-        def _find_python(self):
+        def _find_python(self) -> str:
             # Implementation-specific logic
-            pass
+            ...
 
 Register the entry point:
 
@@ -53,19 +57,32 @@ Implement the ``Creator`` interface:
 
 .. code-block:: python
 
-    from virtualenv.create.creator import Creator
+    from __future__ import annotations
+
+    from argparse import ArgumentParser
+
+    from virtualenv.app_data.base import AppData
+    from virtualenv.config.cli.parser import VirtualEnvOptions
+    from virtualenv.create.creator import Creator, CreatorMeta
+    from virtualenv.discovery.py_info import PythonInfo
 
 
     class CustomCreator(Creator):
         @classmethod
-        def add_parser_arguments(cls, parser, interpreter):
+        def add_parser_arguments(
+            cls,
+            parser: ArgumentParser,
+            interpreter: PythonInfo,
+            meta: CreatorMeta,
+            app_data: AppData,
+        ) -> None:
             parser.add_argument("--custom-creator-opt", help="custom creator option")
 
-        def __init__(self, options, interpreter):
+        def __init__(self, options: VirtualEnvOptions, interpreter: PythonInfo) -> None:
             super().__init__(options, interpreter)
             self.custom_opt = options.custom_creator_opt
 
-        def create(self):
+        def create(self) -> None:
             # Create directory structure
             self.bin_dir.mkdir(parents=True, exist_ok=True)
             # Copy or symlink Python executable
@@ -89,29 +106,51 @@ Register the entry point using a naming pattern that matches platform and Python
 
 Seeder plugins install initial packages into the virtual environment. Register under ``virtualenv.seed``.
 
+Override ``cannot_seed`` to reject target interpreters the seeder does not support. The base returns ``None`` for every
+interpreter; return a message instead and selection rejects the seeder before creating the environment, surfacing your
+message to the user. A plugin can therefore serve Python versions the bundled seeders no longer ship wheels for, such as
+a version past its support window.
+
 Implement the ``Seeder`` interface:
 
 .. code-block:: python
 
+    from __future__ import annotations
+
+    from argparse import ArgumentParser
+
+    from virtualenv.app_data.base import AppData
+    from virtualenv.config.cli.parser import VirtualEnvOptions
+    from virtualenv.create.creator import Creator
+    from virtualenv.discovery.py_info import PythonInfo
     from virtualenv.seed.seeder import Seeder
 
 
     class CustomSeeder(Seeder):
         @classmethod
-        def add_parser_arguments(cls, parser, interpreter, app_data):
+        def add_parser_arguments(
+            cls, parser: ArgumentParser, interpreter: PythonInfo, app_data: AppData
+        ) -> None:
             parser.add_argument("--custom-seed-opt", help="custom seeder option")
 
-        def __init__(self, options, enabled, app_data):
-            super().__init__(options, enabled, app_data)
+        @classmethod
+        def cannot_seed(cls, interpreter: PythonInfo) -> str | None:
+            # ship wheels down to Python 3.6, for example
+            if interpreter.version_info[:2] >= (3, 6):
+                return None
+            return "custom seeder ships wheels only for Python 3.6 and later"
+
+        def __init__(self, options: VirtualEnvOptions, enabled: bool) -> None:
+            super().__init__(options, enabled)
             self.custom_opt = options.custom_seed_opt
 
-        def run(self, creator):
+        def run(self, creator: Creator) -> None:
             # Install packages into creator.bin_dir / creator.script("pip")
             self._install_packages(creator)
 
-        def _install_packages(self, creator):
+        def _install_packages(self, creator: Creator) -> None:
             # Implementation-specific logic
-            pass
+            ...
 
 Register the entry point:
 
@@ -130,18 +169,24 @@ Implement the ``Activator`` interface:
 
 .. code-block:: python
 
+    from __future__ import annotations
+
+    from pathlib import Path
+
     from virtualenv.activation.activator import Activator
+    from virtualenv.create.creator import Creator
 
 
     class CustomShellActivator(Activator):
-        def generate(self, creator):
+        def generate(self, creator: Creator) -> list[Path]:
             # Generate activation script content
             script_content = self._render_template(creator)
             # Write to activation directory
             dest = creator.bin_dir / self.script_name
             dest.write_text(script_content)
+            return [dest]
 
-        def _render_template(self, creator):
+        def _render_template(self, creator: Creator) -> str:
             # Return activation script content
             return f"""
             # Custom shell activation script
@@ -150,7 +195,7 @@ Implement the ``Activator`` interface:
             """
 
         @property
-        def script_name(self):
+        def script_name(self) -> str:
             return "activate.custom"
 
 Register the entry point:

docs/plugin/tutorial.rst

@@ -49,19 +49,21 @@ In ``src/virtualenv_pyenv/__init__.py``, implement the discovery plugin by subcl
     from __future__ import annotations
 
     import subprocess
+    from argparse import ArgumentParser
     from pathlib import Path
 
+    from virtualenv.config.cli.parser import VirtualEnvOptions
     from virtualenv.discovery.discover import Discover
     from virtualenv.discovery.py_info import PythonInfo
 
 
     class PyEnvDiscovery(Discover):
-        def __init__(self, options):
+        def __init__(self, options: VirtualEnvOptions) -> None:
             super().__init__(options)
             self.python_spec = options.python if options.python else "python"
 
         @classmethod
-        def add_parser_arguments(cls, parser):
+        def add_parser_arguments(cls, parser: ArgumentParser) -> None:
             parser.add_argument(
                 "--python",
                 dest="python",
@@ -71,7 +73,7 @@ In ``src/virtualenv_pyenv/__init__.py``, implement the discovery plugin by subcl
                 help="pyenv Python version to use (e.g., 3.11.0)",
             )
 
-        def run(self):
+        def run(self) -> PythonInfo | None:
             try:
                 result = subprocess.run(
                     ["pyenv", "which", "python"],
@@ -82,7 +84,7 @@ In ``src/virtualenv_pyenv/__init__.py``, implement the discovery plugin by subcl
                 python_path = Path(result.stdout.strip())
                 return PythonInfo.from_exe(str(python_path))
             except (subprocess.CalledProcessError, FileNotFoundError) as e:
-                raise RuntimeError(f"Failed to locate pyenv Python: {e}")
+                raise RuntimeError(f"Failed to locate pyenv Python: {e}") from e
 
 ********************
  Install the plugin

docs/reference/compatibility.rst

@@ -46,6 +46,7 @@ Python 3.14.
 
 Major version support changes:
 
+- **21.5.0** (2026-06-13): dropped support for running under and creating environments for Python 3.8 and earlier.
 - **20.27.0** (2024-10-17): dropped support for running under Python 3.7 and earlier.
 - **20.22.0** (2023-04-19): dropped support for creating environments for Python 3.6 and earlier.
 - **20.18.0** (2023-02-06): dropped support for running under Python 3.6 and earlier.

src/virtualenv/run/plugin/seeders.py

@@ -43,7 +43,10 @@ def handle_selected_arg_parse(self, options: VirtualEnvOptions) -> str:
 
     def create(self, options: VirtualEnvOptions) -> Seeder:
         assert self._impl_class is not None  # noqa: S101  # Set by handle_selected_arg_parse
-        return self._impl_class(options)
+        seeder = self._impl_class(options)
+        if seeder.enabled and (reason := seeder.cannot_seed(self.interpreter)) is not None:
+            raise RuntimeError(reason)
+        return seeder
 
 
 __all__ = [

src/virtualenv/seed/embed/base_embed.py

@@ -8,6 +8,7 @@
 
 from virtualenv.seed.seeder import Seeder
 from virtualenv.seed.wheels import Version
+from virtualenv.seed.wheels.embed import MIN, OLDEST_SUPPORTED
 
 if TYPE_CHECKING:
     from argparse import ArgumentParser
@@ -65,6 +66,28 @@ def distribution_to_versions(self) -> dict[str, str]:
             if getattr(self, f"no_{distribution}", None) is False and getattr(self, f"{distribution}_version") != "none"
         }
 
+    @classmethod
+    def cannot_seed(cls, interpreter: PythonInfo) -> str | None:
+        """Explain why the bundled wheels cannot seed the target Python version.
+
+        The embedded pip/setuptools stopped shipping for Pythons below :data:`OLDEST_SUPPORTED`, so seeding one would
+        install an incompatible wheel.
+
+        :param interpreter: the interpreter to be seeded
+
+        :returns: ``None`` when the bundled wheels still support the target, otherwise a message naming the target and
+            the remedies
+
+        """
+        if interpreter.version_info[:2] >= OLDEST_SUPPORTED:
+            return None
+        target = f"{interpreter.version_info.major}.{interpreter.version_info.minor}"
+        return (
+            f"the bundled seeder no longer ships pip/setuptools for Python {target}; the oldest supported target is "
+            f"Python {MIN} - pass --no-seed for an empty environment, use a seeder that provides Python {target} "
+            f"wheels, or install an older virtualenv release"
+        )
+
     @classmethod
     def add_parser_arguments(cls, parser: ArgumentParser, interpreter: PythonInfo, app_data: AppData) -> None:  # noqa: ARG003
         group = parser.add_mutually_exclusive_group()

src/virtualenv/seed/seeder.py

@@ -26,6 +26,18 @@ def __init__(self, options: VirtualEnvOptions, enabled: bool) -> None:
         self.enabled = enabled
         self.env = options.env
 
+    @classmethod
+    def cannot_seed(cls, interpreter: PythonInfo) -> str | None:  # noqa: ARG003
+        """Explain why this seeder cannot install seed packages for the given interpreter.
+
+        :param interpreter: the interpreter the environment is based on
+
+        :returns: ``None`` when the seeder supports the interpreter, otherwise a message describing why it cannot;
+            selection rejects a seeder that returns a message and surfaces it to the user
+
+        """
+        return None
+
     @classmethod
     def add_parser_arguments(cls, parser: ArgumentParser, interpreter: PythonInfo, app_data: AppData) -> None:
         """Add CLI arguments for this seed mechanisms.

src/virtualenv/seed/wheels/embed/__init__.py

@@ -43,6 +43,15 @@
     },
 }
 MAX = next(reversed(BUNDLE_SUPPORT))
+MIN = next(iter(BUNDLE_SUPPORT))
+
+
+def _release_tuple(version: str) -> tuple[int, ...]:
+    return tuple(int(part) for part in version.split("."))
+
+
+# oldest target Python version virtualenv still bundles seed wheels for; anything below this has no embedded pip
+OLDEST_SUPPORTED = _release_tuple(MIN)
 
 # SHA-256 of every bundled wheel. Verified on load so a corrupted or tampered wheel on disk fails loud instead of
 # being handed to pip. Generated together with ``BUNDLE_SUPPORT`` by ``tasks/upgrade_wheels.py``.
@@ -55,19 +64,26 @@
 _VERIFIED_WHEELS: set[str] = set()
 
 
-def get_embed_wheel(distribution: str, for_py_version: str) -> Wheel | None:
+def get_embed_wheel(distribution: str, for_py_version: str | None) -> Wheel | None:
     """Return the bundled wheel that ships with virtualenv for a given distribution and Python version.
 
     :param distribution: project name of the seed package, for example ``pip`` or ``setuptools``.
-    :param for_py_version: major.minor Python version string the environment will be created for.
+    :param for_py_version: major.minor Python version string the environment will be created for, or ``None`` to use the
+        newest bundle.
 
     :returns: a :class:`Wheel` pointing at the verified bundled file, or ``None`` when no wheel is bundled for the
-        requested combination.
+        requested combination, including target versions below the oldest bundled one.
 
     :raises RuntimeError: if the bundled wheel on disk fails SHA-256 verification.
 
     """
-    mapping = BUNDLE_SUPPORT.get(for_py_version, {}) or BUNDLE_SUPPORT[MAX]
+    if for_py_version is None or _release_tuple(for_py_version) > _release_tuple(MAX):
+        # no specific target, or a Python newer than anything bundled: reuse the newest bundle
+        mapping = BUNDLE_SUPPORT[MAX]
+    else:  # versions below the oldest bundled one fall through to None instead of an incompatible newer wheel
+        mapping = BUNDLE_SUPPORT.get(for_py_version)
+    if not mapping:
+        return None
     wheel_file = mapping.get(distribution)
     if wheel_file is None:
         return None
@@ -112,5 +128,7 @@ def _hash_bundled_wheel(path: Path) -> str:
     "BUNDLE_SHA256",
     "BUNDLE_SUPPORT",
     "MAX",
+    "MIN",
+    "OLDEST_SUPPORTED",
     "get_embed_wheel",
 ]