🔧 add --install-dir arg to uv python commands

Author: danielgafni

crates/uv-cli/src/lib.rs

@@ -3559,6 +3559,11 @@ pub struct PythonListArgs {
 #[derive(Args)]
 #[allow(clippy::struct_excessive_bools)]
 pub struct PythonInstallArgs {
+    /// The directory where Python will be installed.
+    ///
+    #[arg(long, short, env = "UV_PYTHON_INSTALL_DIR")]
+    pub install_dir: Option<PathBuf>,
+
     /// The Python version(s) to install.
     ///
     /// If not provided, the requested Python version(s) will be read from the
@@ -3580,6 +3585,11 @@ pub struct PythonInstallArgs {
 #[derive(Args)]
 #[allow(clippy::struct_excessive_bools)]
 pub struct PythonUninstallArgs {
+    /// The directory where Python is installed.
+    ///
+    #[arg(long, short, env = "UV_PYTHON_INSTALL_DIR")]
+    pub install_dir: Option<PathBuf>,
+
     /// The Python version(s) to uninstall.
     ///
     /// See `uv help python` to view supported request formats.

crates/uv-python/src/managed.rs

@@ -65,7 +65,7 @@ pub struct ManagedPythonInstallations {
 
 impl ManagedPythonInstallations {
     /// A directory for Python installations at `root`.
-    fn from_path(root: impl Into<PathBuf>) -> Self {
+    pub fn from_path(root: impl Into<PathBuf>) -> Self {
         Self { root: root.into() }
     }
 

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

@@ -21,6 +21,7 @@ use crate::printer::Printer;
 /// Download and install Python versions.
 pub(crate) async fn install(
     project_dir: &Path,
+    install_dir: Option<&Path>,
     targets: Vec<String>,
     reinstall: bool,
     python_downloads: PythonDownloads,
@@ -31,7 +32,12 @@ pub(crate) async fn install(
 ) -> Result<ExitStatus> {
     let start = std::time::Instant::now();
 
-    let installations = ManagedPythonInstallations::from_settings()?.init()?;
+    let installations = if let Some(install_dir) = install_dir {
+        ManagedPythonInstallations::from_path(install_dir)
+    } else {
+        ManagedPythonInstallations::from_settings()?
+    }
+    .init()?;
     let installations_dir = installations.root();
     let cache_dir = installations.cache();
     let _lock = installations.lock().await?;

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

@@ -14,15 +14,22 @@ use uv_python::PythonRequest;
 use crate::commands::python::{ChangeEvent, ChangeEventKind};
 use crate::commands::{elapsed, ExitStatus};
 use crate::printer::Printer;
+use std::path::Path;
 
 /// Uninstall managed Python versions.
 pub(crate) async fn uninstall(
+    install_dir: Option<&Path>,
     targets: Vec<String>,
     all: bool,
 
     printer: Printer,
 ) -> Result<ExitStatus> {
-    let installations = ManagedPythonInstallations::from_settings()?.init()?;
+    let installations = if let Some(install_dir) = install_dir {
+        ManagedPythonInstallations::from_path(install_dir)
+    } else {
+        ManagedPythonInstallations::from_settings()?.init()?
+    };
+
     let _lock = installations.lock().await?;
 
     // Perform the uninstallation.

crates/uv/src/lib.rs

@@ -1016,6 +1016,7 @@ async fn run(cli: Cli) -> Result<ExitStatus> {
 
             commands::python_install(
                 &project_dir,
+                args.install_dir.as_deref(),
                 args.targets,
                 args.reinstall,
                 globals.python_downloads,
@@ -1033,7 +1034,8 @@ async fn run(cli: Cli) -> Result<ExitStatus> {
             let args = settings::PythonUninstallSettings::resolve(args, filesystem);
             show_settings!(args);
 
-            commands::python_uninstall(args.targets, args.all, printer).await
+            commands::python_uninstall(args.install_dir.as_deref(), args.targets, args.all, printer)
+                .await
         }
         Commands::Python(PythonNamespace {
             command: PythonCommand::Find(args),

crates/uv/src/settings.rs

@@ -585,6 +585,7 @@ impl PythonListSettings {
 #[allow(clippy::struct_excessive_bools)]
 #[derive(Debug, Clone)]
 pub(crate) struct PythonInstallSettings {
+    pub(crate) install_dir: Option<PathBuf>,
     pub(crate) targets: Vec<String>,
     pub(crate) reinstall: bool,
 }
@@ -593,16 +594,25 @@ 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 {
+            install_dir,
+            targets,
+            reinstall,
+        } = args;
 
-        Self { targets, reinstall }
+        Self {
+            install_dir,
+            targets,
+            reinstall,
+        }
     }
 }
 
 /// The resolved settings to use for a `python uninstall` invocation.
 #[allow(clippy::struct_excessive_bools)]
 #[derive(Debug, Clone)]
 pub(crate) struct PythonUninstallSettings {
+    pub(crate) install_dir: Option<PathBuf>,
     pub(crate) targets: Vec<String>,
     pub(crate) all: bool,
 }
@@ -614,9 +624,17 @@ impl PythonUninstallSettings {
         args: PythonUninstallArgs,
         _filesystem: Option<FilesystemOptions>,
     ) -> Self {
-        let PythonUninstallArgs { targets, all } = args;
+        let PythonUninstallArgs {
+            install_dir,
+            targets,
+            all,
+        } = args;
 
-        Self { targets, all }
+        Self {
+            install_dir,
+            targets,
+            all,
+        }
     }
 }
 

docs/reference/cli.md

@@ -4016,6 +4016,9 @@ uv python install [OPTIONS] [TARGETS]...
 
 </dd><dt><code>--help</code>, <code>-h</code></dt><dd><p>Display the concise help for this command</p>
 
+</dd><dt><code>--install-dir</code>, <code>-i</code> <i>install-dir</i></dt><dd><p>The directory where Python will be installed</p>
+
+<p>May also be set with the <code>UV_PYTHON_INSTALL_DIR</code> environment variable.</p>
 </dd><dt><code>--native-tls</code></dt><dd><p>Whether to load TLS certificates from the platform&#8217;s native certificate store.</p>
 
 <p>By default, uv loads certificates from the bundled <code>webpki-roots</code> crate. The <code>webpki-roots</code> are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).</p>
@@ -4493,6 +4496,9 @@ uv python uninstall [OPTIONS] <TARGETS>...
 
 </dd><dt><code>--help</code>, <code>-h</code></dt><dd><p>Display the concise help for this command</p>
 
+</dd><dt><code>--install-dir</code>, <code>-i</code> <i>install-dir</i></dt><dd><p>The directory where Python is installed</p>
+
+<p>May also be set with the <code>UV_PYTHON_INSTALL_DIR</code> environment variable.</p>
 </dd><dt><code>--native-tls</code></dt><dd><p>Whether to load TLS certificates from the platform&#8217;s native certificate store.</p>
 
 <p>By default, uv loads certificates from the bundled <code>webpki-roots</code> crate. The <code>webpki-roots</code> are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).</p>