Allow pinning managed Python versions to specific build versions #15314

zanieb · 2025-08-15T19:24:15Z

Allows pinning the Python build version via environment variables, e.g., UV_PYTHON_CPYTHON_BUILD=.... Each variable is implementation specific, because they use different versioning schemes.

Updates the Python download metadata to include a build string, so we can filter downloads by the pin. Writes the build version to a file in the managed install, e.g., cpython-3.10.18-macos-aarch64-none/BUILD, so we can filter installed versions by the pin.

Some important follow-up here:

Include the build version in not found errors (when pinned)
Automatically use a remote list of Python downloads to satisfy build versions not present in the latest embedded download metadata

Some less important follow-ups to consider:

Allow using ranges for build version pins

zanieb · 2025-08-20T20:31:26Z

crates/uv/tests/it/common/mod.rs

    /// Add extra standard filtering for Python executable names, e.g., stripping version number
    /// and `.exe` suffixes.
    #[must_use]
    pub fn with_filtered_python_names(mut self) -> Self {


Absolutely nightmarish to get the filters working on Windows and Unix. Hopefully this makes them more robust elsewhere.

zanieb · 2025-08-20T22:56:23Z

crates/uv-python/src/downloads.rs

+/// A wrapper type to display a `ManagedPythonDownload` with its build information.
+pub struct ManagedPythonDownloadWithBuild<'a>(&'a ManagedPythonDownload);
+
+impl Display for ManagedPythonDownloadWithBuild<'_> {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        if let Some(build) = self.0.build {
+            write!(f, "{}+{}", self.0.key, build)
+        } else {
+            write!(f, "{}", self.0.key)
+        }
+    }
+}


I want to make use of this for some error messages to avoid confusion when this is in a request. I'm not sure what the best way to do so is yet though.

crates/uv-python/src/python_version.rs

konstin · 2025-08-21T13:21:31Z

crates/uv-python/src/python_version.rs

+) -> Result<Option<String>, BuildVersionError> {
+    let variable = python_build_version_variable(implementation);
+
+    let Some(build_os) = env::var_os(variable) else {


We should use env::var here, this also avoids using our own error type

I don't want to use env::var here, it will error if not present and I want that to have different behavior. I also want the dedicated error type for when we perform further validation of these values in the future, e.g., we know what a well formed build version looks like.

It makes sense if we add our own validation logic on top.

crates/uv-python/src/downloads.rs

crates/uv-python/src/managed.rs

konstin · 2025-08-21T13:43:43Z

crates/uv-python/src/python_version.rs

 }

+/// Get the environment variable name for the build constraint for a given implementation.
+pub(crate) fn python_build_version_variable(implementation: ImplementationName) -> &'static str {


Should this be a method on implementation name?

It could be 🤔 I wanted to keep all this logic together but I don't feel strongly.

This MR contains the following updates: | Package | Update | Change | |---|---|---| | [astral-sh/uv](https://github.com/astral-sh/uv) | patch | `0.8.13` -> `0.8.14` | 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.14`](https://github.com/astral-sh/uv/blob/HEAD/CHANGELOG.md#0814) [Compare Source](astral-sh/uv@0.8.13...0.8.14) ##### Python - Add managed CPython distributions for aarch64 musl ##### Enhancements - Add `--python-platform` to `uv pip check` ([#15486](astral-sh/uv#15486)) - Add an environment variable for `UV_ISOLATED` ([#15428](astral-sh/uv#15428)) - Add logging to the uv build backend ([#15533](astral-sh/uv#15533)) - Allow more trailing null bytes in zip files ([#15452](astral-sh/uv#15452)) - Allow pinning managed Python versions to specific build versions ([#15314](astral-sh/uv#15314)) - Cache PyTorch wheels by default ([#15481](astral-sh/uv#15481)) - Reject already-installed wheels that don't match the target platform ([#15484](astral-sh/uv#15484)) - Add `--no-install-local` option to `uv sync`, `uv add` and `uv export` ([#15328](astral-sh/uv#15328)) - Include cycle error message in `uv pip` CLI ([#15453](astral-sh/uv#15453)) ##### Preview features - Fix format of `{version}` on `uv format` failure ([#15527](astral-sh/uv#15527)) - Lock during installs in `uv format` to prevent races ([#15551](astral-sh/uv#15551)) - Respect `--project` in `uv format` ([#15438](astral-sh/uv#15438)) - Run `uv format` in the project root ([#15440](astral-sh/uv#15440)) ##### Configuration - Add file-to-CLI overrides for build isolation configuration ([#15437](astral-sh/uv#15437)) - Add file-to-CLI overrides for reinstall configuration ([#15426](astral-sh/uv#15426)) ##### Performance - Cache `WHEEL` and `METADATA` reads in installed distributions ([#15489](astral-sh/uv#15489)) ##### Bug fixes - Avoid erroring when creating `venv` in current working directory ([#15537](astral-sh/uv#15537)) - Avoid introducing unnecessary system dependency on CUDA ([#15449](astral-sh/uv#15449)) - Clear discovered site packages when creating virtual environment ([#15522](astral-sh/uv#15522)) - Read index credentials from the environment during `uv publish` checks ([#15545](astral-sh/uv#15545)) - Refuse to remove non-virtual environments in `uv venv` ([#15538](astral-sh/uv#15538)) - Stop setting `CLICOLOR_FORCE=1` when calling build backends ([#15472](astral-sh/uv#15472)) - Support file or directory removal for Windows symlinks ([#15543](astral-sh/uv#15543)) ##### Documentation - Fix GitHub guide highlight lines ([#15443](astral-sh/uv#15443)) - Move Resolver to new Internals section in the Reference ([#15465](astral-sh/uv#15465)) - Split the "Authentication" page into sections ([#15575](astral-sh/uv#15575)) - Update uninstall docs to mention `uvw.exe` needs to be removed ([#15536](astral-sh/uv#15536)) </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. --- - [ ] If you want to rebase/retry this MR, check this box --- This MR has been generated by [Renovate Bot](https://github.com/renovatebot/renovate).

zanieb added 4 commits August 14, 2025 15:04

Add build to managed Python versions

311d2fa

Allow pinning the Python build version via env vars

3874743

Write BUILD files to managed install directories

f14d7d8

Respect Python build versions during discovery

3212cb3

zanieb force-pushed the zb/download-build-key branch from f12bae7 to 3212cb3 Compare August 15, 2025 19:26

zanieb temporarily deployed to uv-test-registries August 15, 2025 19:30 — with GitHub Actions Inactive

Regenerate reference

4e52016

zanieb temporarily deployed to uv-test-registries August 15, 2025 19:35 — with GitHub Actions Inactive

Clean up some LLM slop

cef77d2

zanieb temporarily deployed to uv-test-registries August 15, 2025 20:20 — with GitHub Actions Inactive

zanieb added enhancement New feature or improvement to existing functionality configuration Settings and such labels Aug 16, 2025

zanieb temporarily deployed to uv-test-registries August 18, 2025 13:04 — with GitHub Actions Inactive

zanieb had a problem deploying to uv-test-publish August 18, 2025 13:04 — with GitHub Actions Failure

Fixes

6a8d153

zanieb force-pushed the zb/download-build-key branch from a0cd585 to 6a8d153 Compare August 18, 2025 14:29

zanieb temporarily deployed to uv-test-registries August 18, 2025 14:36 — with GitHub Actions Inactive

zanieb temporarily deployed to uv-test-registries August 18, 2025 21:49 — with GitHub Actions Inactive

zanieb temporarily deployed to uv-test-publish August 18, 2025 21:49 — with GitHub Actions Inactive

zanieb force-pushed the zb/download-build-key branch from ec1816c to b145177 Compare August 18, 2025 21:54

Make build optional for now

96a2dbd

zanieb force-pushed the zb/download-build-key branch from b145177 to 96a2dbd Compare August 18, 2025 22:09

zanieb added 3 commits August 18, 2025 17:11

Update metadata

87bf022

Require PyPy versions when fetching bundled metadata

9b65242

Merge branch 'main' into zb/download-build-key

dfea019

zanieb temporarily deployed to uv-test-registries August 18, 2025 22:23 — with GitHub Actions Inactive

Change test version

d94d9c1

zanieb temporarily deployed to uv-test-registries August 19, 2025 21:09 — with GitHub Actions Inactive

zanieb temporarily deployed to uv-test-publish August 19, 2025 21:09 — with GitHub Actions Inactive

zanieb temporarily deployed to uv-test-registries August 19, 2025 22:36 — with GitHub Actions Inactive

zanieb temporarily deployed to uv-test-registries August 20, 2025 15:52 — with GitHub Actions Inactive

zanieb force-pushed the zb/download-build-key branch from 1767aee to 4c1c479 Compare August 20, 2025 15:58

zanieb temporarily deployed to uv-test-registries August 20, 2025 16:00 — with GitHub Actions Inactive

zanieb force-pushed the zb/download-build-key branch from 4c1c479 to 9a34dcd Compare August 20, 2025 16:43

zanieb temporarily deployed to uv-test-registries August 20, 2025 16:45 — with GitHub Actions Inactive

zanieb force-pushed the zb/download-build-key branch from 9a34dcd to 5115bd6 Compare August 20, 2025 17:43

zanieb temporarily deployed to uv-test-registries August 20, 2025 17:46 — with GitHub Actions Inactive

zanieb force-pushed the zb/download-build-key branch from 5115bd6 to 39f569d Compare August 20, 2025 18:51

zanieb temporarily deployed to uv-test-registries August 20, 2025 18:53 — with GitHub Actions Inactive

zanieb force-pushed the zb/download-build-key branch from 39f569d to 58c88e7 Compare August 20, 2025 19:22

zanieb temporarily deployed to uv-test-registries August 20, 2025 19:25 — with GitHub Actions Inactive

zanieb force-pushed the zb/download-build-key branch from 58c88e7 to a5291b7 Compare August 20, 2025 19:43

zanieb temporarily deployed to uv-test-registries August 20, 2025 19:45 — with GitHub Actions Inactive

zanieb force-pushed the zb/download-build-key branch from a5291b7 to 97825d0 Compare August 20, 2025 20:00

zanieb temporarily deployed to uv-test-registries August 20, 2025 20:03 — with GitHub Actions Inactive

Filter for pypy

e193380

zanieb force-pushed the zb/download-build-key branch from 97825d0 to e193380 Compare August 20, 2025 20:17

zanieb temporarily deployed to uv-test-registries August 20, 2025 20:19 — with GitHub Actions Inactive

zanieb marked this pull request as ready for review August 20, 2025 20:30

zanieb commented Aug 20, 2025

View reviewed changes

konstin reviewed Aug 21, 2025

View reviewed changes

Review feedback

55b53d7

zanieb temporarily deployed to uv-test-registries August 21, 2025 15:10 — with GitHub Actions Inactive

Merge branch 'main' into zb/download-build-key

02a7047

zanieb temporarily deployed to uv-test-registries August 21, 2025 17:41 — with GitHub Actions Inactive

zanieb merged commit 9b8d698 into main Aug 25, 2025
96 checks passed

zanieb deleted the zb/download-build-key branch August 25, 2025 21:25

BrewTestBot mentioned this pull request Aug 28, 2025

uv 0.8.14 Homebrew/homebrew-core#235418

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Allow pinning managed Python versions to specific build versions #15314

Allow pinning managed Python versions to specific build versions #15314

Uh oh!

zanieb commented Aug 15, 2025 •

edited

Loading

Uh oh!

zanieb Aug 20, 2025

Uh oh!

zanieb Aug 20, 2025

Uh oh!

Uh oh!

konstin Aug 21, 2025

Uh oh!

zanieb Aug 21, 2025 •

edited

Loading

Uh oh!

konstin Aug 21, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

konstin Aug 21, 2025

Uh oh!

zanieb Aug 21, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Allow pinning managed Python versions to specific build versions #15314

Allow pinning managed Python versions to specific build versions #15314

Uh oh!

Conversation

zanieb commented Aug 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

zanieb Aug 20, 2025

Choose a reason for hiding this comment

Uh oh!

zanieb Aug 20, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

konstin Aug 21, 2025

Choose a reason for hiding this comment

Uh oh!

zanieb Aug 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

konstin Aug 21, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

konstin Aug 21, 2025

Choose a reason for hiding this comment

Uh oh!

zanieb Aug 21, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

zanieb commented Aug 15, 2025 •

edited

Loading

zanieb Aug 21, 2025 •

edited

Loading