mirrors/uv
1
0
Fork 0
mirror of https://github.com/astral-sh/uv.git synced 2025-08-31 07:47:27 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 3

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

Browse source 
## 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.
This commit is contained in:
konsti 2025-01-23 15:13:41 +01:00 • committed by GitHub
parent a497176818
commit db4ab9dc8a
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
17 changed files with 831 additions and 301 deletions
Download patch file Download diff file Expand all files Collapse all files

2
crates/uv-python/Cargo.toml
View file

@ -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" }

6
crates/uv-python/src/discovery.rs
View file

@ -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();

4
crates/uv-python/src/downloads.rs
View file

@ -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
}

11
crates/uv-python/src/installation.rs
View file

@ -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
}

9
crates/uv-python/src/lib.rs
View file

@ -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> {

2
crates/uv-python/src/macos_dylib.rs
View file

@ -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
);
}

58
crates/uv-python/src/managed.rs
View file

@ -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,7 +324,12 @@ 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.
@ -315,7 +337,10 @@ impl ManagedPythonInstallation {
/// 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,7 +613,7 @@ 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;
@ -593,7 +621,7 @@ impl ManagedPythonInstallation {
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.

2
crates/uv-python/src/microsoft_store.rs
View file

@ -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;

4
crates/uv-python/src/platform.rs
View file

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

98
crates/uv-python/src/py_launcher.rs
View file

@ -1,98 +0,0 @@
use crate::PythonVersion;
use std::cmp::Ordering;
use std::path::PathBuf;
use std::str::FromStr;
use tracing::debug;
use windows_registry::{Key, CURRENT_USER, LOCAL_MACHINE};
/// A Python interpreter found in the Windows registry through PEP 514 or from a known Microsoft
/// Store path.
///
/// There are a lot more (optional) fields defined in PEP 514, but we only care about path and
/// version here, for everything else we probe with a Python script.
#[derive(Debug, Clone)]
pub(crate) struct WindowsPython {
pub(crate) path: PathBuf,
pub(crate) version: Option<PythonVersion>,
}
/// Find all Pythons registered in the Windows registry following PEP 514.
pub(crate) fn registry_pythons() -> Result<Vec<WindowsPython>, windows_result::Error> {
let mut registry_pythons = Vec::new();
for root_key in [CURRENT_USER, LOCAL_MACHINE] {
let Ok(key_python) = root_key.open(r"Software\Python") else {
continue;
};
for company in key_python.keys()? {
// Reserved name according to the PEP.
if company == "PyLauncher" {
continue;
}
let Ok(company_key) = key_python.open(&company) else {
// Ignore invalid entries
continue;
};
for tag in company_key.keys()? {
let tag_key = company_key.open(&tag)?;
if let Some(registry_python) = read_registry_entry(&company, &tag, &tag_key) {
registry_pythons.push(registry_python);
}
}
}
}
// The registry has no natural ordering, so we're processing the latest version first.
registry_pythons.sort_by(|a, b| {
match (&a.version, &b.version) {
// Place entries with a version before those without a version.
(Some(_), None) => Ordering::Greater,
(None, Some(_)) => Ordering::Less,
// We want the highest version on top, which is the inverse from the regular order. The
// path is an arbitrary but stable tie-breaker.
(Some(version_a), Some(version_b)) => {
version_a.cmp(version_b).reverse().then(a.path.cmp(&b.path))
}
// Sort the entries without a version arbitrarily, but stable (by path).
(None, None) => a.path.cmp(&b.path),
}
});
Ok(registry_pythons)
}
fn read_registry_entry(company: &str, tag: &str, tag_key: &Key) -> Option<WindowsPython> {
// `ExecutablePath` is mandatory for executable Pythons.
let Ok(executable_path) = tag_key
.open("InstallPath")
.and_then(|install_path| install_path.get_value("ExecutablePath"))
.and_then(String::try_from)
else {
debug!(
r"Python interpreter in the registry is not executable: `Software\Python\{}\{}",
company, tag
);
return None;
};
// `SysVersion` is optional.
let version = tag_key
.get_value("SysVersion")
.and_then(String::try_from)
.ok()
.and_then(|s| match PythonVersion::from_str(&s) {
Ok(version) => Some(version),
Err(err) => {
debug!(
"Skipping Python interpreter ({executable_path}) \
with invalid registry version {s}: {err}",
);
None
}
});
Some(WindowsPython {
path: PathBuf::from(executable_path),
version,
})
}

275
crates/uv-python/src/windows_registry.rs Normal file
View file

@ -0,0 +1,275 @@
//! PEP 514 interactions with the Windows registry.
use crate::managed::ManagedPythonInstallation;
use crate::platform::Arch;
use crate::{PythonInstallationKey, PythonVersion, COMPANY_DISPLAY_NAME, COMPANY_KEY};
use std::cmp::Ordering;
use std::collections::HashSet;
use std::path::PathBuf;
use std::str::FromStr;
use target_lexicon::PointerWidth;
use thiserror::Error;
use tracing::debug;
use uv_warnings::{warn_user, warn_user_once};
use windows_registry::{Key, Value, CURRENT_USER, HSTRING, LOCAL_MACHINE};
use windows_result::HRESULT;
use windows_sys::Win32::Foundation::ERROR_FILE_NOT_FOUND;
/// Code returned when the registry key doesn't exist.
const ERROR_NOT_FOUND: HRESULT = HRESULT::from_win32(ERROR_FILE_NOT_FOUND);
/// A Python interpreter found in the Windows registry through PEP 514 or from a known Microsoft
/// Store path.
///
/// There are a lot more (optional) fields defined in PEP 514, but we only care about path and
/// version here, for everything else we probe with a Python script.
#[derive(Debug, Clone)]
pub(crate) struct WindowsPython {
pub(crate) path: PathBuf,
pub(crate) version: Option<PythonVersion>,
}
/// Find all Pythons registered in the Windows registry following PEP 514.
pub(crate) fn registry_pythons() -> Result<Vec<WindowsPython>, windows_result::Error> {
let mut registry_pythons = Vec::new();
// Prefer `HKEY_CURRENT_USER` over `HKEY_LOCAL_MACHINE`
for root_key in [CURRENT_USER, LOCAL_MACHINE] {
let Ok(key_python) = root_key.open(r"Software\Python") else {
continue;
};
for company in key_python.keys()? {
// Reserved name according to the PEP.
if company == "PyLauncher" {
continue;
}
let Ok(company_key) = key_python.open(&company) else {
// Ignore invalid entries
continue;
};
for tag in company_key.keys()? {
let tag_key = company_key.open(&tag)?;
if let Some(registry_python) = read_registry_entry(&company, &tag, &tag_key) {
registry_pythons.push(registry_python);
}
}
}
}
// The registry has no natural ordering, so we're processing the latest version first.
registry_pythons.sort_by(|a, b| {
match (&a.version, &b.version) {
// Place entries with a version before those without a version.
(Some(_), None) => Ordering::Greater,
(None, Some(_)) => Ordering::Less,
// We want the highest version on top, which is the inverse from the regular order. The
// path is an arbitrary but stable tie-breaker.
(Some(version_a), Some(version_b)) => {
version_a.cmp(version_b).reverse().then(a.path.cmp(&b.path))
}
// Sort the entries without a version arbitrarily, but stable (by path).
(None, None) => a.path.cmp(&b.path),
}
});
Ok(registry_pythons)
}
fn read_registry_entry(company: &str, tag: &str, tag_key: &Key) -> Option<WindowsPython> {
// `ExecutablePath` is mandatory for executable Pythons.
let Ok(executable_path) = tag_key
.open("InstallPath")
.and_then(|install_path| install_path.get_value("ExecutablePath"))
.and_then(String::try_from)
else {
debug!(
r"Python interpreter in the registry is not executable: `Software\Python\{}\{}",
company, tag
);
return None;
};
// `SysVersion` is optional.
let version = tag_key
.get_value("SysVersion")
.and_then(String::try_from)
.ok()
.and_then(|s| match PythonVersion::from_str(&s) {
Ok(version) => Some(version),
Err(err) => {
debug!(
"Skipping Python interpreter ({executable_path}) \
with invalid registry version {s}: {err}",
);
None
}
});
Some(WindowsPython {
path: PathBuf::from(executable_path),
version,
})
}
#[derive(Debug, Error)]
pub enum ManagedPep514Error {
#[error("Windows has an unknown pointer width for arch: `{_0}`")]
InvalidPointerSize(Arch),
}
/// Register a managed Python installation in the Windows registry following PEP 514.
pub fn create_registry_entry(
installation: &ManagedPythonInstallation,
errors: &mut Vec<(PythonInstallationKey, anyhow::Error)>,
) -> Result<(), ManagedPep514Error> {
let pointer_width = match installation.key().arch().family().pointer_width() {
Ok(PointerWidth::U32) => 32,
Ok(PointerWidth::U64) => 64,
_ => {
return Err(ManagedPep514Error::InvalidPointerSize(
*installation.key().arch(),
));
}
};
if let Err(err) = write_registry_entry(installation, pointer_width) {
errors.push((installation.key().clone(), err.into()));
}
Ok(())
}
fn write_registry_entry(
installation: &ManagedPythonInstallation,
pointer_width: i32,
) -> windows_registry::Result<()> {
// We currently just overwrite all known keys, without removing prior entries first
// Similar to using the bin directory in HOME on Unix, we only install for the current user
// on Windows.
let company = CURRENT_USER.create(format!("Software\\Python\\{COMPANY_KEY}"))?;
company.set_string("DisplayName", COMPANY_DISPLAY_NAME)?;
company.set_string("SupportUrl", "https://github.com/astral-sh/uv")?;
// Ex) CPython3.13.1
let tag = company.create(registry_python_tag(installation.key()))?;
let display_name = format!(
"{} {} ({}-bit)",
installation.key().implementation().pretty(),
installation.key().version(),
pointer_width
);
tag.set_string("DisplayName", &display_name)?;
tag.set_string("SupportUrl", "https://github.com/astral-sh/uv")?;
tag.set_string("Version", &installation.key().version().to_string())?;
tag.set_string("SysVersion", &installation.key().sys_version())?;
tag.set_string("SysArchitecture", &format!("{pointer_width}bit"))?;
// Store `python-build-standalone` release
if let Some(url) = installation.url() {
tag.set_string("DownloadUrl", url)?;
}
if let Some(sha256) = installation.sha256() {
tag.set_string("DownloadSha256", sha256)?;
}
let install_path = tag.create("InstallPath")?;
install_path.set_value(
"",
&Value::from(&HSTRING::from(installation.path().as_os_str())),
)?;
install_path.set_value(
"ExecutablePath",
&Value::from(&HSTRING::from(installation.executable(false).as_os_str())),
)?;
install_path.set_value(
"WindowedExecutablePath",
&Value::from(&HSTRING::from(installation.executable(true).as_os_str())),
)?;
Ok(())
}
fn registry_python_tag(key: &PythonInstallationKey) -> String {
format!("{}{}", key.implementation().pretty(), key.version())
}
/// Remove requested Python entries from the Windows Registry (PEP 514).
pub fn remove_registry_entry<'a>(
installations: impl IntoIterator<Item = &'a ManagedPythonInstallation>,
all: bool,
errors: &mut Vec<(PythonInstallationKey, anyhow::Error)>,
) {
let astral_key = format!("Software\\Python\\{COMPANY_KEY}");
if all {
debug!("Removing registry key HKCU:\\{}", astral_key);
if let Err(err) = CURRENT_USER.remove_tree(&astral_key) {
if err.code() == ERROR_NOT_FOUND {
debug!("No registry entries to remove, no registry key {astral_key}");
} else {
warn_user!("Failed to clear registry entries under {astral_key}: {err}");
}
}
return;
}
for installation in installations {
let python_tag = registry_python_tag(installation.key());
let python_entry = format!("{astral_key}\\{python_tag}");
debug!("Removing registry key HKCU:\\{}", python_entry);
if let Err(err) = CURRENT_USER.remove_tree(&python_entry) {
if err.code() == ERROR_NOT_FOUND {
debug!(
"No registry entries to remove for {}, no registry key {}",
installation.key(),
python_entry
);
} else {
errors.push((
installation.key().clone(),
anyhow::Error::new(err)
.context("Failed to clear registry entries under HKCU:\\{python_entry}"),
));
}
};
}
}
/// Remove Python entries from the Windows Registry (PEP 514) that are not matching any
/// installation.
pub fn remove_orphan_registry_entries(installations: &[ManagedPythonInstallation]) {
let keep: HashSet<_> = installations
.iter()
.map(|installation| registry_python_tag(installation.key()))
.collect();
let astral_key = format!("Software\\Python\\{COMPANY_KEY}");
let key = match CURRENT_USER.open(&astral_key) {
Ok(subkeys) => subkeys,
Err(err) if err.code() == ERROR_NOT_FOUND => {
return;
}
Err(err) => {
// TODO(konsti): We don't have an installation key here.
warn_user_once!("Failed to open HKCU:\\{astral_key}: {err}");
return;
}
};
// Separate assignment since `keys()` creates a borrow.
let subkeys = match key.keys() {
Ok(subkeys) => subkeys,
Err(err) => {
// TODO(konsti): We don't have an installation key here.
warn_user_once!("Failed to list subkeys of HKCU:\\{astral_key}: {err}");
return;
}
};
for subkey in subkeys {
if keep.contains(&subkey) {
continue;
}
let python_entry = format!("{astral_key}\\{subkey}");
debug!("Removing orphan registry key HKCU:\\{}", python_entry);
if let Err(err) = CURRENT_USER.remove_tree(&python_entry) {
// TODO(konsti): We don't have an installation key here.
warn_user_once!("Failed to remove orphan registry key HKCU:\\{python_entry}: {err}");
};
}
}