Add --root flag for uv pip install

Author: fdfz

crates/uv-cli/src/lib.rs

@@ -1946,7 +1946,7 @@ pub struct PipSyncArgs {
     /// environment and only searches for a Python interpreter to use for package resolution.
     /// If a suitable Python interpreter cannot be found, uv will install one.
     /// To disable this, add `--no-python-downloads`.
-    #[arg(short = 't', long, conflicts_with = "prefix", value_hint = ValueHint::DirPath)]
+    #[arg(short = 't', long, conflicts_with_all = ["prefix", "root"], value_hint = ValueHint::DirPath)]
     pub target: Option<PathBuf>,
 
     /// Install packages into `lib`, `bin`, and other top-level folders under the specified
@@ -1961,9 +1961,18 @@ pub struct PipSyncArgs {
     /// environment and only searches for a Python interpreter to use for package resolution.
     /// If a suitable Python interpreter cannot be found, uv will install one.
     /// To disable this, add `--no-python-downloads`.
-    #[arg(long, conflicts_with = "target", value_hint = ValueHint::DirPath)]
+    #[arg(long, conflicts_with_all = ["target", "root"], value_hint = ValueHint::DirPath)]
     pub prefix: Option<PathBuf>,
 
+    /// Install everything relative to this alternate root directory.
+    ///
+    /// Unlike other install operations, this command does not require discovery of an existing Python
+    /// environment and only searches for a Python interpreter to use for package resolution.
+    /// If a suitable Python interpreter cannot be found, uv will install one.
+    /// To disable this, add `--no-python-downloads`.
+    #[arg(long, conflicts_with_all = ["target", "prefix"], value_hint = ValueHint::DirPath)]
+    pub root: Option<PathBuf>,
+
     /// Don't build source distributions.
     ///
     /// When enabled, resolving will not run arbitrary Python code. The cached wheels of
@@ -2323,7 +2332,7 @@ pub struct PipInstallArgs {
     /// environment and only searches for a Python interpreter to use for package resolution.
     /// If a suitable Python interpreter cannot be found, uv will install one.
     /// To disable this, add `--no-python-downloads`.
-    #[arg(short = 't', long, conflicts_with = "prefix", value_hint = ValueHint::DirPath)]
+    #[arg(short = 't', long, conflicts_with_all = ["prefix", "root"], value_hint = ValueHint::DirPath)]
     pub target: Option<PathBuf>,
 
     /// Install packages into `lib`, `bin`, and other top-level folders under the specified
@@ -2338,9 +2347,18 @@ pub struct PipInstallArgs {
     /// environment and only searches for a Python interpreter to use for package resolution.
     /// If a suitable Python interpreter cannot be found, uv will install one.
     /// To disable this, add `--no-python-downloads`.
-    #[arg(long, conflicts_with = "target", value_hint = ValueHint::DirPath)]
+    #[arg(long, conflicts_with_all = ["target", "root"], value_hint = ValueHint::DirPath)]
     pub prefix: Option<PathBuf>,
 
+    /// Install everything relative to this alternate root directory.
+    ///
+    /// Unlike other install operations, this command does not require discovery of an existing Python
+    /// environment and only searches for a Python interpreter to use for package resolution.
+    /// If a suitable Python interpreter cannot be found, uv will install one.
+    /// To disable this, add `--no-python-downloads`.
+    #[arg(long, conflicts_with_all = ["target", "prefix"], value_hint = ValueHint::DirPath)]
+    pub root: Option<PathBuf>,
+
     /// Don't build source distributions.
     ///
     /// When enabled, resolving will not run arbitrary Python code. The cached wheels of
@@ -2539,13 +2557,17 @@ pub struct PipUninstallArgs {
     pub no_break_system_packages: bool,
 
     /// Uninstall packages from the specified `--target` directory.
-    #[arg(short = 't', long, conflicts_with = "prefix", value_hint = ValueHint::DirPath)]
+    #[arg(short = 't', long, conflicts_with_all = ["prefix", "root"], value_hint = ValueHint::DirPath)]
     pub target: Option<PathBuf>,
 
     /// Uninstall packages from the specified `--prefix` directory.
-    #[arg(long, conflicts_with = "target", value_hint = ValueHint::DirPath)]
+    #[arg(long, conflicts_with_all = ["target", "root"], value_hint = ValueHint::DirPath)]
     pub prefix: Option<PathBuf>,
 
+    /// Uninstall packages from the specified `--root` directory.
+    #[arg(long, conflicts_with_all = ["target", "prefix"], value_hint = ValueHint::DirPath)]
+    pub root: Option<PathBuf>,
+
     /// Perform a dry run, i.e., don't actually uninstall anything but print the resulting plan.
     #[arg(long)]
     pub dry_run: bool,
@@ -2610,13 +2632,17 @@ pub struct PipFreezeArgs {
     pub no_system: bool,
 
     /// List packages from the specified `--target` directory.
-    #[arg(short = 't', long, conflicts_with_all = ["prefix", "paths"], value_hint = ValueHint::DirPath)]
+    #[arg(short = 't', long, conflicts_with_all = ["prefix", "root", "paths"], value_hint = ValueHint::DirPath)]
     pub target: Option<PathBuf>,
 
     /// List packages from the specified `--prefix` directory.
-    #[arg(long, conflicts_with_all = ["target", "paths"], value_hint = ValueHint::DirPath)]
+    #[arg(long, conflicts_with_all = ["target", "root", "paths"], value_hint = ValueHint::DirPath)]
     pub prefix: Option<PathBuf>,
 
+    /// List packages from the specified `--root` directory.
+    #[arg(long, conflicts_with_all = ["target", "prefix"], value_hint = ValueHint::DirPath)]
+    pub root: Option<PathBuf>,
+
     #[command(flatten)]
     pub compat_args: compat::PipGlobalCompatArgs,
 }
@@ -2694,13 +2720,17 @@ pub struct PipListArgs {
     pub no_system: bool,
 
     /// List packages from the specified `--target` directory.
-    #[arg(short = 't', long, conflicts_with = "prefix", value_hint = ValueHint::DirPath)]
+    #[arg(short = 't', long, conflicts_with_all = ["prefix", "root"], value_hint = ValueHint::DirPath)]
     pub target: Option<PathBuf>,
 
     /// List packages from the specified `--prefix` directory.
-    #[arg(long, conflicts_with = "target", value_hint = ValueHint::DirPath)]
+    #[arg(long, conflicts_with_all = ["target", "root"], value_hint = ValueHint::DirPath)]
     pub prefix: Option<PathBuf>,
 
+    /// List packages from the specified `--root` directory.
+    #[arg(long, conflicts_with_all = ["target", "prefix"], value_hint = ValueHint::DirPath)]
+    pub root: Option<PathBuf>,
+
     #[command(flatten)]
     pub compat_args: compat::PipListCompatArgs,
 }
@@ -2820,13 +2850,17 @@ pub struct PipShowArgs {
     pub no_system: bool,
 
     /// Show a package from the specified `--target` directory.
-    #[arg(short = 't', long, conflicts_with = "prefix", value_hint = ValueHint::DirPath)]
+    #[arg(short = 't', long, conflicts_with_all = ["prefix", "root"], value_hint = ValueHint::DirPath)]
     pub target: Option<PathBuf>,
 
     /// Show a package from the specified `--prefix` directory.
-    #[arg(long, conflicts_with = "target", value_hint = ValueHint::DirPath)]
+    #[arg(long, conflicts_with_all = ["target", "root"], value_hint = ValueHint::DirPath)]
     pub prefix: Option<PathBuf>,
 
+    /// Show a package from the specified `--root` directory.
+    #[arg(long, conflicts_with_all = ["target", "prefix"], value_hint = ValueHint::DirPath)]
+    pub root: Option<PathBuf>,
+
     #[command(flatten)]
     pub compat_args: compat::PipGlobalCompatArgs,
 }

crates/uv-python/src/environment.rs

@@ -13,6 +13,7 @@ use uv_preview::Preview;
 
 use crate::discovery::find_python_installation;
 use crate::installation::PythonInstallation;
+use crate::root::Root;
 use crate::virtualenv::{PyVenvConfiguration, virtualenv_python_executable};
 use crate::{
     EnvironmentPreference, Error, Interpreter, Prefix, PythonNotFound, PythonPreference,
@@ -257,6 +258,15 @@ impl PythonEnvironment {
         })))
     }
 
+    /// Create a [`PythonEnvironment`] from an existing [`Interpreter`] and `--root` directory.
+    pub fn with_root(self, root: Root) -> std::io::Result<Self> {
+        let inner = Arc::unwrap_or_clone(self.0);
+        Ok(Self(Arc::new(PythonEnvironmentShared {
+            interpreter: inner.interpreter.with_root(root)?,
+            ..inner
+        })))
+    }
+
     /// Returns the root (i.e., `prefix`) of the Python interpreter.
     pub fn root(&self) -> &Path {
         &self.0.root

crates/uv-python/src/interpreter.rs

@@ -36,6 +36,7 @@ use crate::{
     VersionRequest, VirtualEnvironment,
 };
 
+use crate::root::Root;
 #[cfg(windows)]
 use windows::Win32::Foundation::{APPMODEL_ERROR_NO_PACKAGE, ERROR_CANT_ACCESS_FILE, WIN32_ERROR};
 
@@ -60,6 +61,7 @@ pub struct Interpreter {
     tags: OnceLock<Tags>,
     target: Option<Target>,
     prefix: Option<Prefix>,
+    root: Option<Root>,
     pointer_size: PointerSize,
     gil_disabled: bool,
     real_executable: PathBuf,
@@ -98,6 +100,7 @@ impl Interpreter {
             tags: OnceLock::new(),
             target: None,
             prefix: None,
+            root: None,
             real_executable: executable.as_ref().to_path_buf(),
         })
     }
@@ -135,6 +138,15 @@ impl Interpreter {
         })
     }
 
+    /// Return a new [`Interpreter`] to install into the given `--root` directory.
+    pub fn with_root(self, root: Root) -> io::Result<Self> {
+        root.init(&self)?;
+        Ok(Self {
+            root: Some(root),
+            ..self
+        })
+    }
+
     /// Return the base Python executable; that is, the Python executable that should be
     /// considered the "base" for the virtual environment. This is typically the Python executable
     /// from the [`Interpreter`]; however, if the interpreter is a virtual environment itself, then
@@ -280,6 +292,11 @@ impl Interpreter {
         self.prefix.is_some()
     }
 
+    /// Returns `true` if the environment is a `--root` environment.
+    pub fn is_root(&self) -> bool {
+        self.root.is_some()
+    }
+
     /// Returns `true` if this interpreter is managed by uv.
     ///
     /// Returns `false` if we cannot determine the path of the uv managed Python interpreters.
@@ -337,7 +354,7 @@ impl Interpreter {
         }
 
         // If we're installing into a target or prefix directory, it's never externally managed.
-        if self.is_target() || self.is_prefix() {
+        if self.is_target() || self.is_prefix() || self.is_root() {
             return None;
         }
 
@@ -555,6 +572,11 @@ impl Interpreter {
         self.prefix.as_ref()
     }
 
+    /// Return the `--root` directory for this interpreter, if any.
+    pub fn root(&self) -> Option<&Root> {
+        self.root.as_ref()
+    }
+
     /// Returns `true` if an [`Interpreter`] may be a `python-build-standalone` interpreter.
     ///
     /// This method may return false positives, but it should not return false negatives. In other
@@ -586,6 +608,8 @@ impl Interpreter {
                 target.scheme()
             } else if let Some(prefix) = self.prefix.as_ref() {
                 prefix.scheme(&self.virtualenv)
+            } else if let Some(root) = self.root.as_ref() {
+                root.scheme(self)
             } else {
                 Scheme {
                     purelib: self.purelib().to_path_buf(),
@@ -625,7 +649,9 @@ impl Interpreter {
             .prefix()
             .map(|prefix| prefix.site_packages(self.virtualenv()));
 
-        let interpreter = if target.is_none() && prefix.is_none() {
+        let root = self.root().map(|root| root.site_packages(self));
+
+        let interpreter = if target.is_none() && prefix.is_none() && root.is_none() {
             let purelib = self.purelib();
             let platlib = self.platlib();
             Some(std::iter::once(purelib).chain(
@@ -644,6 +670,7 @@ impl Interpreter {
             .flatten()
             .map(Cow::Borrowed)
             .chain(prefix.into_iter().flatten().map(Cow::Owned))
+            .chain(root.into_iter().flatten().map(Cow::Owned))
             .chain(interpreter.into_iter().flatten().map(Cow::Borrowed))
     }
 
@@ -685,13 +712,21 @@ impl Interpreter {
             )
             .await
         } else if let Some(prefix) = self.prefix() {
-            // Likewise, if we're installing into a `--prefix`, use a prefix-specific lockfile.
+            // If we're installing into a `--prefix`, use a prefix-specific lockfile.
             LockedFile::acquire(
                 prefix.root().join(".lock"),
                 LockedFileMode::Exclusive,
                 prefix.root().user_display(),
             )
             .await
+        } else if let Some(root) = self.root() {
+            // If we're installing into a `--root`, use a root-specific lockfile.
+            LockedFile::acquire(
+                root.root().join(".lock"),
+                LockedFileMode::Exclusive,
+                root.root().user_display(),
+            )
+            .await
         } else if self.is_virtualenv() {
             // If the environment a virtualenv, use a virtualenv-specific lockfile.
             LockedFile::acquire(

crates/uv-python/src/lib.rs

@@ -22,6 +22,7 @@ pub use crate::interpreter::{
 pub use crate::pointer_size::PointerSize;
 pub use crate::prefix::Prefix;
 pub use crate::python_version::{BuildVersionError, PythonVersion};
+pub use crate::root::Root;
 pub use crate::target::Target;
 pub use crate::version_files::{
     DiscoveryOptions as VersionFileDiscoveryOptions, FilePreference as VersionFilePreference,
@@ -42,6 +43,7 @@ mod microsoft_store;
 mod pointer_size;
 mod prefix;
 mod python_version;
+mod root;
 mod sysconfig;
 mod target;
 mod version_files;