PEP 838: Reject python startup with mismatched python-version

This is a stronger version of #127727 / #149715: Using the standardized `python-version`, we fail at startup with a helpful error message instead of running up until an unclear `ModuleNotFoundError` because the shared library has a tag for a different Python version.

This change checks the major version, we shouldn't silently pass when encountering a potential Python 4 that mismatches.

This is an optional part of the PEP and may equally be a warning as it currently is with `version`/`version_info`.

Stacked on top of #154378.

Author: konstin

Lib/site.py

@@ -982,7 +982,7 @@ def _venv(state):
     if candidate_conf:
         virtual_conf = candidate_conf
         system_site = "true"
-        version, version_info = None, None
+        version, version_info, python_version = None, None, None
         # Issue 25185: Use UTF-8, as that's what the venv module uses when
         # writing the file.
         with open(virtual_conf, encoding='utf-8') as f:
@@ -999,31 +999,46 @@ def _venv(state):
                         version = value
                     elif key == 'version_info':
                         version_info = value
-
-        for field_name, field_value in [
-            ('version',version), ('version_info',version_info)
+                    elif key == 'python-version':
+                        python_version = value
+
+        for field_name, field_value, should_error in [
+            # Run the fatal check first.
+            ('python_version', python_version, True),
+            ('version',version, False),
+            ('version_info',version_info, False),
         ]:
-            if field_value is not None:
-                try:
-                    major, minor = map(int, field_value.split(".")[:2])
-                except (ValueError, AttributeError):
-                    _warn(
-                        f"Malformed {field_name} string in pyvenv.cfg: {field_value!r}",
-                        RuntimeWarning,
-                    )
-                else:
-                    if (
-                        major == sys.version_info.major
-                        and minor != sys.version_info.minor
-                    ):
-                        _warn(
-                            f"This virtual environment was created for Python {major}.{minor}, "
-                            f"but the current interpreter is Python "
-                            f"{sys.version_info.major}.{sys.version_info.minor}. "
-                            "Consider running `python -m venv --upgrade` to update the environment.",
-                            RuntimeWarning,
-                        )
-                        break
+            if field_value is None:
+                continue
+            try:
+                major, minor = map(int, field_value.split(".")[:2])
+            except (ValueError, AttributeError):
+                _warn(
+                    f"Malformed {field_name} string in pyvenv.cfg: {field_value!r}",
+                    RuntimeWarning,
+                )
+                continue
+            if (
+                major == sys.version_info.major
+                and minor == sys.version_info.minor
+            ):
+                continue
+            if should_error:
+                raise RuntimeError(
+                    f"This virtual environment was created for Python {major}.{minor}, "
+                    f"but the current interpreter is Python "
+                    f"{sys.version_info.major}.{sys.version_info.minor}. "
+                    "Consider running `python -m venv --upgrade` to update the environment.",
+                )
+            else:
+                _warn(
+                    f"This virtual environment was created for Python {major}.{minor}, "
+                    f"but the current interpreter is Python "
+                    f"{sys.version_info.major}.{sys.version_info.minor}. "
+                    "Consider running `python -m venv --upgrade` to update the environment.",
+                    RuntimeWarning,
+                )
+                break
 
         if sys.prefix != site_prefix:
             _warn(

Lib/test/test_venv.py

@@ -313,6 +313,45 @@ def test_sysconfig(self):
                 out, err = check_output(cmd, encoding='utf-8')
                 self.assertEqual(out.strip(), expected, err)
 
+    @requireVenvCreate
+    def test_python_version_mismatch_error(self):
+        rmtree(self.env_dir)
+        self.run_with_capture(venv.create, self.env_dir, with_pip=False)
+
+        corrct_version = f"{sys.version_info.major}.{sys.version_info.minor}"
+        wrong_version = f"{sys.version_info.major}.{sys.version_info.minor + 1}"
+
+        cfg_path = self.get_env_file("pyvenv.cfg")
+        with open(cfg_path, encoding="utf-8") as f:
+            cfg_content = f.read()
+
+        cfg_content = cfg_content.replace(
+            f"python-version = {corrct_version}",
+            f"python-version = {wrong_version}",
+        )
+
+        with open(cfg_path, "w", encoding="utf-8") as f:
+            f.write(cfg_content)
+
+        envpy = self.envpy(real_env_dir=True)
+
+        proc = subprocess.run(
+            [envpy, "-c", 'print("done")'],
+            capture_output=True,
+            text=True,
+            env={**os.environ, "PYTHONHOME": ""},
+        )
+
+        self.assertNotEqual(proc.returncode, 0)
+        self.assertNotIn("done", proc.stdout)
+        self.assertIn("RuntimeError", proc.stderr)
+        self.assertIn(f"Python {wrong_version}", proc.stderr)
+        self.assertIn(
+            f"Python {sys.version_info.major}.{sys.version_info.minor}",
+            proc.stderr,
+        )
+        self.assertIn("Consider running `python -m venv --upgrade`", proc.stderr)
+
     @requireVenvCreate
     def test_version_mismatch_warning(self):
         """
@@ -330,7 +369,7 @@ def test_version_mismatch_warning(self):
 
         new_version = f"{sys.version_info.major}.{wrong_minor}"
         if 'version =' in cfg_content:
-            cfg_content = re.sub(r'version = \d+\.\d+', f'version = {new_version}', cfg_content)
+            cfg_content = re.sub(r'(?m)^version = \d+\.\d+', f'version = {new_version}', cfg_content)
 
         cfg_content += f'\nversion_info = {new_version}\n'
 
@@ -422,7 +461,7 @@ def test_malformed_version_warning(self):
 
         malformed_version = "not.a.version"
         if 'version =' in cfg_content:
-            cfg_content = re.sub(r'version = .+', f'version = {malformed_version}', cfg_content)
+            cfg_content = re.sub(r'(?m)^version = .+', f'version = {malformed_version}', cfg_content)
 
         with open(cfg_path, 'w', encoding='utf-8') as f:
             f.write(cfg_content)
@@ -483,7 +522,7 @@ def test_conflicting_version_fields(self):
 
         version_wrong = f"{sys.version_info.major}.{wrong_minor}"
         if 'version =' in cfg_content:
-            cfg_content = re.sub(r'version = \d+\.\d+', f'version = {version_wrong}', cfg_content)
+            cfg_content = re.sub(r'(?m)^version = \d+\.\d+', f'version = {version_wrong}', cfg_content)
 
         version_info_wrong = f"{sys.version_info.major}.{wrong_minor + 1}"
         cfg_content += f'\nversion_info = {version_info_wrong}\n'
@@ -519,7 +558,7 @@ def test_different_major_version_no_warning(self):
         new_version = f"{different_major}.{sys.version_info.minor}"
 
         if 'version =' in cfg_content:
-            cfg_content = re.sub(r'version = \d+\.\d+', f'version = {new_version}', cfg_content)
+            cfg_content = re.sub(r'(?m)^version = \d+\.\d+', f'version = {new_version}', cfg_content)
         with open(cfg_path, 'w', encoding='utf-8') as f:
             f.write(cfg_content)
 

Misc/NEWS.d/next/Library/2026-07-21-17-53-52.gh-issue-154377.venver.rst

@@ -0,0 +1,2 @@
+Fail at startup when the ``python-version`` in a virtual
+environment's ``pyvenv.cfg`` does not match the running interpreter.