Skip to content

Document support for free-threaded and debug Python versions #15961

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
zanieb merged 6 commits into from
Sep 22, 2025
Merged

Document support for free-threaded and debug Python versions #15961

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
cf86432
Document support for free-threaded and debug Python versions
zanieb Sep 20, 2025
5b1a606
Update docs/concepts/python-versions.md
zanieb Sep 22, 2025
2d64691
Update docs/concepts/python-versions.md
zanieb Sep 22, 2025
5e3c973
Add note
zanieb Sep 22, 2025
1e6d93a
Fix note
zanieb Sep 22, 2025
b52da6c
Reset lockfile
zanieb Sep 22, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions crates/uv-cli/src/lib.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -437,6 +437,8 @@ pub enum Commands {
///
/// - `<version>` e.g. `3`, `3.12`, `3.12.3`
/// - `<version-specifier>` e.g. `>=3.12,<3.13`
/// - `<version><short-variant>` (e.g., `3.13t`, `3.12.0d`)
Copy link
Copy Markdown
Contributor

@geofft geofft Sep 20, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should we call this "ABI flag," for consistency with e.g. sys.abiflags?

Copy link
Copy Markdown
Member Author

@zanieb zanieb Sep 20, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hm. I'll think about that. I probably don't want to introduce another concept.

Copy link
Copy Markdown
Contributor

@geofft geofft Sep 22, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would argue that this naming is what's already used in the Python docs and "short variant" would be introducing new naming, but I see the argument that we're already using "variant," hm....

Copy link
Copy Markdown
Member Author

@zanieb zanieb Sep 22, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's just track this in an issue for now.

/// - `<version>+<variant>` (e.g., `3.13+freethreaded`, `3.12.0+debug`)
/// - `<implementation>` e.g. `cpython` or `cp`
/// - `<implementation>@<version>` e.g. `cpython@3.12`
/// - `<implementation><version>` e.g. `cpython3.12` or `cp312`
Expand Down
2 changes: 2 additions & 0 deletions crates/uv/tests/it/help.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -272,6 +272,8 @@ fn help_subcommand() {

- `<version>` e.g. `3`, `3.12`, `3.12.3`
- `<version-specifier>` e.g. `>=3.12,<3.13`
- `<version><short-variant>` (e.g., `3.13t`, `3.12.0d`)
- `<version>+<variant>` (e.g., `3.13+freethreaded`, `3.12.0+debug`)
- `<implementation>` e.g. `cpython` or `cp`
- `<implementation>@<version>` e.g. `cpython@3.12`
- `<implementation><version>` e.g. `cpython3.12` or `cp312`
Expand Down
36 changes: 35 additions & 1 deletion docs/concepts/python-versions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,8 @@ The following Python version request formats are supported:

- `<version>` (e.g., `3`, `3.12`, `3.12.3`)
- `<version-specifier>` (e.g., `>=3.12,<3.13`)
- `<version><short-variant>` (e.g., `3.13t`, `3.12.0d`)
- `<version>+<variant>` (e.g., `3.13+freethreaded`, `3.12.0+debug`)
- `<implementation>` (e.g., `cpython` or `cp`)
- `<implementation>@<version>` (e.g., `cpython@3.12`)
- `<implementation><version>` (e.g., `cpython3.12` or `cp312`)
Expand Down Expand Up @@ -315,7 +317,7 @@ a system Python version, uv will use the first compatible version — not the ne
If a Python version cannot be found on the system, uv will check for a compatible managed Python
version download.

### Python pre-releases
## Python pre-releases

Python pre-releases will not be selected by default. Python pre-releases will be used if there is no
other available installation matching the request. For example, if only a pre-release version is
Expand All @@ -326,6 +328,38 @@ and the pre-release version will be used.
If a pre-release Python version is available and matches the request, uv will not download a stable
Python version instead.

## Free-threaded Python

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`.

## Debug Python variants

uv supports discovering and installing
[debug builds](https://docs.python.org/3.14/using/configure.html#debug-build) of Python, i.e., with
debug assertions enabled.

!!! important

Debug builds of Python are slower and are not appropriate for general use.

Debug builds will be used if there is no other available installation matching the request. For
example, if only a debug version is available it will be used but otherwise a stable release version
will be used. Similarly, if the path to a debug Python executable is provided then no other Python
version matches the request and the debug version will be used.

Debug builds of Python can be explicitly requested with, e.g., `3.13d` or `3.13+debug`.

!!! note

CPython versions installed by uv usually have debug symbols stripped to reduce the distribution
size. These debug builds do not have debug symbols stripped, which can be useful when debugging
Python processes with a C-level debugger.

## Disabling automatic Python downloads

By default, uv will automatically download Python versions when needed.
Expand Down
2 changes: 2 additions & 0 deletions docs/reference/cli.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3279,6 +3279,8 @@ The following Python version request formats are supported:

- `<version>` e.g. `3`, `3.12`, `3.12.3`
- `<version-specifier>` e.g. `>=3.12,<3.13`
- `<version><short-variant>` (e.g., `3.13t`, `3.12.0d`)
- `<version>+<variant>` (e.g., `3.13+freethreaded`, `3.12.0+debug`)
- `<implementation>` e.g. `cpython` or `cp`
- `<implementation>@<version>` e.g. `cpython@3.12`
- `<implementation><version>` e.g. `cpython3.12` or `cp312`
Expand Down
Loading