Add uv python install --default

Author: zanieb

crates/uv-cli/src/lib.rs

@@ -3904,6 +3904,21 @@ pub struct PythonInstallArgs {
     /// installed.
     #[arg(long, short, alias = "force")]
     pub reinstall: bool,
+
+    /// Use as the default Python version.
+    ///
+    /// By default, only a `python{major}.{minor}` executable is installed, e.g., `python3.10`. When
+    /// the `--default` flag is used, `python{major}`, e.g., `python3`, and `python` executables are
+    /// also installed.
+    ///
+    /// Alternative Python variants will still include their tag. For example, installing
+    /// 3.13+freethreaded with `--default` will include in `python3t` and `pythont`, not `python3`
+    /// and `python`.
+    ///
+    /// If multiple Python versions are requested during the installation, the first request will be
+    /// the default.
+    #[arg(long)]
+    pub default: bool,
 }
 
 #[derive(Args)]

crates/uv-python/src/installation.rs

@@ -306,8 +306,8 @@ impl PythonInstallationKey {
         &self.libc
     }
 
-    /// Return a canonical name for a versioned executable.
-    pub fn versioned_executable_name(&self) -> String {
+    /// Return a canonical name for a minor versioned executable.
+    pub fn executable_name_minor(&self) -> String {
         format!(
             "python{maj}.{min}{var}{exe}",
             maj = self.major,
@@ -316,6 +316,25 @@ impl PythonInstallationKey {
             exe = std::env::consts::EXE_SUFFIX
         )
     }
+
+    /// Return a canonical name for a major versioned executable.
+    pub fn executable_name_major(&self) -> String {
+        format!(
+            "python{maj}{var}{exe}",
+            maj = self.major,
+            var = self.variant.suffix(),
+            exe = std::env::consts::EXE_SUFFIX
+        )
+    }
+
+    /// Return a canonical name for an un-versioned executable.
+    pub fn executable_name(&self) -> String {
+        format!(
+            "python{var}{exe}",
+            var = self.variant.suffix(),
+            exe = std::env::consts::EXE_SUFFIX
+        )
+    }
 }
 
 impl fmt::Display for PythonInstallationKey {

crates/uv-python/src/managed.rs

@@ -475,26 +475,24 @@ impl ManagedPythonInstallation {
         Ok(())
     }
 
-    /// Create a link to the Python executable in the given `bin` directory.
-    pub fn create_bin_link(&self, bin: &Path) -> Result<PathBuf, Error> {
+    /// Create a link to the managed Python executable.
+    pub fn create_bin_link(&self, target: &Path) -> Result<(), Error> {
         let python = self.executable();
 
+        let bin = target.parent().ok_or(Error::NoExecutableDirectory)?;
         fs_err::create_dir_all(bin).map_err(|err| Error::ExecutableDirectory {
             to: bin.to_path_buf(),
             err,
         })?;
 
-        // TODO(zanieb): Add support for a "default" which
-        let python_in_bin = bin.join(self.key.versioned_executable_name());
-
-        match uv_fs::symlink_copy_fallback_file(&python, &python_in_bin) {
-            Ok(()) => Ok(python_in_bin),
+        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: python_in_bin,
+                to: target.to_path_buf(),
                 err,
             }),
         }

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

@@ -29,10 +29,12 @@ use crate::commands::{elapsed, ExitStatus};
 use crate::printer::Printer;
 
 /// Download and install Python versions.
+#[allow(clippy::fn_params_excessive_bools)]
 pub(crate) async fn install(
     project_dir: &Path,
     targets: Vec<String>,
     reinstall: bool,
+    default: bool,
     python_downloads: PythonDownloads,
     native_tls: bool,
     connectivity: Connectivity,
@@ -99,6 +101,7 @@ pub(crate) async fn install(
                     installation.key().green(),
                 )?;
             }
+            // TODO(zanieb): Ensure executables are linked for already-installed versions
             if reinstall {
                 uninstalled.insert(installation.key());
                 unfilled_requests.push(download_request);
@@ -186,35 +189,46 @@ pub(crate) async fn install(
                 let managed = ManagedPythonInstallation::new(path.clone())?;
                 managed.ensure_externally_managed()?;
                 managed.ensure_canonical_executables()?;
-                match managed.create_bin_link(&bin) {
-                    Ok(executable) => {
-                        debug!("Installed {} executable to {}", key, executable.display());
-                    }
-                    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)?;
-                            let executable = managed.create_bin_link(&bin)?;
-                            debug!(
-                                "Replaced {} executable at {}",
-                                key,
-                                executable.user_display()
-                            );
-                        } else {
-                            if !is_same_file(&to, &from).unwrap_or_default() {
-                                errors.push((
-                                    key,
-                                    anyhow::anyhow!(
-                                        "Executable already exists at `{}`. Use `--reinstall` to force replacement.",
-                                        to.user_display()
-                                    ),
-                                ));
+
+                // TODO(zanieb): Only apply `default` for the _first_ requested version
+                let targets = if default {
+                    vec![
+                        managed.key().executable_name_minor(),
+                        managed.key().executable_name_major(),
+                        managed.key().executable_name(),
+                    ]
+                } else {
+                    vec![managed.key().executable_name_minor()]
+                };
+
+                for target in targets {
+                    let target = bin.join(target);
+                    match managed.create_bin_link(&target) {
+                        Ok(()) => {
+                            debug!("Installed {} executable to {}", key, target.display());
+                        }
+                        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)?;
+                                managed.create_bin_link(&target)?;
+                                debug!("Replaced {} executable at {}", key, target.user_display());
+                            } else {
+                                if !is_same_file(&to, &from).unwrap_or_default() {
+                                    errors.push((
+                                        key,
+                                        anyhow::anyhow!(
+                                            "Executable already exists at `{}`. Use `--reinstall` to force replacement.",
+                                            to.user_display()
+                                        ),
+                                    ));
+                                }
                             }
                         }
+                        Err(err) => return Err(err.into()),
                     }
-                    Err(err) => return Err(err.into()),
                 }
             }
             Err(err) => {
@@ -280,7 +294,7 @@ pub(crate) async fn install(
                         " {} {} ({})",
                         "+".green(),
                         event.key.bold(),
-                        event.key.versioned_executable_name()
+                        event.key.executable_name_minor()
                     )?;
                 }
                 ChangeEventKind::Removed => {
@@ -289,7 +303,7 @@ pub(crate) async fn install(
                         " {} {} ({})",
                         "-".red(),
                         event.key.bold(),
-                        event.key.versioned_executable_name()
+                        event.key.executable_name_minor()
                     )?;
                 }
                 ChangeEventKind::Reinstalled => {
@@ -298,7 +312,7 @@ pub(crate) async fn install(
                         " {} {} ({})",
                         "~".yellow(),
                         event.key.bold(),
-                        event.key.versioned_executable_name()
+                        event.key.executable_name_minor()
                     )?;
                 }
             }

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

@@ -141,8 +141,10 @@ async fn do_uninstall(
         // leave broken links behind, i.e., if the user created them.
         .filter(|path| {
             matching_installations.iter().any(|installation| {
-                path.file_name().and_then(|name| name.to_str())
-                    == Some(&installation.key().versioned_executable_name())
+                let name = path.file_name().and_then(|name| name.to_str());
+                name == Some(&installation.key().executable_name_minor())
+                    || name == Some(&installation.key().executable_name_major())
+                    || name == Some(&installation.key().executable_name())
             })
         })
         // Only include Python executables that match the installations
@@ -222,7 +224,7 @@ async fn do_uninstall(
                         " {} {} ({})",
                         "-".red(),
                         event.key.bold(),
-                        event.key.versioned_executable_name()
+                        event.key.executable_name_minor()
                     )?;
                 }
                 _ => unreachable!(),

crates/uv/src/lib.rs

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

crates/uv/src/settings.rs

@@ -646,15 +646,24 @@ impl PythonDirSettings {
 pub(crate) struct PythonInstallSettings {
     pub(crate) targets: Vec<String>,
     pub(crate) reinstall: bool,
+    pub(crate) default: 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,
+            default,
+        } = args;
 
-        Self { targets, reinstall }
+        Self {
+            targets,
+            reinstall,
+            default,
+        }
     }
 }
 

crates/uv/tests/it/help.rs

@@ -486,6 +486,20 @@ fn help_subsubcommand() {
               
               By default, uv will exit successfully if the version is already installed.
 
+          --default
+              Use as the default Python version.
+              
+              By default, only a `python{major}.{minor}` executable is installed, e.g., `python3.10`.
+              When the `--default` flag is used, `python{major}`, e.g., `python3`, and `python`
+              executables are also installed.
+              
+              Alternative Python variants will still include their tag. For example, installing
+              3.13+freethreaded with `--default` will include in `python3t` and `pythont`, not `python3`
+              and `python`.
+              
+              If multiple Python versions are requested during the installation, the first request will
+              be the default.
+
     Cache options:
       -n, --no-cache
               Avoid reading from or writing to the cache, instead using a temporary directory for the
@@ -716,6 +730,7 @@ fn help_flag_subsubcommand() {
 
     Options:
       -r, --reinstall  Reinstall the requested Python version, if it's already installed
+          --default    Use as the default Python version
 
     Cache options:
       -n, --no-cache               Avoid reading from or writing to the cache, instead using a temporary