diff --git a/crates/uv-cli/src/lib.rs b/crates/uv-cli/src/lib.rs index 55fe20acdecfa..206e4ded044f5 100644 --- a/crates/uv-cli/src/lib.rs +++ b/crates/uv-cli/src/lib.rs @@ -437,6 +437,8 @@ pub enum Commands { /// /// - `` 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. `cpython` or `cp` /// - `@` e.g. `cpython@3.12` /// - `` e.g. `cpython3.12` or `cp312` diff --git a/crates/uv/tests/it/help.rs b/crates/uv/tests/it/help.rs index 6a2e9bc487c4b..63e4c15253a40 100644 --- a/crates/uv/tests/it/help.rs +++ b/crates/uv/tests/it/help.rs @@ -272,6 +272,8 @@ fn help_subcommand() { - `` 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. `cpython` or `cp` - `@` e.g. `cpython@3.12` - `` e.g. `cpython3.12` or `cp312` diff --git a/docs/concepts/python-versions.md b/docs/concepts/python-versions.md index 8272e58e5dd7f..360f652ea6512 100644 --- a/docs/concepts/python-versions.md +++ b/docs/concepts/python-versions.md @@ -33,6 +33,8 @@ 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., `cpython` or `cp`) - `@` (e.g., `cpython@3.12`) - `` (e.g., `cpython3.12` or `cp312`) @@ -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 @@ -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. diff --git a/docs/reference/cli.md b/docs/reference/cli.md index 7d0af7503a37b..af702fb5b6a1b 100644 --- a/docs/reference/cli.md +++ b/docs/reference/cli.md @@ -3279,6 +3279,8 @@ 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. `cpython` or `cp` - `@` e.g. `cpython@3.12` - `` e.g. `cpython3.12` or `cp312`