Install and remove managed Python to and from the Windows Registry (PEP 514) (#10634)

## Summary

In preview mode on windows, register und un-register the managed python build standalone installations in the Windows registry following PEP 514.

We write the values defined in the PEP plus the download URL and hash. We add an entry when installing a version, remove an entry when uninstalling and removing all values when uninstalling with `--all`. We update entries only by overwriting existing values, there is no "syncing" involved.

Since they are not official builds, pbs gets a prefix. `py -V:Astral/CPython3.13.1` works, `py -3.13` doesn't.

```
$ py --list-paths                                            
 -V:3.12 *        C:\Users\Konsti\AppData\Local\Programs\Python\Python312\python.exe
 -V:3.11.9        C:\Users\Konsti\.pyenv\pyenv-win\versions\3.11.9\python.exe
 -V:3.11          C:\Users\micro\AppData\Local\Programs\Python\Python311\python.exe
 -V:3.8           C:\Users\micro\AppData\Local\Programs\Python\Python38\python.exe
 -V:Astral/CPython3.13.1 C:\Users\Konsti\AppData\Roaming\uv\data\python\cpython-3.13.1-windows-x86_64-none\python.exe
```

Registry errors are reported but not fatal, except for operations on the company key since it's not bound to any specific python interpreter.

On uninstallation, we prune registry entries that have no matching Python installation (i.e. broken entries).

The code uses the official `windows_registry` crate of the `winreg` crate.

Best reviewed commit-by-commit.

## Test Plan

We're reusing an existing system check to test different (un)installation scenarios.

Author: konstin

.github/workflows/ci.yml

@@ -1733,6 +1733,24 @@ jobs:
       - name: "Validate global Python install"
         run: py -3.13 ./scripts/check_system_python.py --uv ./uv.exe
 
+  # Test our PEP 514 integration that installs Python into the Windows registry.
+  system-test-windows-registry:
+    timeout-minutes: 10
+    needs: build-binary-windows-x86_64
+    name: "check system | windows registry"
+    runs-on: windows-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: "Download binary"
+        uses: actions/download-artifact@v4
+        with:
+          name: uv-windows-x86_64-${{ github.sha }}
+
+      # NB: Run this last, we are modifying the registry
+      - name: "Test PEP 514 registration"
+        run: python ./scripts/check_registry.py --uv ./uv.exe
+
   system-test-choco:
     timeout-minutes: 10
     needs: build-binary-windows-x86_64

crates/uv-python/Cargo.toml

@@ -64,9 +64,9 @@ which = { workspace = true }
 procfs = { workspace = true }
 
 [target.'cfg(target_os = "windows")'.dependencies]
-windows-sys = { workspace = true }
 windows-registry = { workspace = true }
 windows-result = { workspace = true }
+windows-sys = { workspace = true }
 
 [dev-dependencies]
 anyhow = { version = "1.0.89" }

crates/uv-python/src/discovery.rs

@@ -24,13 +24,13 @@ use crate::interpreter::{StatusCodeError, UnexpectedResponseError};
 use crate::managed::ManagedPythonInstallations;
 #[cfg(windows)]
 use crate::microsoft_store::find_microsoft_store_pythons;
-#[cfg(windows)]
-use crate::py_launcher::{registry_pythons, WindowsPython};
 use crate::virtualenv::Error as VirtualEnvError;
 use crate::virtualenv::{
     conda_environment_from_env, virtualenv_from_env, virtualenv_from_working_dir,
     virtualenv_python_executable, CondaEnvironmentKind,
 };
+#[cfg(windows)]
+use crate::windows_registry::{registry_pythons, WindowsPython};
 use crate::{Interpreter, PythonVersion};
 
 /// A request to find a Python installation.
@@ -324,7 +324,7 @@ fn python_executables_from_installed<'a>(
                         }
                     })
                     .inspect(|installation| debug!("Found managed installation `{installation}`"))
-                    .map(|installation| (PythonSource::Managed, installation.executable())))
+                    .map(|installation| (PythonSource::Managed, installation.executable(false))))
             })
     })
     .flatten_ok();

crates/uv-python/src/downloads.rs

@@ -453,7 +453,7 @@ impl ManagedPythonDownload {
             .filter(|download| download.key.libc != Libc::Some(target_lexicon::Environment::Musl))
     }
 
-    pub fn url(&self) -> &str {
+    pub fn url(&self) -> &'static str {
         self.url
     }
 
@@ -465,7 +465,7 @@ impl ManagedPythonDownload {
         self.key.os()
     }
 
-    pub fn sha256(&self) -> Option<&str> {
+    pub fn sha256(&self) -> Option<&'static str> {
         self.sha256
     }
 

crates/uv-python/src/installation.rs

@@ -161,7 +161,7 @@ impl PythonInstallation {
             DownloadResult::Fetched(path) => path,
         };
 
-        let installed = ManagedPythonInstallation::new(path)?;
+        let installed = ManagedPythonInstallation::new(path, download);
         installed.ensure_externally_managed()?;
         installed.ensure_sysconfig_patched()?;
         installed.ensure_canonical_executables()?;
@@ -171,7 +171,7 @@ impl PythonInstallation {
 
         Ok(Self {
             source: PythonSource::Managed,
-            interpreter: Interpreter::query(installed.executable(), cache)?,
+            interpreter: Interpreter::query(installed.executable(false), cache)?,
         })
     }
 
@@ -282,7 +282,7 @@ impl PythonInstallationKey {
         }
     }
 
-    pub fn new_from_version(
+    fn new_from_version(
         implementation: LenientImplementationName,
         version: &PythonVersion,
         os: Os,
@@ -320,6 +320,11 @@ impl PythonInstallationKey {
         .expect("Python installation keys must have valid Python versions")
     }
 
+    /// The version in `x.y.z` format.
+    pub fn sys_version(&self) -> String {
+        format!("{}.{}.{}", self.major, self.minor, self.patch)
+    }
+
     pub fn arch(&self) -> &Arch {
         &self.arch
     }

crates/uv-python/src/lib.rs

@@ -37,13 +37,18 @@ mod microsoft_store;
 pub mod platform;
 mod pointer_size;
 mod prefix;
-#[cfg(windows)]
-mod py_launcher;
 mod python_version;
 mod sysconfig;
 mod target;
 mod version_files;
 mod virtualenv;
+#[cfg(windows)]
+pub mod windows_registry;
+
+#[cfg(windows)]
+pub(crate) const COMPANY_KEY: &str = "Astral";
+#[cfg(windows)]
+pub(crate) const COMPANY_DISPLAY_NAME: &str = "Astral Software Inc.";
 
 #[cfg(not(test))]
 pub(crate) fn current_dir() -> Result<std::path::PathBuf, std::io::Error> {

crates/uv-python/src/macos_dylib.rs

@@ -56,7 +56,7 @@ impl Error {
         };
         warn_user!(
             "Failed to patch the install name of the dynamic library for {}. This may cause issues when building Python native extensions.{}",
-            installation.executable().simplified_display(),
+            installation.executable(false).simplified_display(),
             error
         );
     }

crates/uv-python/src/managed.rs

@@ -16,7 +16,7 @@ use uv_state::{StateBucket, StateStore};
 use uv_static::EnvVars;
 use uv_trampoline_builder::{windows_python_launcher, Launcher};
 
-use crate::downloads::Error as DownloadError;
+use crate::downloads::{Error as DownloadError, ManagedPythonDownload};
 use crate::implementation::{
     Error as ImplementationError, ImplementationName, LenientImplementationName,
 };
@@ -229,7 +229,7 @@ impl ManagedPythonInstallations {
                     .unwrap_or(true)
             })
             .filter_map(|path| {
-                ManagedPythonInstallation::new(path)
+                ManagedPythonInstallation::from_path(path)
                     .inspect_err(|err| {
                         warn!("Ignoring malformed managed Python entry:\n    {err}");
                     })
@@ -294,10 +294,27 @@ pub struct ManagedPythonInstallation {
     path: PathBuf,
     /// An install key for the Python version.
     key: PythonInstallationKey,
+    /// The URL with the Python archive.
+    ///
+    /// Empty when self was constructed from a path.
+    url: Option<&'static str>,
+    /// The SHA256 of the Python archive at the URL.
+    ///
+    /// Empty when self was constructed from a path.
+    sha256: Option<&'static str>,
 }
 
 impl ManagedPythonInstallation {
-    pub fn new(path: PathBuf) -> Result<Self, Error> {
+    pub fn new(path: PathBuf, download: &ManagedPythonDownload) -> Self {
+        Self {
+            path,
+            key: download.key().clone(),
+            url: Some(download.url()),
+            sha256: download.sha256(),
+        }
+    }
+
+    pub(crate) fn from_path(path: PathBuf) -> Result<Self, Error> {
         let key = PythonInstallationKey::from_str(
             path.file_name()
                 .ok_or(Error::NameError("name is empty".to_string()))?
@@ -307,15 +324,23 @@ impl ManagedPythonInstallation {
 
         let path = std::path::absolute(&path).map_err(|err| Error::AbsolutePath(path, err))?;
 
-        Ok(Self { path, key })
+        Ok(Self {
+            path,
+            key,
+            url: None,
+            sha256: None,
+        })
     }
 
     /// The path to this managed installation's Python executable.
     ///
     /// If the installation has multiple execututables i.e., `python`, `python3`, etc., this will
     /// return the _canonical_ executable name which the other names link to. On Unix, this is
     /// `python{major}.{minor}{variant}` and on Windows, this is `python{exe}`.
-    pub fn executable(&self) -> PathBuf {
+    ///
+    /// If windowed is true, `pythonw.exe` is selected over `python.exe` on windows, with no changes
+    /// on non-windows.
+    pub fn executable(&self, windowed: bool) -> PathBuf {
         let implementation = match self.implementation() {
             ImplementationName::CPython => "python",
             ImplementationName::PyPy => "pypy",
@@ -342,6 +367,9 @@ impl ManagedPythonInstallation {
         // On Windows, the executable is just `python.exe` even for alternative variants
         let variant = if cfg!(unix) {
             self.key.variant.suffix()
+        } else if cfg!(windows) && windowed {
+            // Use windowed Python that doesn't open a terminal.
+            "w"
         } else {
             ""
         };
@@ -412,11 +440,11 @@ impl ManagedPythonInstallation {
 
     pub fn satisfies(&self, request: &PythonRequest) -> bool {
         match request {
-            PythonRequest::File(path) => self.executable() == *path,
+            PythonRequest::File(path) => self.executable(false) == *path,
             PythonRequest::Default | PythonRequest::Any => true,
             PythonRequest::Directory(path) => self.path() == *path,
             PythonRequest::ExecutableName(name) => self
-                .executable()
+                .executable(false)
                 .file_name()
                 .is_some_and(|filename| filename.to_string_lossy() == *name),
             PythonRequest::Implementation(implementation) => {
@@ -432,7 +460,7 @@ impl ManagedPythonInstallation {
 
     /// Ensure the environment contains the canonical Python executable names.
     pub fn ensure_canonical_executables(&self) -> Result<(), Error> {
-        let python = self.executable();
+        let python = self.executable(false);
 
         let canonical_names = &["python"];
 
@@ -539,7 +567,7 @@ impl ManagedPythonInstallation {
     ///
     /// If the file already exists at the target path, an error will be returned.
     pub fn create_bin_link(&self, target: &Path) -> Result<(), Error> {
-        let python = self.executable();
+        let python = self.executable(false);
 
         let bin = target.parent().ok_or(Error::NoExecutableDirectory)?;
         fs_err::create_dir_all(bin).map_err(|err| Error::ExecutableDirectory {
@@ -585,15 +613,15 @@ impl ManagedPythonInstallation {
     /// [`ManagedPythonInstallation::create_bin_link`].
     pub fn is_bin_link(&self, path: &Path) -> bool {
         if cfg!(unix) {
-            is_same_file(path, self.executable()).unwrap_or_default()
+            is_same_file(path, self.executable(false)).unwrap_or_default()
         } else if cfg!(windows) {
             let Some(launcher) = Launcher::try_from_path(path).unwrap_or_default() else {
                 return false;
             };
             if !matches!(launcher.kind, uv_trampoline_builder::LauncherKind::Python) {
                 return false;
             }
-            launcher.python_path == self.executable()
+            launcher.python_path == self.executable(false)
         } else {
             unreachable!("Only Windows and Unix are supported")
         }
@@ -627,6 +655,14 @@ impl ManagedPythonInstallation {
         // Do not upgrade if the patch versions are the same
         self.key.patch != other.key.patch
     }
+
+    pub fn url(&self) -> Option<&'static str> {
+        self.url
+    }
+
+    pub fn sha256(&self) -> Option<&'static str> {
+        self.sha256
+    }
 }
 
 /// Generate a platform portion of a key from the environment.

crates/uv-python/src/microsoft_store.rs

@@ -3,7 +3,7 @@
 //!
 //! Effectively a port of <https://github.com/python/cpython/blob/58ce131037ecb34d506a613f21993cde2056f628/PC/launcher2.c#L1744>
 
-use crate::py_launcher::WindowsPython;
+use crate::windows_registry::WindowsPython;
 use crate::PythonVersion;
 use itertools::Either;
 use std::env;

crates/uv-python/src/platform.rs

@@ -102,6 +102,10 @@ impl Arch {
             variant: None,
         }
     }
+
+    pub fn family(&self) -> target_lexicon::Architecture {
+        self.family
+    }
 }
 
 impl Display for Libc {