Improve interactions with existing Python executables during install (#…

…8733)

Previously, we'd use the `--reinstall` flag to determine if we should
replace existing Python executables in the bin directory during an
install. There are a few problems with this:

- We replace executables we don't manage
- We can replace executables from other uv Python installations during
reinstall (surprising)
- We don't do the "right" thing when installing patch versions e.g.
installing `3.12.4` then `3.12.6` would fail without the reinstall flag

In `uv tool`, we have separate `--force` and `--reinstall` concepts.
Here we separate the flags (`--force` was previously just a
`--reinstall` alias) and add inspection of the existing executables to
inform a decision on replacement.

In brief, we will:

- Replace any executables with `--force`
- Replace executables for the same installation with `--reinstall`
- Replace executables for an older patch version by default

crates/uv-cli/src/lib.rs

@@ -3946,8 +3946,16 @@ pub struct PythonInstallArgs {
     ///
     /// By default, uv will exit successfully if the version is already
     /// installed.
-    #[arg(long, short, alias = "force")]
+    #[arg(long, short)]
     pub reinstall: bool,
+
+    /// Replace existing Python executables during installation.
+    ///
+    /// By default, uv will refuse to replace executables that it does not manage.
+    ///
+    /// Implies `--reinstall`.
+    #[arg(long, short)]
+    pub force: bool,
 }
 
 #[derive(Args)]

crates/uv-python/src/managed.rs

@@ -88,7 +88,7 @@ pub enum Error {
     LibcDetection(#[from] LibcDetectionError),
 }
 /// A collection of uv-managed Python installations installed on the current system.
-#[derive(Debug, Clone)]
+#[derive(Debug, Clone, Eq, PartialEq)]
 pub struct ManagedPythonInstallations {
     /// The path to the top-level directory of the installed Python versions.
     root: PathBuf,
@@ -542,6 +542,35 @@ impl ManagedPythonInstallation {
             unreachable!("Only Windows and Unix are supported")
         }
     }
+
+    /// Returns `true` if self is a suitable upgrade of other.
+    pub fn is_upgrade_of(&self, other: &ManagedPythonInstallation) -> bool {
+        // Require matching implementation
+        if self.key.implementation != other.key.implementation {
+            return false;
+        }
+        // Require a matching variant
+        if self.key.variant != other.key.variant {
+            return false;
+        }
+        // Require matching minor version
+        if (self.key.major, self.key.minor) != (other.key.major, other.key.minor) {
+            return false;
+        }
+        // Require a newer, or equal patch version (for pre-release upgrades)
+        if self.key.patch <= other.key.patch {
+            return false;
+        }
+        if let Some(other_pre) = other.key.prerelease {
+            if let Some(self_pre) = self.key.prerelease {
+                return self_pre > other_pre;
+            }
+            // Do not upgrade from non-prerelease to prerelease
+            return false;
+        }
+        // Do not upgrade if the patch versions are the same
+        self.key.patch != other.key.patch
+    }
 }
 
 /// Generate a platform portion of a key from the environment.

crates/uv/Cargo.toml

@@ -48,6 +48,7 @@ uv-settings = { workspace = true, features = ["schemars"] }
 uv-shell = { workspace = true }
 uv-static = { workspace = true }
 uv-tool = { workspace = true }
+uv-trampoline-builder = { workspace = true }
 uv-types = { workspace = true }
 uv-virtualenv = { workspace = true }
 uv-version = { workspace = true }
@@ -79,7 +80,6 @@ rayon = { workspace = true }
 regex = { workspace = true }
 reqwest = { workspace = true }
 rustc-hash = { workspace = true }
-same-file = { workspace = true }
 serde = { workspace = true }
 serde_json = { workspace = true }
 tempfile = { workspace = true }

crates/uv/src/commands/python/install.rs

@@ -8,7 +8,6 @@ use futures::StreamExt;
 use itertools::{Either, Itertools};
 use owo_colors::OwoColorize;
 use rustc_hash::{FxHashMap, FxHashSet};
-use same_file::is_same_file;
 use tracing::{debug, trace};
 
 use uv_client::Connectivity;
@@ -20,6 +19,7 @@ use uv_python::managed::{
 };
 use uv_python::{PythonDownloads, PythonInstallationKey, PythonRequest, PythonVersionFile};
 use uv_shell::Shell;
+use uv_trampoline_builder::{Launcher, LauncherKind};
 use uv_warnings::warn_user;
 
 use crate::commands::python::{ChangeEvent, ChangeEventKind};
@@ -73,7 +73,6 @@ struct Changelog {
     installed: FxHashSet<PythonInstallationKey>,
     uninstalled: FxHashSet<PythonInstallationKey>,
     installed_executables: FxHashMap<PythonInstallationKey, Vec<PathBuf>>,
-    uninstalled_executables: FxHashSet<PathBuf>,
 }
 
 impl Changelog {
@@ -104,10 +103,12 @@ impl Changelog {
 }
 
 /// Download and install Python versions.
+#[allow(clippy::fn_params_excessive_bools)]
 pub(crate) async fn install(
     project_dir: &Path,
     targets: Vec<String>,
     reinstall: bool,
+    force: bool,
     python_downloads: PythonDownloads,
     native_tls: bool,
     connectivity: Connectivity,
@@ -281,7 +282,7 @@ pub(crate) async fn install(
             Ok(()) => {
                 debug!(
                     "Installed executable at {} for {}",
-                    target.user_display(),
+                    target.simplified_display(),
                     installation.key(),
                 );
                 changelog.installed.insert(installation.key().clone());
@@ -291,42 +292,102 @@ pub(crate) async fn install(
                     .or_default()
                     .push(target.clone());
             }
-            Err(uv_python::managed::Error::LinkExecutable { from, to, err })
+            Err(uv_python::managed::Error::LinkExecutable { from: _, to, err })
                 if err.kind() == ErrorKind::AlreadyExists =>
             {
-                // TODO(zanieb): Add `--force`
-                if reinstall {
-                    fs_err::remove_file(&to)?;
-                    installation.create_bin_link(&target)?;
-                    debug!(
-                        "Updated executable at {} to {}",
-                        target.user_display(),
-                        installation.key(),
-                    );
-                    changelog.installed.insert(installation.key().clone());
-                    changelog
-                        .installed_executables
-                        .entry(installation.key().clone())
-                        .or_default()
-                        .push(target.clone());
-                    changelog.uninstalled_executables.insert(target);
-                } else {
-                    if !is_same_file(&to, &from).unwrap_or_default() {
-                        errors.push((
+                debug!(
+                    "Inspecting existing executable at {}",
+                    target.simplified_display()
+                );
+
+                // Figure out what installation it references, if any
+                let existing = find_matching_bin_link(&existing_installations, &target);
+
+                match existing {
+                    None => {
+                        // There's an existing executable we don't manage, require `--force`
+                        if !force {
+                            errors.push((
+                                installation.key(),
+                                anyhow::anyhow!(
+                                    "Executable already exists at `{}` but is not managed by uv; use `--force` to replace it",
+                                    to.simplified_display()
+                                ),
+                            ));
+                            continue;
+                        }
+                        debug!(
+                            "Replacing existing executable at `{}` due to `--force`",
+                            target.simplified_display()
+                        );
+                    }
+                    Some(existing) if existing == installation => {
+                        // The existing link points to the same installation, so we're done unless
+                        // they requested we reinstall
+                        if !(reinstall || force) {
+                            debug!(
+                                "Executable at `{}` is already for `{}`",
+                                target.simplified_display(),
+                                installation.key(),
+                            );
+                            continue;
+                        }
+                        debug!(
+                            "Replacing existing executable for `{}` at `{}`",
                             installation.key(),
-                            anyhow::anyhow!(
-                                "Executable already exists at `{}`. Use `--reinstall` to force replacement.",
-                                to.user_display()
-                            ),
-                        ));
+                            target.simplified_display(),
+                        );
+                    }
+                    Some(existing) => {
+                        // The existing link points to a different installation, check if it
+                        // is reasonable to replace
+                        if force {
+                            debug!(
+                                "Replacing existing executable for `{}` at `{}` with executable for `{}` due to `--force` flag",
+                                existing.key(),
+                                target.simplified_display(),
+                                installation.key(),
+                            );
+                        } else {
+                            if installation.is_upgrade_of(existing) {
+                                debug!(
+                                    "Replacing existing executable for `{}` at `{}` with executable for `{}` since it is an upgrade",
+                                    existing.key(),
+                                    target.simplified_display(),
+                                    installation.key(),
+                                );
+                            } else {
+                                debug!(
+                                    "Executable already exists at `{}` for `{}`. Use `--force` to replace it.",
+                                    existing.key(),
+                                    to.simplified_display()
+                                );
+                                continue;
+                            }
+                        }
                     }
                 }
+
+                // Replace the existing link
+                fs_err::remove_file(&to)?;
+                installation.create_bin_link(&target)?;
+                debug!(
+                    "Updated executable at `{}` to `{}`",
+                    target.simplified_display(),
+                    installation.key(),
+                );
+                changelog.installed.insert(installation.key().clone());
+                changelog
+                    .installed_executables
+                    .entry(installation.key().clone())
+                    .or_default()
+                    .push(target.clone());
             }
             Err(err) => return Err(err.into()),
         }
     }
 
-    if changelog.installed.is_empty() {
+    if changelog.installed.is_empty() && errors.is_empty() {
         if is_default_install {
             writeln!(
                 printer.stderr(),
@@ -483,3 +544,32 @@ fn warn_if_not_on_path(bin: &Path) {
         }
     }
 }
+
+/// Find the [`ManagedPythonInstallation`] corresponding to an executable link installed at the
+/// given path, if any.
+///
+/// Like [`ManagedPythonInstallation::is_bin_link`], but this method will only resolve the
+/// given path one time.
+fn find_matching_bin_link<'a>(
+    installations: &'a [ManagedPythonInstallation],
+    path: &Path,
+) -> Option<&'a ManagedPythonInstallation> {
+    let target = if cfg!(unix) {
+        if !path.is_symlink() {
+            return None;
+        }
+        path.read_link().ok()?
+    } else if cfg!(windows) {
+        let launcher = Launcher::try_from_path(path).ok()??;
+        if !matches!(launcher.kind, LauncherKind::Python) {
+            return None;
+        }
+        launcher.python_path
+    } else {
+        unreachable!("Only Windows and Unix are supported")
+    };
+
+    installations
+        .iter()
+        .find(|installation| installation.executable() == target)
+}

crates/uv/src/lib.rs

@@ -1054,6 +1054,7 @@ async fn run(mut cli: Cli) -> Result<ExitStatus> {
                 &project_dir,
                 args.targets,
                 args.reinstall,
+                args.force,
                 globals.python_downloads,
                 globals.native_tls,
                 globals.connectivity,

crates/uv/src/settings.rs

@@ -629,15 +629,24 @@ impl PythonDirSettings {
 pub(crate) struct PythonInstallSettings {
     pub(crate) targets: Vec<String>,
     pub(crate) reinstall: bool,
+    pub(crate) force: bool,
 }
 
 impl PythonInstallSettings {
     /// Resolve the [`PythonInstallSettings`] from the CLI and filesystem configuration.
     #[allow(clippy::needless_pass_by_value)]
     pub(crate) fn resolve(args: PythonInstallArgs, _filesystem: Option<FilesystemOptions>) -> Self {
-        let PythonInstallArgs { targets, reinstall } = args;
+        let PythonInstallArgs {
+            targets,
+            reinstall,
+            force,
+        } = args;
 
-        Self { targets, reinstall }
+        Self {
+            targets,
+            reinstall,
+            force,
+        }
     }
 }
 

crates/uv/tests/it/help.rs

@@ -441,6 +441,13 @@ fn help_subsubcommand() {
               
               By default, uv will exit successfully if the version is already installed.
 
+      -f, --force
+              Replace existing Python executables during installation.
+              
+              By default, uv will refuse to replace executables that it does not manage.
+              
+              Implies `--reinstall`.
+
     Cache options:
       -n, --no-cache
               Avoid reading from or writing to the cache, instead using a temporary directory for the
@@ -646,6 +653,7 @@ fn help_flag_subsubcommand() {
 
     Options:
       -r, --reinstall  Reinstall the requested Python version, if it's already installed
+      -f, --force      Replace existing Python executables during installation
 
     Cache options:
       -n, --no-cache               Avoid reading from or writing to the cache, instead using a temporary