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/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

crates/uv/tests/it/python_install.rs

@@ -191,3 +191,101 @@ fn python_install_freethreaded() {
      - cpython-3.13.0+freethreaded-[PLATFORM]
     "###);
 }
+
+#[test]
+fn python_install_default() {
+    let context: TestContext = TestContext::new_with_versions(&[]).with_filtered_python_keys();
+
+    // Install the latest version
+    uv_snapshot!(context.filters(), context.python_install(), @r###"
+    success: true
+    exit_code: 0
+    ----- stdout -----
+
+    ----- stderr -----
+    Searching for Python installations
+    Installed Python 3.13.0 in [TIME]
+     + cpython-3.13.0-[PLATFORM]
+    warning: `[TEMP_DIR]/bin` is not on your PATH. To use the installed Python executable, run `export PATH="[TEMP_DIR]/bin:$PATH"`.
+    "###);
+
+    let bin_python_minor = context
+        .temp_dir
+        .child("bin")
+        .child(format!("python3.13{}", std::env::consts::EXE_SUFFIX));
+
+    let bin_python_major = context
+        .temp_dir
+        .child("bin")
+        .child(format!("python3{}", std::env::consts::EXE_SUFFIX));
+
+    let bin_python_default = context
+        .temp_dir
+        .child("bin")
+        .child(format!("python{}", std::env::consts::EXE_SUFFIX));
+
+    // The minor-versioend executable should be installed in the bin directory
+    bin_python_minor.assert(predicate::path::exists());
+    // But the others should not
+    bin_python_major.assert(predicate::path::missing());
+    bin_python_default.assert(predicate::path::missing());
+
+    // TODO(zanieb): We should add the executables without the `--reinstall` flag
+    uv_snapshot!(context.filters(), context.python_install().arg("--default").arg("--reinstall"), @r###"
+    success: true
+    exit_code: 0
+    ----- stdout -----
+
+    ----- stderr -----
+    Searching for Python installations
+    Found: cpython-3.13.0-[PLATFORM]
+    Installed Python 3.13.0 in [TIME]
+     ~ cpython-3.13.0-[PLATFORM]
+    warning: `[TEMP_DIR]/bin` is not on your PATH. To use the installed Python executable, run `export PATH="[TEMP_DIR]/bin:$PATH"`.
+    "###);
+
+    // Now we should have an unversioned and major-versioned executable
+    bin_python_minor.assert(predicate::path::exists());
+    bin_python_major.assert(predicate::path::exists());
+    bin_python_default.assert(predicate::path::exists());
+
+    uv_snapshot!(context.filters(), context.python_uninstall().arg("3.13"), @r###"
+    success: true
+    exit_code: 0
+    ----- stdout -----
+
+    ----- stderr -----
+    Searching for Python versions matching: Python 3.13
+    Uninstalled Python 3.13.0 in [TIME]
+     - cpython-3.13.0-[PLATFORM]
+    "###);
+
+    // We should remove all the executables
+    bin_python_minor.assert(predicate::path::missing());
+    bin_python_major.assert(predicate::path::missing());
+    bin_python_default.assert(predicate::path::missing());
+
+    // Install multiple versions
+    uv_snapshot!(context.filters(), context.python_install().arg("3.12").arg("3.13").arg("--default"), @r###"
+    success: false
+    exit_code: 1
+    ----- stdout -----
+
+    ----- stderr -----
+    Searching for Python versions matching: Python 3.12
+    Searching for Python versions matching: Python 3.13
+    Installed 2 versions in [TIME]
+     + cpython-3.12.7-[PLATFORM]
+     + cpython-3.13.0-[PLATFORM]
+    warning: `[TEMP_DIR]/bin` is not on your PATH. To use the installed Python executable, run `export PATH="[TEMP_DIR]/bin:$PATH"`.
+    error: Failed to install cpython-3.12.7-[PLATFORM]
+      Caused by: Executable already exists at `bin/python3`. Use `--reinstall` to force replacement.
+    error: Failed to install cpython-3.12.7-[PLATFORM]
+      Caused by: Executable already exists at `bin/python`. Use `--reinstall` to force replacement.
+    "###);
+
+    bin_python_minor.assert(predicate::path::exists());
+    bin_python_major.assert(predicate::path::exists());
+    bin_python_default.assert(predicate::path::exists());
+    // TODO(zanieb): Assert that 3.12 is the default version
+}

docs/reference/cli.md

@@ -4427,6 +4427,14 @@ uv python install [OPTIONS] [TARGETS]...
 <p>While uv configuration can be included in a <code>pyproject.toml</code> file, it is not allowed in this context.</p>
 
 <p>May also be set with the <code>UV_CONFIG_FILE</code> environment variable.</p>
+</dd><dt><code>--default</code></dt><dd><p>Use as the default Python version.</p>
+
+<p>By default, only a <code>python{major}.{minor}</code> executable is installed, e.g., <code>python3.10</code>. When the <code>--default</code> flag is used, <code>python{major}</code>, e.g., <code>python3</code>, and <code>python</code> executables are also installed.</p>
+
+<p>Alternative Python variants will still include their tag. For example, installing 3.13+freethreaded with <code>--default</code> will include in <code>python3t</code> and <code>pythont</code>, not <code>python3</code> and <code>python</code>.</p>
+
+<p>If multiple Python versions are requested during the installation, the first request will be the default.</p>
+
 </dd><dt><code>--directory</code> <i>directory</i></dt><dd><p>Change to the given directory prior to running the command.</p>
 
 <p>Relative paths are resolved with the given directory as the base.</p>