Update preview installation of Python executables to be non-fatal (#14612)

Previously, if installation of executables into the bin directory failed
we'd with a non-zero code. However, if we make this behavior the default
we don't want it to be fatal. There's a `--bin` opt-in to _require_
successful executable installation and a `--no-bin` opt-out to silence
the warning / opt-out of installation entirely.

Part of #14296 — we need this
before we can stabilize the behavior.

In #14614 we do the same for writing entries to the Windows registry.

Author: zanieb

crates/uv-cli/src/lib.rs

@@ -4941,6 +4941,19 @@ pub struct PythonInstallArgs {
     #[arg(long, short, env = EnvVars::UV_PYTHON_INSTALL_DIR)]
     pub install_dir: Option<PathBuf>,
 
+    /// Install a Python executable into the `bin` directory.
+    ///
+    /// This is the default behavior. If this flag is provided explicitly, uv will error if the
+    /// executable cannot be installed.
+    ///
+    /// See `UV_PYTHON_BIN_DIR` to customize the target directory.
+    #[arg(long, overrides_with("no_bin"), hide = true)]
+    pub bin: bool,
+
+    /// Do not install a Python executable into the `bin` directory.
+    #[arg(long, overrides_with("bin"), conflicts_with("default"))]
+    pub no_bin: bool,
+
     /// The Python version(s) to install.
     ///
     /// If not provided, the requested Python version(s) will be read from the `UV_PYTHON`
@@ -5003,7 +5016,7 @@ pub struct PythonInstallArgs {
     /// and `python`.
     ///
     /// If multiple Python versions are requested, uv will exit with an error.
-    #[arg(long)]
+    #[arg(long, conflicts_with("no_bin"))]
     pub default: bool,
 }
 

crates/uv-python/src/windows_registry.rs

@@ -129,12 +129,13 @@ fn read_registry_entry(company: &str, tag: &str, tag_key: &Key) -> Option<Window
 pub enum ManagedPep514Error {
     #[error("Windows has an unknown pointer width for arch: `{_0}`")]
     InvalidPointerSize(Arch),
+    #[error("Failed to write registry entry: {0}")]
+    WriteError(#[from] windows_result::Error),
 }
 
 /// 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,
@@ -146,9 +147,7 @@ pub fn create_registry_entry(
         }
     };
 
-    if let Err(err) = write_registry_entry(installation, pointer_width) {
-        errors.push((installation.key().clone(), err.into()));
-    }
+    write_registry_entry(installation, pointer_width)?;
 
     Ok(())
 }

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

@@ -135,6 +135,14 @@ impl Changelog {
     }
 }
 
+#[derive(Debug, Clone, Copy)]
+enum InstallErrorKind {
+    DownloadUnpack,
+    Bin,
+    #[cfg(windows)]
+    Registry,
+}
+
 /// Download and install Python versions.
 #[allow(clippy::fn_params_excessive_bools)]
 pub(crate) async fn install(
@@ -143,6 +151,7 @@ pub(crate) async fn install(
     targets: Vec<String>,
     reinstall: bool,
     upgrade: bool,
+    bin: Option<bool>,
     force: bool,
     python_install_mirror: Option<String>,
     pypy_install_mirror: Option<String>,
@@ -432,12 +441,16 @@ pub(crate) async fn install(
                 downloaded.push(installation.clone());
             }
             Err(err) => {
-                errors.push((download.key().clone(), anyhow::Error::new(err)));
+                errors.push((
+                    InstallErrorKind::DownloadUnpack,
+                    download.key().clone(),
+                    anyhow::Error::new(err),
+                ));
             }
         }
     }
 
-    let bin = if preview.is_enabled() {
+    let bin_dir = if matches!(bin, Some(true)) || preview.is_enabled() {
         Some(python_executable_dir()?)
     } else {
         None
@@ -460,35 +473,46 @@ pub(crate) async fn install(
             continue;
         }
 
-        let bin = bin
+        let bin_dir = bin_dir
             .as_ref()
             .expect("We should have a bin directory with preview enabled")
             .as_path();
 
         let upgradeable = (default || is_default_install)
             || requested_minor_versions.contains(&installation.key().version().python_version());
 
-        create_bin_links(
-            installation,
-            bin,
-            reinstall,
-            force,
-            default,
-            upgradeable,
-            upgrade,
-            is_default_install,
-            first_request,
-            &existing_installations,
-            &installations,
-            &mut changelog,
-            &mut errors,
-            preview,
-        )?;
+        if !matches!(bin, Some(false)) {
+            create_bin_links(
+                installation,
+                bin_dir,
+                reinstall,
+                force,
+                default,
+                upgradeable,
+                upgrade,
+                is_default_install,
+                first_request,
+                &existing_installations,
+                &installations,
+                &mut changelog,
+                &mut errors,
+                preview,
+            );
+        }
 
         if preview.is_enabled() {
             #[cfg(windows)]
             {
-                uv_python::windows_registry::create_registry_entry(installation, &mut errors)?;
+                match uv_python::windows_registry::create_registry_entry(installation) {
+                    Ok(()) => {}
+                    Err(err) => {
+                        errors.push((
+                            InstallErrorKind::Registry,
+                            installation.key().clone(),
+                            err.into(),
+                        ));
+                    }
+                }
             }
         }
     }
@@ -636,24 +660,47 @@ pub(crate) async fn install(
             }
         }
 
-        if preview.is_enabled() {
-            let bin = bin
+        if preview.is_enabled() && !matches!(bin, Some(false)) {
+            let bin_dir = bin_dir
                 .as_ref()
                 .expect("We should have a bin directory with preview enabled")
                 .as_path();
-            warn_if_not_on_path(bin);
+            warn_if_not_on_path(bin_dir);
         }
     }
 
     if !errors.is_empty() {
-        for (key, err) in errors
+        // If there are only bin install errors and the user didn't opt-in, we're only going to warn
+        let fatal = errors
+            .iter()
+            .all(|(kind, _, _)| matches!(kind, InstallErrorKind::Bin))
+            && bin.is_none();
+
+        for (kind, key, err) in errors
             .into_iter()
-            .sorted_unstable_by(|(key_a, _), (key_b, _)| key_a.cmp(key_b))
+            .sorted_unstable_by(|(_, key_a, _), (_, key_b, _)| key_a.cmp(key_b))
         {
+            let (level, verb) = match kind {
+                InstallErrorKind::DownloadUnpack => ("error".red().bold().to_string(), "install"),
+                InstallErrorKind::Bin => {
+                    let level = match bin {
+                        None => "warning".yellow().bold().to_string(),
+                        Some(false) => continue,
+                        Some(true) => "error".red().bold().to_string(),
+                    };
+                    (level, "install executable for")
+                }
+                #[cfg(windows)]
+                InstallErrorKind::Registry => (
+                    "error".red().bold().to_string(),
+                    "install registry entry for",
+                ),
+            };
+
             writeln!(
                 printer.stderr(),
-                "{}: Failed to install {}",
-                "error".red().bold(),
+                "{level}{} Failed to {verb} {}",
+                ":".bold(),
                 key.green()
             )?;
             for err in err.chain() {
@@ -665,13 +712,20 @@ pub(crate) async fn install(
                 )?;
             }
         }
+
+        if fatal {
+            return Ok(ExitStatus::Success);
+        }
+
         return Ok(ExitStatus::Failure);
     }
 
     Ok(ExitStatus::Success)
 }
 
 /// Link the binaries of a managed Python installation to the bin directory.
+///
+/// This function is fallible, but errors are pushed to `errors` instead of being thrown.
 #[allow(clippy::fn_params_excessive_bools)]
 fn create_bin_links(
     installation: &ManagedPythonInstallation,
@@ -686,9 +740,9 @@ fn create_bin_links(
     existing_installations: &[ManagedPythonInstallation],
     installations: &[&ManagedPythonInstallation],
     changelog: &mut Changelog,
-    errors: &mut Vec<(PythonInstallationKey, Error)>,
+    errors: &mut Vec<(InstallErrorKind, PythonInstallationKey, Error)>,
     preview: PreviewMode,
-) -> Result<(), Error> {
+) {
     let targets =
         if (default || is_default_install) && first_request.matches_installation(installation) {
             vec![
@@ -773,6 +827,7 @@ fn create_bin_links(
                                     );
                                 } else {
                                     errors.push((
+                                        InstallErrorKind::Bin,
                                         installation.key().clone(),
                                         anyhow::anyhow!(
                                             "Executable already exists at `{}` but is not managed by uv; use `--force` to replace it",
@@ -848,7 +903,17 @@ fn create_bin_links(
                 }
 
                 // Replace the existing link
-                fs_err::remove_file(&to)?;
+                if let Err(err) = fs_err::remove_file(&to) {
+                    errors.push((
+                        InstallErrorKind::Bin,
+                        installation.key().clone(),
+                        anyhow::anyhow!(
+                            "Executable already exists at `{}` but could not be removed: {err}",
+                            to.simplified_display()
+                        ),
+                    ));
+                    continue;
+                }
 
                 if let Some(existing) = existing {
                     // Ensure we do not report installation of this executable for an existing
@@ -860,7 +925,18 @@ fn create_bin_links(
                         .remove(&target);
                 }
 
-                create_link_to_executable(&target, executable)?;
+                if let Err(err) = create_link_to_executable(&target, executable) {
+                    errors.push((
+                        InstallErrorKind::Bin,
+                        installation.key().clone(),
+                        anyhow::anyhow!(
+                            "Failed to create link at `{}`: {err}",
+                            target.simplified_display()
+                        ),
+                    ));
+                    continue;
+                }
+
                 debug!(
                     "Updated executable at `{}` to {}",
                     target.simplified_display(),
@@ -874,11 +950,14 @@ fn create_bin_links(
                     .insert(target.clone());
             }
             Err(err) => {
-                errors.push((installation.key().clone(), anyhow::Error::new(err)));
+                errors.push((
+                    InstallErrorKind::Bin,
+                    installation.key().clone(),
+                    anyhow::Error::new(err),
+                ));
             }
         }
     }
-    Ok(())
 }
 
 pub(crate) fn format_executables(

crates/uv/src/lib.rs

@@ -1402,6 +1402,7 @@ async fn run(mut cli: Cli) -> Result<ExitStatus> {
                 args.targets,
                 args.reinstall,
                 upgrade,
+                args.bin,
                 args.force,
                 args.python_install_mirror,
                 args.pypy_install_mirror,
@@ -1430,6 +1431,7 @@ async fn run(mut cli: Cli) -> Result<ExitStatus> {
                 args.targets,
                 reinstall,
                 upgrade,
+                args.bin,
                 args.force,
                 args.python_install_mirror,
                 args.pypy_install_mirror,

crates/uv/src/settings.rs

@@ -933,6 +933,7 @@ pub(crate) struct PythonInstallSettings {
     pub(crate) targets: Vec<String>,
     pub(crate) reinstall: bool,
     pub(crate) force: bool,
+    pub(crate) bin: Option<bool>,
     pub(crate) python_install_mirror: Option<String>,
     pub(crate) pypy_install_mirror: Option<String>,
     pub(crate) python_downloads_json_url: Option<String>,
@@ -961,6 +962,8 @@ impl PythonInstallSettings {
             install_dir,
             targets,
             reinstall,
+            bin,
+            no_bin,
             force,
             mirror: _,
             pypy_mirror: _,
@@ -973,6 +976,7 @@ impl PythonInstallSettings {
             targets,
             reinstall,
             force,
+            bin: flag(bin, no_bin, "bin"),
             python_install_mirror: python_mirror,
             pypy_install_mirror: pypy_mirror,
             python_downloads_json_url,
@@ -992,6 +996,7 @@ pub(crate) struct PythonUpgradeSettings {
     pub(crate) pypy_install_mirror: Option<String>,
     pub(crate) python_downloads_json_url: Option<String>,
     pub(crate) default: bool,
+    pub(crate) bin: Option<bool>,
 }
 
 impl PythonUpgradeSettings {
@@ -1013,6 +1018,7 @@ impl PythonUpgradeSettings {
             args.python_downloads_json_url.or(python_downloads_json_url);
         let force = false;
         let default = false;
+        let bin = None;
 
         let PythonUpgradeArgs {
             install_dir,
@@ -1030,6 +1036,7 @@ impl PythonUpgradeSettings {
             pypy_install_mirror: pypy_mirror,
             python_downloads_json_url,
             default,
+            bin,
         }
     }
 }

crates/uv/tests/it/help.rs

@@ -504,6 +504,9 @@ fn help_subsubcommand() {
               
               [env: UV_PYTHON_INSTALL_DIR=]
 
+          --no-bin
+              Do not install a Python executable into the `bin` directory
+
           --mirror <MIRROR>
               Set the URL to use as the source for downloading Python installations.
               
@@ -790,6 +793,8 @@ fn help_flag_subsubcommand() {
     Options:
       -i, --install-dir <INSTALL_DIR>
               The directory to store the Python installation in [env: UV_PYTHON_INSTALL_DIR=]
+          --no-bin
+              Do not install a Python executable into the `bin` directory
           --mirror <MIRROR>
               Set the URL to use as the source for downloading Python installations [env:
               UV_PYTHON_INSTALL_MIRROR=]