Add free-threaded Python support

.github/workflows/check.yaml

@@ -22,6 +22,7 @@ jobs:
       fail-fast: false
       matrix:
         py:
+          - "3.13t"
           - "3.13"
           - "3.12"
           - "3.11"
@@ -83,19 +84,26 @@ jobs:
         if: matrix.py != '3.13'
         run: uv tool install --python-preference only-managed --python 3.13 tox --with tox-uv
       - name: Setup brew python for test ${{ matrix.py }}
-        if: startsWith(matrix.py,'brew@')
+        if: startsWith(matrix.py, 'brew@')
         run: |
           set -e
           PY=$(echo '${{ matrix.py }}' | cut -c 6-)
           brew cleanup && brew upgrade python@$PY || brew install python@$PY
           echo "/usr/local/opt/python@$PY/libexec/bin" >>"${GITHUB_PATH}"
         shell: bash
       - name: Setup python for test ${{ matrix.py }}
-        if: "!( startsWith(matrix.py,'brew@') || endsWith(matrix.py, '-dev') )"
+        if: "!( startsWith(matrix.py, 'brew@') || endsWith(matrix.py, 't'))"
         uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.py }}
           allow-prereleases: true
+      # quansight-labs to install free-threaded python until actions/setup-python supports it
+      # https://github.com/actions/setup-python/issues/771
+      - name: Setup python for test ${{ matrix.py }}
+        if: endsWith(matrix.py, 't')
+        uses: quansight-labs/[email protected]
+        with:
+          python-version: ${{ matrix.py }}
       - name: Pick environment to run
         run: python tasks/pick_tox_env.py ${{ matrix.py }}
       - name: Setup test suite

docs/changelog/2809.feature.rst

@@ -0,0 +1 @@
+Add support for selecting free-threaded Python interpreters, e.g., `python3.13t`.

docs/installation.rst

@@ -84,7 +84,7 @@ Python and OS Compatibility
 
 virtualenv works with the following Python interpreter implementations:
 
-- `CPython <https://www.python.org/>`_: ``3.12 >= python_version >= 3.7``
+- `CPython <https://www.python.org/>`_: ``3.13 >= python_version >= 3.7``
 - `PyPy <https://pypy.org/>`_: ``3.10 >= python_version >= 3.7``
 
 This means virtualenv works on the latest patch version of each of these minor versions. Previous patch versions are

docs/user_guide.rst

@@ -93,6 +93,7 @@ format is either:
 
     - ``python3.8.1`` means any python implementation having the version ``3.8.1``,
     - ``3`` means any python implementation having the major version ``3``,
+    - ``3.13t`` means any python implementation having the version ``3.13`` with free threading,
     - ``cpython3`` means a ``CPython`` implementation having the version ``3``,
     - ``pypy2`` means a python interpreter with the ``PyPy`` implementation and major version ``2``.
 

src/virtualenv/discovery/cached_py_info.py

@@ -24,6 +24,7 @@
 _CACHE = OrderedDict()
 _CACHE[Path(sys.executable)] = PythonInfo()
 LOGGER = logging.getLogger(__name__)
+_CACHE_FILE_VERSION = 1
 
 
 def from_exe(cls, app_data, exe, env=None, raise_on_error=True, ignore_cache=False):  # noqa: FBT002, PLR0913
@@ -64,8 +65,13 @@ def _get_via_file_cache(cls, app_data, path, exe, env):
     with py_info_store.locked():
         if py_info_store.exists():  # if exists and matches load
             data = py_info_store.read()
-            of_path, of_st_mtime, of_content = data["path"], data["st_mtime"], data["content"]
-            if of_path == path_text and of_st_mtime == path_modified:
+            of_path, of_st_mtime, of_content, version = (
+                data["path"],
+                data["st_mtime"],
+                data["content"],
+                data.get("version"),
+            )
+            if of_path == path_text and of_st_mtime == path_modified and version == _CACHE_FILE_VERSION:
                 py_info = cls._from_dict(of_content.copy())
                 sys_exe = py_info.system_executable
                 if sys_exe is not None and not os.path.exists(sys_exe):
@@ -76,7 +82,12 @@ def _get_via_file_cache(cls, app_data, path, exe, env):
         if py_info is None:  # if not loaded run and save
             failure, py_info = _run_subprocess(cls, exe, app_data, env)
             if failure is None:
-                data = {"st_mtime": path_modified, "path": path_text, "content": py_info._to_dict()}  # noqa: SLF001
+                data = {
+                    "st_mtime": path_modified,
+                    "path": path_text,
+                    "content": py_info._to_dict(),  # noqa: SLF001
+                    "version": _CACHE_FILE_VERSION,
+                }
                 py_info_store.write(data)
             else:
                 py_info = failure

src/virtualenv/discovery/py_info.py

@@ -52,6 +52,7 @@ def abs_path(v):
 
         self.version = sys.version
         self.os = os.name
+        self.free_threaded = sysconfig.get_config_var("Py_GIL_DISABLED") == 1
 
         # information about the prefix - determines python home
         self.prefix = abs_path(getattr(sys, "prefix", None))  # prefix we think
@@ -290,7 +291,12 @@ def __str__(self) -> str:
 
     @property
     def spec(self):
-        return "{}{}-{}".format(self.implementation, ".".join(str(i) for i in self.version_info), self.architecture)
+        return "{}{}{}-{}".format(
+            self.implementation,
+            ".".join(str(i) for i in self.version_info),
+            "t" if self.free_threaded else "",
+            self.architecture,
+        )
 
     @classmethod
     def clear_cache(cls, app_data):

src/virtualenv/discovery/py_spec.py

@@ -5,7 +5,7 @@
 import os
 import re
 
-PATTERN = re.compile(r"^(?P<impl>[a-zA-Z]+)?(?P<version>[0-9.]+)?(?:-(?P<arch>32|64))?$")
+PATTERN = re.compile(r"^(?P<impl>[a-zA-Z]+)?(?P<version>[0-9.]+)?(?P<threaded>t)?(?:-(?P<arch>32|64))?$")
 
 
 class PythonSpec:
@@ -20,18 +20,21 @@ def __init__(  # noqa: PLR0913
         micro: int | None,
         architecture: int | None,
         path: str | None,
+        *,
+        free_threaded: bool | None = None,
     ) -> None:
         self.str_spec = str_spec
         self.implementation = implementation
         self.major = major
         self.minor = minor
         self.micro = micro
+        self.free_threaded = free_threaded
         self.architecture = architecture
         self.path = path
 
     @classmethod
     def from_string_spec(cls, string_spec: str):  # noqa: C901, PLR0912
-        impl, major, minor, micro, arch, path = None, None, None, None, None, None
+        impl, major, minor, micro, threaded, arch, path = None, None, None, None, None, None, None
         if os.path.isabs(string_spec):  # noqa: PLR1702
             path = string_spec
         else:
@@ -65,19 +68,21 @@ def _int_or_none(val):
                     impl = groups["impl"]
                     if impl in {"py", "python"}:
                         impl = None
+                    threaded = bool(groups["threaded"])
                     arch = _int_or_none(groups["arch"])
 
             if not ok:
                 path = string_spec
 
-        return cls(string_spec, impl, major, minor, micro, arch, path)
+        return cls(string_spec, impl, major, minor, micro, arch, path, free_threaded=threaded)
 
     def generate_re(self, *, windows: bool) -> re.Pattern:
         """Generate a regular expression for matching against a filename."""
         version = r"{}(\.{}(\.{})?)?".format(
             *(r"\d+" if v is None else v for v in (self.major, self.minor, self.micro))
         )
         impl = "python" if self.implementation is None else f"python|{re.escape(self.implementation)}"
+        mod = "t" if self.free_threaded else ""
         suffix = r"\.exe" if windows else ""
         version_conditional = (
             "?"
@@ -89,7 +94,7 @@ def generate_re(self, *, windows: bool) -> re.Pattern:
         )
         # Try matching `direct` first, so the `direct` group is filled when possible.
         return re.compile(
-            rf"(?P<impl>{impl})(?P<v>{version}){version_conditional}{suffix}$",
+            rf"(?P<impl>{impl})(?P<v>{version}){version_conditional}{mod}{suffix}$",
             flags=re.IGNORECASE,
         )
 
@@ -105,6 +110,8 @@ def satisfies(self, spec):
             return False
         if spec.architecture is not None and spec.architecture != self.architecture:
             return False
+        if spec.free_threaded != self.free_threaded:
+            return False
 
         for our, req in zip((self.major, self.minor, self.micro), (spec.major, spec.minor, spec.micro)):
             if req is not None and our is not None and our != req:
@@ -113,7 +120,7 @@ def satisfies(self, spec):
 
     def __repr__(self) -> str:
         name = type(self).__name__
-        params = "implementation", "major", "minor", "micro", "architecture", "path"
+        params = "implementation", "major", "minor", "micro", "architecture", "path", "free_threaded"
         return f"{name}({', '.join(f'{k}={getattr(self, k)}' for k in params if getattr(self, k) is not None)})"
 
 

tests/integration/test_zipapp.py

@@ -26,23 +26,26 @@ def zipapp_build_env(tmp_path_factory):
         exe, found = None, False
         # prefer CPython as builder as pypy is slow
         for impl in ["cpython", ""]:
-            for version in range(11, 6, -1):
-                with suppress(Exception):
-                    # create a virtual environment which is also guaranteed to contain a recent enough pip (bundled)
-                    session = cli_run(
-                        [
-                            "-vvv",
-                            "-p",
-                            f"{impl}3.{version}",
-                            "--activators",
-                            "",
-                            str(create_env_path),
-                            "--no-download",
-                            "--no-periodic-update",
-                        ],
-                    )
-                    exe = str(session.creator.exe)
-                    found = True
+            for threaded in ["", "t"]:
+                for version in range(11, 6, -1):
+                    with suppress(Exception):
+                        # create a virtual environment which is also guaranteed to contain a recent enough pip (bundled)
+                        session = cli_run(
+                            [
+                                "-vvv",
+                                "-p",
+                                f"{impl}3.{version}{threaded}",
+                                "--activators",
+                                "",
+                                str(create_env_path),
+                                "--no-download",
+                                "--no-periodic-update",
+                            ],
+                        )
+                        exe = str(session.creator.exe)
+                        found = True
+                        break
+                if found:
                     break
             if found:
                 break

tests/unit/create/via_global_ref/builtin/cpython/cpython3_win_embed.json

@@ -57,5 +57,6 @@
   "system_stdlib": "c:\\path\\to\\python\\Lib",
   "system_stdlib_platform": "c:\\path\\to\\python\\Lib",
   "max_size": 9223372036854775807,
-  "_creators": null
+  "_creators": null,
+  "free_threaded": false
 }

tests/unit/create/via_global_ref/builtin/pypy/deb_pypy37.json

@@ -60,5 +60,6 @@
   "system_stdlib": "/usr/lib/pypy3/lib-python/3.7",
   "system_stdlib_platform": "/usr/lib/pypy3/lib-python/3.7",
   "max_size": 9223372036854775807,
-  "_creators": null
+  "_creators": null,
+  "free_threaded": false
 }

tests/unit/create/via_global_ref/builtin/pypy/deb_pypy38.json

@@ -60,5 +60,6 @@
   "system_stdlib": "/usr/lib/pypy3.8",
   "system_stdlib_platform": "/usr/lib/pypy3.8",
   "max_size": 9223372036854775807,
-  "_creators": null
+  "_creators": null,
+  "free_threaded": false
 }

tests/unit/create/via_global_ref/builtin/pypy/portable_pypy38.json

@@ -59,5 +59,6 @@
   "system_stdlib": "/tmp/pypy3.8-v7.3.8-linux64/lib/pypy3.8",
   "system_stdlib_platform": "/tmp/pypy3.8-v7.3.8-linux64/lib/pypy3.8",
   "max_size": 9223372036854775807,
-  "_creators": null
+  "_creators": null,
+  "free_threaded": false
 }

tests/unit/create/via_global_ref/test_build_c_ext.py

@@ -41,10 +41,19 @@ def test_can_build_c_extensions(creator, tmp_path, coverage_env):
     shutil.copytree(str(Path(__file__).parent.resolve() / "greet"), greet)
     session = cli_run(["--creator", creator, "--seeder", "app-data", str(env), "-vvv"])
     coverage_env()
+    setuptools_index_args = ()
+    if CURRENT.version_info >= (3, 12):
+        # requires to be able to install setuptools as build dependency
+        setuptools_index_args = (
+            "--find-links",
+            "https://pypi.org/simple/setuptools/",
+        )
+
     cmd = [
         str(session.creator.script("pip")),
         "install",
         "--no-index",
+        *setuptools_index_args,
         "--no-deps",
         "--disable-pip-version-check",
         "-vvv",

tests/unit/discovery/py_info/test_py_info.py

@@ -26,7 +26,9 @@ def test_current_as_json():
     result = CURRENT._to_json()  # noqa: SLF001
     parsed = json.loads(result)
     a, b, c, d, e = sys.version_info
+    f = sysconfig.get_config_var("Py_GIL_DISABLED") == 1
     assert parsed["version_info"] == {"major": a, "minor": b, "micro": c, "releaselevel": d, "serial": e}
+    assert parsed["free_threaded"] is f
 
 
 def test_bad_exe_py_info_raise(tmp_path, session_app_data):
@@ -59,7 +61,7 @@ def test_bad_exe_py_info_no_raise(tmp_path, caplog, capsys, session_app_data):
     itertools.chain(
         [sys.executable],
         [
-            f"{impl}{'.'.join(str(i) for i in ver)}{arch}"
+            f"{impl}{'.'.join(str(i) for i in ver)}{'t' if CURRENT.free_threaded else ''}{arch}"
             for impl, ver, arch in itertools.product(
                 (
                     [CURRENT.implementation]
@@ -90,6 +92,14 @@ def test_satisfy_not_arch():
     assert matches is False
 
 
+def test_satisfy_not_threaded():
+    parsed_spec = PythonSpec.from_string_spec(
+        f"{CURRENT.implementation}{'' if CURRENT.free_threaded else 't'}",
+    )
+    matches = CURRENT.satisfies(parsed_spec, True)
+    assert matches is False
+
+
 def _generate_not_match_current_interpreter_version():
     result = []
     for i in range(3):

tests/unit/discovery/py_info/test_py_info_exe_based_of.py

@@ -30,7 +30,7 @@ def test_discover_ok(tmp_path, suffix, impl, version, arch, into, caplog, sessio
     caplog.set_level(logging.DEBUG)
     folder = tmp_path / into
     folder.mkdir(parents=True, exist_ok=True)
-    name = f"{impl}{version}"
+    name = f"{impl}{version}{'t' if CURRENT.free_threaded else ''}"
     if arch:
         name += f"-{arch}"
     name += suffix

tests/unit/discovery/test_discovery.py

@@ -21,6 +21,7 @@ def test_discovery_via_path(monkeypatch, case, specificity, tmp_path, caplog, se
     caplog.set_level(logging.DEBUG)
     current = PythonInfo.current_system(session_app_data)
     name = "somethingVeryCryptic"
+    threaded = "t" if current.free_threaded else ""
     if case == "lower":
         name = name.lower()
     elif case == "upper":
@@ -37,7 +38,7 @@ def test_discovery_via_path(monkeypatch, case, specificity, tmp_path, caplog, se
         # e.g. spec: python3.12.1, exe: /bin/python
         core_ver = ".".join(str(i) for i in current.version_info[0:3])
         exe_ver = ""
-    core = "" if specificity == "none" else f"{name}{core_ver}"
+    core = threaded if specificity == "none" else f"{name}{threaded}{core_ver}"
     exe_name = f"{name}{exe_ver}{'.exe' if sys.platform == 'win32' else ''}"
     target = tmp_path / current.install_path("scripts")
     target.mkdir(parents=True)

tests/unit/discovery/test_py_spec.py

@@ -45,6 +45,16 @@ def test_spec_satisfies_arch():
     assert spec_2.satisfies(spec_1) is False
 
 
+def test_spec_satisfies_free_threaded():
+    spec_1 = PythonSpec.from_string_spec("python3.13t")
+    spec_2 = PythonSpec.from_string_spec("python3.13")
+
+    assert spec_1.satisfies(spec_1) is True
+    assert spec_1.free_threaded is True
+    assert spec_2.satisfies(spec_1) is False
+    assert spec_2.free_threaded is False
+
+
 @pytest.mark.parametrize(
     ("req", "spec"),
     [("py", "python"), ("jython", "jython"), ("CPython", "cpython")],

tests/unit/discovery/windows/conftest.py

@@ -65,7 +65,7 @@ def _open_key_ex(*args):
     mocker.patch("os.path.exists", return_value=True)
 
 
-def _mock_pyinfo(major, minor, arch, exe):
+def _mock_pyinfo(major, minor, arch, exe, threaded=False):
     """Return PythonInfo objects with essential metadata set for the given args"""
     from virtualenv.discovery.py_info import PythonInfo, VersionInfo  # noqa: PLC0415
 
@@ -75,6 +75,7 @@ def _mock_pyinfo(major, minor, arch, exe):
     info.implementation = "CPython"
     info.architecture = arch
     info.version_info = VersionInfo(major, minor, 0, "final", 0)
+    info.free_threaded = threaded
     return info
 
 

tox.ini

@@ -13,6 +13,7 @@ env_list =
     coverage
     readme
     docs
+    3.13t
 skip_missing_interpreters = true
 
 [testenv]