From 7d8634bf35edbc6b7dc106d0c3eb0581c5b8d722 Mon Sep 17 00:00:00 2001 From: pythonweb2 <32141163+pythonweb2@users.noreply.github.com> Date: Thu, 20 Nov 2025 07:58:49 -0700 Subject: [PATCH] Document the new behavior for free-threaded python versions (#16781) ## Summary I noticed that after first installing the free-threaded version, then the gil version of 3.14, I wasn't able to install greenlet, because it doesn't ship with wheels for the free-threaded version (I think it isn't safe for it to use that interpreter). I noticed that the change made in 3.14 wasn't updated in the docs. ## Test Plan N/A --------- Co-authored-by: Wade Roberts Co-authored-by: Zanie Blue --- docs/concepts/python-versions.md | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) diff --git a/docs/concepts/python-versions.md b/docs/concepts/python-versions.md index 65576ef78..2c835211a 100644 --- a/docs/concepts/python-versions.md +++ b/docs/concepts/python-versions.md @@ -34,7 +34,7 @@ The following Python version request formats are supported: - `` (e.g., `3`, `3.12`, `3.12.3`) - `` (e.g., `>=3.12,<3.13`) - `` (e.g., `3.13t`, `3.12.0d`) -- `+` (e.g., `3.13+freethreaded`, `3.12.0+debug`) +- `+` (e.g., `3.13+freethreaded`, `3.12.0+debug`, `3.14+gil`) - `` (e.g., `cpython` or `cp`) - `@` (e.g., `cpython@3.12`) - `` (e.g., `cpython3.12` or `cp312`) @@ -339,8 +339,16 @@ uv supports discovering and installing [free-threaded](https://docs.python.org/3.14/glossary.html#term-free-threading) Python variants in CPython 3.13+. -Free-threaded Python versions will not be selected by default. Free-threaded Python versions will -only be selected when explicitly requested, e.g., with `3.13t` or `3.13+freethreaded`. +For Python 3.13, free-threaded Python versions will not be selected by default. Free-threaded Python +versions will only be selected when explicitly requested, e.g., with `3.13t` or `3.13+freethreaded`. + +For Python 3.14+, uv will allow use of free-threaded Python 3.14+ interpreters without explicit +selection. The GIL-enabled build of Python will still be preferred, e.g., when performing an +installation with `uv python install 3.14`. However, e.g., if a free-threaded interpreter comes +before a GIL-enabled build on the `PATH`, it will be used. + +If both free-threaded and GIL-enabled Python versions are available on the system, and want to +require the use of the GIL-enabled variant in a project, you can use the `+gil` variant specifier. ## Debug Python variants