Use trampolines for Python executables on Windows

Author: zanieb

Cargo.lock

@@ -31,6 +31,7 @@ uv-platform-tags = { workspace = true }
 uv-pypi-types = { workspace = true }
 uv-state = { workspace = true }
 uv-static = { workspace = true }
+uv-trampoline-builder = { workspace = true }
 uv-warnings = { workspace = true }
 
 anyhow = { workspace = true }

crates/uv-python/Cargo.toml

@@ -1,15 +1,19 @@
 use core::fmt;
-use fs_err as fs;
-use itertools::Itertools;
 use std::cmp::Reverse;
 use std::ffi::OsStr;
 use std::io::{self, Write};
 use std::path::{Path, PathBuf};
 use std::str::FromStr;
+
+use fs_err::{self as fs, File};
+use itertools::Itertools;
 use thiserror::Error;
 use tracing::{debug, warn};
 
+use uv_fs::{LockedFile, Simplified};
 use uv_state::{StateBucket, StateStore};
+use uv_static::EnvVars;
+use uv_trampoline_builder::windows_python_launcher;
 
 use crate::downloads::Error as DownloadError;
 use crate::implementation::{
@@ -21,9 +25,6 @@ use crate::platform::Error as PlatformError;
 use crate::platform::{Arch, Libc, Os};
 use crate::python_version::PythonVersion;
 use crate::{PythonRequest, PythonVariant};
-use uv_fs::{LockedFile, Simplified};
-use uv_static::EnvVars;
-
 #[derive(Error, Debug)]
 pub enum Error {
     #[error(transparent)]
@@ -74,6 +75,8 @@ pub enum Error {
     },
     #[error("Failed to find a directory to install executables into")]
     NoExecutableDirectory,
+    #[error(transparent)]
+    LauncherError(#[from] uv_trampoline_builder::Error),
     #[error("Failed to read managed Python directory name: {0}")]
     NameError(String),
     #[error("Failed to construct absolute path to managed Python directory: {}", _0.user_display())]
@@ -485,16 +488,34 @@ impl ManagedPythonInstallation {
             err,
         })?;
 
-        match uv_fs::symlink_copy_fallback_file(&python, target) {
-            Ok(()) => Ok(()),
-            Err(err) if err.kind() == io::ErrorKind::NotFound => {
-                Err(Error::MissingExecutable(python.clone()))
+        if cfg!(unix) {
+            match uv_fs::symlink_copy_fallback_file(&python, target) {
+                Ok(()) => Ok(()),
+                Err(err) if err.kind() == io::ErrorKind::NotFound => {
+                    Err(Error::MissingExecutable(python.clone()))
+                }
+                Err(err) => Err(Error::LinkExecutable {
+                    from: python,
+                    to: target.to_path_buf(),
+                    err,
+                }),
             }
-            Err(err) => Err(Error::LinkExecutable {
-                from: python,
-                to: target.to_path_buf(),
-                err,
-            }),
+        } else if cfg!(windows) {
+            // TODO(zanieb): Install GUI launchers as well
+            let launcher = windows_python_launcher(&python, false)?;
+            match File::create(target)?.write_all(launcher.as_ref()) {
+                Ok(()) => Ok(()),
+                Err(err) if err.kind() == io::ErrorKind::NotFound => {
+                    Err(Error::MissingExecutable(python.clone()))
+                }
+                Err(err) => Err(Error::LinkExecutable {
+                    from: python,
+                    to: target.to_path_buf(),
+                    err,
+                }),
+            }
+        } else {
+            unimplemented!("Only Windows and Unix systems are supported.")
         }
     }
 }

crates/uv-python/src/managed.rs

@@ -23,6 +23,8 @@ workspace = true
 
 [dependencies]
 uv-fs = { workspace = true }
+
+fs-err = {workspace = true }
 thiserror = { workspace = true }
 zip = { workspace = true }
 

crates/uv-trampoline-builder/Cargo.toml

@@ -1,6 +1,7 @@
-use std::io::{Cursor, Write};
+use std::io::{self, Cursor, Read, Seek, Write};
 use std::path::Path;
 
+use fs_err::File;
 use thiserror::Error;
 use uv_fs::Simplified;
 use zip::write::FileOptions;
@@ -33,7 +34,7 @@ const LAUNCHER_AARCH64_CONSOLE: &[u8] =
 /// The kind of trampoline launcher to create.
 ///
 /// See [`uv-trampoline::bounce::TrampolineKind`].
-enum LauncherKind {
+pub enum LauncherKind {
     /// The trampoline should execute itself, it's a zipped Python script.
     Script,
     /// The trampoline should just execute Python, it's a proxy Python executable.
@@ -47,6 +48,37 @@ impl LauncherKind {
             Self::Python => b"UVPY",
         }
     }
+
+    /// Read a [`LauncherKind`] from 4 byte buffer.
+    ///
+    /// If the buffer does not contain a matching magic number, `None` is returned.
+    fn try_from_bytes(bytes: [u8; 4]) -> Option<Self> {
+        if &bytes == Self::Script.magic_number() {
+            return Some(Self::Script);
+        }
+        if &bytes == Self::Python.magic_number() {
+            return Some(Self::Python);
+        }
+        None
+    }
+
+    /// Read a [`LauncherKind`] from a file path.
+    ///
+    /// If the file cannot be read, an [`io::Error`] is returned. If the path is not a launcher,
+    /// `None` is returned.
+    pub fn try_from_path(path: &Path) -> Result<Option<Self>, io::Error> {
+        let mut file = File::open(path)?;
+        let mut buffer = [0; 4];
+
+        // If the file is less than four bytes, it's not a launcher.
+        let Ok(_) = file.seek(io::SeekFrom::End(-4)) else {
+            return Ok(None);
+        };
+
+        file.read_exact(&mut buffer)?;
+
+        Ok(Self::try_from_bytes(buffer))
+    }
 }
 
 /// Note: The caller is responsible for adding the path of the wheel we're installing.