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

Jump to bottom
Merged
merged 6 commits into from
Sep 22, 2025
Merged

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

merged 6 commits into from
Sep 22, 2025

Conversation

zanieb
Copy link
Member

@zanieb zanieb commented Sep 20, 2025 •
edited
Loading

Closes #12707

@zanieb zanieb added the documentation Improvements or additions to documentation label Sep 20, 2025
@zanieb zanieb temporarily deployed to uv-test-registries September 20, 2025 15:37 — with GitHub Actions Inactive
@zanieb zanieb temporarily deployed to uv-test-registries September 20, 2025 16:04 — with GitHub Actions Inactive
@zanieb
Copy link
Member Author

zanieb commented Sep 20, 2025

cc @geofft

xref #15756

geofft
geofft approved these changes Sep 20, 2025
View reviewed changes
crates/uv-cli/src/lib.rs
///
/// - `<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
Collaborator

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
Member Author

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
Collaborator

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
Member Author

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.

@zanieb zanieb enabled auto-merge (squash) September 22, 2025 13:22
@zanieb zanieb temporarily deployed to uv-test-registries September 22, 2025 13:24 — with GitHub Actions Inactive
geofft
geofft reviewed Sep 22, 2025
View reviewed changes
docs/concepts/python-versions.md Outdated
Comment on lines 344 to 345
debug assertions enabled. These builds also do not have debug symbols stripped, which can be useful
when debugging a Python process with a C-level debugger.
Copy link
Collaborator

Choose a reason for hiding this comment

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

This is less accurate than the phrasing I suggested :) As I understand it, uv will both discover existing --with-pydebug builds on the system (e.g. dnf install python3.14-debug, which gets you a /usr/bin/python3.14d), and install our own managed versions, and in both cases it will only use them if it cannot find a non-debug version. But the lack of stripping of debug symbols only applies to our own debug builds and may not apply to existing discoverable versions. (And it also only applies for now, I would like to do something else about debug symbols in the future.)

Copy link
Member Author

Choose a reason for hiding this comment

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

These are all great reasons not to say this at all imo, it's too complicated :)

Copy link
Member Author

Choose a reason for hiding this comment

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

I changed it.

@zanieb zanieb temporarily deployed to uv-test-registries September 22, 2025 13:42 — with GitHub Actions Inactive
@zanieb zanieb mentioned this pull request Sep 22, 2025
Open
@zanieb zanieb temporarily deployed to uv-test-registries September 22, 2025 13:51 — with GitHub Actions Inactive
@zanieb zanieb merged commit 0edc567 into main Sep 22, 2025
98 checks passed
@zanieb zanieb deleted the zb/ft-debug-docs branch September 22, 2025 13:59
@BrewTestBot BrewTestBot mentioned this pull request Sep 22, 2025
Merged
tmeijn pushed a commit to tmeijn/dotfiles that referenced this pull request Sep 24, 2025
@tmeijn
build(deps): update astral-sh/uv to v0.8.22
8e3707e 
This MR contains the following updates:

| Package | Update | Change |
|---|---|---|
| [astral-sh/uv](https://github.com/astral-sh/uv) | patch | `0.8.17` -> `0.8.22` |

MR created with the help of [el-capitano/tools/renovate-bot](https://gitlab.com/el-capitano/tools/renovate-bot).

**Proposed changes to behavior should be submitted there as MRs.**

---

### Release Notes

<details>
<summary>astral-sh/uv (astral-sh/uv)</summary>

### [`v0.8.22`](https://github.com/astral-sh/uv/blob/HEAD/CHANGELOG.md#0822)

[Compare Source](astral-sh/uv@0.8.21...0.8.22)

Released on 2025-09-23.

##### Python

- Upgrade Pyodide to 0.28.3 ([#&#8203;15999](astral-sh/uv#15999))

##### Security

- Upgrade `astral-tokio-tar` to 0.5.5 which [hardens tar archive extraction](GHSA-3wgq-wrwc-vqmv) ([#&#8203;16004](astral-sh/uv#16004))

### [`v0.8.21`](https://github.com/astral-sh/uv/blob/HEAD/CHANGELOG.md#0821)

[Compare Source](astral-sh/uv@0.8.20...0.8.21)

Released on 2025-09-23.

##### Enhancements

- Refresh lockfile when `--refresh` is provided ([#&#8203;15994](astral-sh/uv#15994))

##### Preview features

Add support for S3 request signing ([#&#8203;15925](astral-sh/uv#15925))

### [`v0.8.20`](https://github.com/astral-sh/uv/blob/HEAD/CHANGELOG.md#0820)

[Compare Source](astral-sh/uv@0.8.19...0.8.20)

Released on 2025-09-22.

##### Enhancements

- Add `--force` flag for `uv cache clean` ([#&#8203;15992](astral-sh/uv#15992))
- Improve resolution errors with proxied packages ([#&#8203;15200](astral-sh/uv#15200))

##### Preview features

- Allow upgrading pre-release versions of the same minor Python version ([#&#8203;15959](astral-sh/uv#15959))

##### Bug fixes

- Hide `freethreaded+debug` Python downloads in `uv python list` ([#&#8203;15985](astral-sh/uv#15985))
- Retain the cache lock and temporary caches during `uv run` and `uvx` ([#&#8203;15990](astral-sh/uv#15990))

##### Documentation

- Add `package` level conflicts to the conflicting dependencies docs ([#&#8203;15963](astral-sh/uv#15963))
- Document pyodide support ([#&#8203;15962](astral-sh/uv#15962))
- Document support for free-threaded and debug Python versions ([#&#8203;15961](astral-sh/uv#15961))
- Expand the contribution docs on issue selection ([#&#8203;15966](astral-sh/uv#15966))
- Tweak title for viewing version in project guide ([#&#8203;15964](astral-sh/uv#15964))

### [`v0.8.19`](https://github.com/astral-sh/uv/blob/HEAD/CHANGELOG.md#0819)

[Compare Source](astral-sh/uv@0.8.18...0.8.19)

Released on 2025-09-19.

##### Python

- Add CPython 3.14.0rc3
- Upgrade OpenSSL to 3.5.3

See the [python-build-standalone release notes](https://github.com/astral-sh/python-build-standalone/releases/tag/20250918) for more details.

##### Bug fixes

- Make `uv cache clean` parallel process safe ([#&#8203;15888](astral-sh/uv#15888))
- Fix implied `platform_machine` marker for `win_arm64` platform tag ([#&#8203;15921](astral-sh/uv#15921))

### [`v0.8.18`](https://github.com/astral-sh/uv/blob/HEAD/CHANGELOG.md#0818)

[Compare Source](astral-sh/uv@0.8.17...0.8.18)

Released on 2025-09-17.

##### Enhancements

- Add PyG packages to torch backend ([#&#8203;15911](astral-sh/uv#15911))
- Add handling for unnamed conda environments in base environment detection ([#&#8203;15681](astral-sh/uv#15681))
- Allow selection of debug build interpreters ([#&#8203;11520](astral-sh/uv#11520))
- Improve `uv init` defaults for native build backend cache keys ([#&#8203;15705](astral-sh/uv#15705))
- Error when `pyproject.toml` target does not exist for dependency groups ([#&#8203;15831](astral-sh/uv#15831))
- Infer check URL from publish URL when known ([#&#8203;15886](astral-sh/uv#15886))
- Support Gitlab CI/CD as a trusted publisher ([#&#8203;15583](astral-sh/uv#15583))
- Add GraalPy 25.0.0 with support for Python 3.12 ([#&#8203;15900](astral-sh/uv#15900))
- Add `--no-clear` to `uv venv` to disable removal prompts ([#&#8203;15795](astral-sh/uv#15795))
- Add conflict detection between `--only-group` and `--extra` flags ([#&#8203;15788](astral-sh/uv#15788))
- Allow `[project]` to be missing from a `pyproject.toml` ([#&#8203;14113](astral-sh/uv#14113))
- Always treat conda environments named `base` and `root` as base environments ([#&#8203;15682](astral-sh/uv#15682))
- Improve log message when direct build for `uv_build` is skipped ([#&#8203;15898](astral-sh/uv#15898))
- Log when the cache is disabled ([#&#8203;15828](astral-sh/uv#15828))
- Show pyx organization name after authenticating ([#&#8203;15823](astral-sh/uv#15823))
- Use `_CONDA_ROOT` to detect Conda base environments ([#&#8203;15680](astral-sh/uv#15680))
- Include blake2b hash in `uv publish` upload form ([#&#8203;15794](astral-sh/uv#15794))
- Fix misleading debug message when removing environments in `uv sync` ([#&#8203;15881](astral-sh/uv#15881))

##### Deprecations

- Deprecate `tool.uv.dev-dependencies` ([#&#8203;15469](astral-sh/uv#15469))
- Revert "feat(ci): build loongarch64 binaries in CI ([#&#8203;15387](astral-sh/uv#15387))" ([#&#8203;15820](astral-sh/uv#15820))

##### Preview features

- Propagate preview flag to client for `native-auth` feature ([#&#8203;15872](astral-sh/uv#15872))
- Store native credentials for realms with the https scheme stripped ([#&#8203;15879](astral-sh/uv#15879))
- Use the root index URL when retrieving credentials from the native store ([#&#8203;15873](astral-sh/uv#15873))

##### Bug fixes

- Fix `uv sync --no-sources` not switching from editable to registry installations ([#&#8203;15234](astral-sh/uv#15234))
- Avoid display of an empty string when a path is the working directory ([#&#8203;15897](astral-sh/uv#15897))
- Allow cached environment reuse with `@latest` ([#&#8203;15827](astral-sh/uv#15827))
- Allow escaping spaces in --env-file handling ([#&#8203;15815](astral-sh/uv#15815))
- Avoid ANSI codes in debug! messages ([#&#8203;15843](astral-sh/uv#15843))
- Improve BSD tag construction ([#&#8203;15829](astral-sh/uv#15829))
- Include SHA when listing lockfile changes ([#&#8203;15817](astral-sh/uv#15817))
- Invert the logic for determining if a path is a base conda environment ([#&#8203;15679](astral-sh/uv#15679))
- Load credentials for explicit members when lowering ([#&#8203;15844](astral-sh/uv#15844))
- Re-add `triton` as a torch backend package ([#&#8203;15910](astral-sh/uv#15910))
- Respect `UV_INSECURE_NO_ZIP_VALIDATION=1` in duplicate header errors ([#&#8203;15912](astral-sh/uv#15912))

##### Documentation

- Add GitHub Actions to PyPI trusted publishing example ([#&#8203;15753](astral-sh/uv#15753))
- Add Coiled integration documentation ([#&#8203;14430](astral-sh/uv#14430))
- Add verbose output to the getting help section ([#&#8203;15915](astral-sh/uv#15915))
- Document `NO_PROXY` support ([#&#8203;15816](astral-sh/uv#15816))
- Document cache-keys for native build backends ([#&#8203;15811](astral-sh/uv#15811))
- Add documentation for dependency group `requires-python` ([#&#8203;14282](astral-sh/uv#14282))

</details>

---

### Configuration

📅 **Schedule**: Branch creation - At any time (no schedule defined), Automerge - At any time (no schedule defined).

🚦 **Automerge**: Disabled by config. Please merge this manually once you are satisfied.

♻ **Rebasing**: Whenever MR becomes conflicted, or you tick the rebase/retry checkbox.

🔕 **Ignore**: Close this MR and you won't be reminded about this update again.

---

 - [ ] <!-- rebase-check -->If you want to rebase/retry this MR, check this box

---

This MR has been generated by [Renovate Bot](https://github.com/renovatebot/renovate).
<!--renovate-debug:eyJjcmVhdGVkSW5WZXIiOiI0MS4xMTUuNiIsInVwZGF0ZWRJblZlciI6IjQxLjEyNS4yIiwidGFyZ2V0QnJhbmNoIjoibWFpbiIsImxhYmVscyI6WyJSZW5vdmF0ZSBCb3QiXX0=-->
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@geofft geofft geofft approved these changes

Assignees

No one assigned

Labels

documentation Improvements or additions to documentation

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

docs: Document the "3.13t" python shortcut for installing freethreaded python

2 participants

@zanieb @geofft