Respect `UV_PYTHON` in `uv python install` (#11487)

Unlike https://github.com/astral-sh/uv/pull/10222, this does not respect
`UV_PYTHON` in `uv python uninstall` (continuing to require an explicit
target there) which I think is simpler and matches our `.python-version`
file behavior.

---------

Co-authored-by: Choudhry Abdullah <cabdulla@trinity.edu>
Co-authored-by: Choudhry Abdullah <choudhry347@choudhrys-air-2.trinity.local>
Co-authored-by: Aria Desires <aria.desires@gmail.com>

crates/uv-cli/src/lib.rs

@@ -4498,11 +4498,13 @@ pub struct PythonInstallArgs {
 
     /// The Python version(s) to install.
     ///
-    /// If not provided, the requested Python version(s) will be read from the `.python-versions` or
+    /// If not provided, the requested Python version(s) will be read from the `UV_PYTHON`
-    /// `.python-version` files. If neither file is present, uv will check if it has installed any
+    /// environment variable then `.python-versions` or `.python-version` files. If none of the
-    /// Python versions. If not, it will install the latest stable version of Python.
+    /// above are present, uv will check if it has installed any Python versions. If not, it will
+    /// install the latest stable version of Python.
     ///
     /// See `uv help python` to view supported request formats.
+    #[arg(env = EnvVars::UV_PYTHON)]
     pub targets: Vec<String>,
 
     /// Set the URL to use as the source for downloading Python installations.

crates/uv/tests/it/help.rs

@@ -480,11 +480,14 @@ fn help_subsubcommand() {
       [TARGETS]...
               The Python version(s) to install.
               
-              If not provided, the requested Python version(s) will be read from the `.python-versions`
+              If not provided, the requested Python version(s) will be read from the `UV_PYTHON`
-              or `.python-version` files. If neither file is present, uv will check if it has installed
+              environment variable then `.python-versions` or `.python-version` files. If none of the
-              any Python versions. If not, it will install the latest stable version of Python.
+              above are present, uv will check if it has installed any Python versions. If not, it will
+              install the latest stable version of Python.
               
               See `uv help python` to view supported request formats.
+              
+              [env: UV_PYTHON=]
 
     Options:
       -i, --install-dir <INSTALL_DIR>
@@ -772,7 +775,7 @@ fn help_flag_subsubcommand() {
     Usage: uv python install [OPTIONS] [TARGETS]...
 
     Arguments:
-      [TARGETS]...  The Python version(s) to install
+      [TARGETS]...  The Python version(s) to install [env: UV_PYTHON=]
 
     Options:
       -i, --install-dir <INSTALL_DIR>  The directory to store the Python installation in [env:

crates/uv/tests/it/python_install.rs

@@ -1,13 +1,13 @@
 use std::{path::Path, process::Command};
 
+use crate::common::{uv_snapshot, TestContext};
 use assert_fs::{
     assert::PathAssert,
     prelude::{FileTouch, PathChild, PathCreateDir},
 };
 use predicates::prelude::predicate;
 use uv_fs::Simplified;
-
+use uv_static::EnvVars;
-use crate::common::{uv_snapshot, TestContext};
 
 #[test]
 fn python_install() {
@@ -1058,9 +1058,96 @@ fn python_install_preview_broken_link() {
     });
 }
 
+#[test]
+fn python_install_default_from_env() {
+    let context: TestContext = TestContext::new_with_versions(&[])
+        .with_filtered_python_keys()
+        .with_filtered_exe_suffix()
+        .with_managed_python_dirs();
+
+    // Install the version specified by the `UV_PYTHON` environment variable by default
+    uv_snapshot!(context.filters(), context.python_install().env(EnvVars::UV_PYTHON, "3.12"), @r"
+    success: true
+    exit_code: 0
+    ----- stdout -----
+
+    ----- stderr -----
+    Installed Python 3.12.9 in [TIME]
+     + cpython-3.12.9-[PLATFORM]
+    ");
+
+    // But prefer explicit requests
+    uv_snapshot!(context.filters(), context.python_install().arg("3.11").env(EnvVars::UV_PYTHON, "3.12"), @r###"
+    success: true
+    exit_code: 0
+    ----- stdout -----
+
+    ----- stderr -----
+    Installed Python 3.11.11 in [TIME]
+     + cpython-3.11.11-[PLATFORM]
+    "###);
+
+    // We should ignore `UV_PYTHON` here and complain there is not a target
+    uv_snapshot!(context.filters(), context.python_uninstall().env(EnvVars::UV_PYTHON, "3.12"), @r###"
+    success: false
+    exit_code: 2
+    ----- stdout -----
+
+    ----- stderr -----
+    error: the following required arguments were not provided:
+      <TARGETS>...
+
+    Usage: uv python uninstall --install-dir <INSTALL_DIR> <TARGETS>...
+
+    For more information, try '--help'.
+    "###);
+
+    // We should ignore `UV_PYTHON` here and respect `--all`
+    uv_snapshot!(context.filters(), context.python_uninstall().arg("--all").env(EnvVars::UV_PYTHON, "3.11"), @r###"
+    success: true
+    exit_code: 0
+    ----- stdout -----
+
+    ----- stderr -----
+    Searching for Python installations
+    Uninstalled 2 versions in [TIME]
+     - cpython-3.11.11-[PLATFORM]
+     - cpython-3.12.9-[PLATFORM]
+    "###);
+
+    // Uninstall with no targets should error
+    uv_snapshot!(context.filters(), context.python_uninstall(), @r###"
+    success: false
+    exit_code: 2
+    ----- stdout -----
+
+    ----- stderr -----
+    error: the following required arguments were not provided:
+      <TARGETS>...
+
+    Usage: uv python uninstall --install-dir <INSTALL_DIR> <TARGETS>...
+
+    For more information, try '--help'.
+    "###);
+
+    // Uninstall with conflicting options should error
+    uv_snapshot!(context.filters(), context.python_uninstall().arg("--all").arg("3.12"), @r###"
+    success: false
+    exit_code: 2
+    ----- stdout -----
+
+    ----- stderr -----
+    error: the argument '--all' cannot be used with '<TARGETS>...'
+
+    Usage: uv python uninstall --all --install-dir <INSTALL_DIR> <TARGETS>...
+
+    For more information, try '--help'.
+    "###);
+}
+
 #[cfg(target_os = "macos")]
 #[test]
-fn python_dylib_install_name_is_patched_on_install() {
+fn python_install_patch_dylib() {
     use assert_cmd::assert::OutputAssertExt;
     use uv_python::managed::platform_key_from_env;
 

docs/reference/cli.md

@@ -4788,7 +4788,7 @@ uv python install [OPTIONS] [TARGETS]...
 
 <dl class="cli-reference"><dt><code>TARGETS</code></dt><dd><p>The Python version(s) to install.</p>
 
-<p>If not provided, the requested Python version(s) will be read from the <code>.python-versions</code> or <code>.python-version</code> files. If neither file is present, uv will check if it has installed any Python versions. If not, it will install the latest stable version of Python.</p>
+<p>If not provided, the requested Python version(s) will be read from the <code>UV_PYTHON</code> environment variable then <code>.python-versions</code> or <code>.python-version</code> files. If none of the above are present, uv will check if it has installed any Python versions. If not, it will install the latest stable version of Python.</p>
 
 <p>See <a href="#uv-python">uv python</a> to view supported request formats.</p>