Implement --user flag and user scheme support for uv pip

crates/uv-interpreter/src/cfg.rs

@@ -10,20 +10,23 @@ pub struct PyVenvConfiguration {
     pub(crate) virtualenv: bool,
     /// The version of the `uv` package used to create the virtual environment, if any.
     pub(crate) uv: bool,
+    /// If the virtual environment has access to the system packages, per PEP 405.
+    pub(crate) include_system_site_packages: bool,
 }
 
 impl PyVenvConfiguration {
     /// Parse a `pyvenv.cfg` file into a [`PyVenvConfiguration`].
     pub fn parse(cfg: impl AsRef<Path>) -> Result<Self, Error> {
         let mut virtualenv = false;
         let mut uv = false;
+        let mut include_system_site_packages = false;
 
         // Per https://snarky.ca/how-virtual-environments-work/, the `pyvenv.cfg` file is not a
         // valid INI file, and is instead expected to be parsed by partitioning each line on the
         // first equals sign.
         let content = fs::read_to_string(&cfg)?;
         for line in content.lines() {
-            let Some((key, _value)) = line.split_once('=') else {
+            let Some((key, value)) = line.split_once('=') else {
                 continue;
             };
             match key.trim() {
@@ -33,11 +36,18 @@ impl PyVenvConfiguration {
                 "uv" => {
                     uv = true;
                 }
+                "include-system-site-packages" => {
+                    include_system_site_packages = value.trim() == "true";
+                }
                 _ => {}
             }
         }
 
-        Ok(Self { virtualenv, uv })
+        Ok(Self {
+            virtualenv,
+            uv,
+            include_system_site_packages,
+        })
     }
 
     /// Returns true if the virtual environment was created with the `virtualenv` package.
@@ -49,6 +59,11 @@ impl PyVenvConfiguration {
     pub fn is_uv(&self) -> bool {
         self.uv
     }
+
+    /// Return true if the virtual environment has access to system site packages.
+    pub fn include_system_site_packages(&self) -> bool {
+        self.include_system_site_packages
+    }
 }
 
 #[derive(Debug, Error)]

crates/uv-interpreter/src/get_interpreter_info.py

@@ -6,7 +6,6 @@
     1: General failure
     3: Python version 3 or newer is required
 """
-
 import json
 import os
 import platform
@@ -25,7 +24,6 @@ def format_full_version(info):
 if sys.version_info[0] < 3:
     sys.exit(3)
 
-
 if hasattr(sys, "implementation"):
     implementation_version = format_full_version(sys.implementation.version)
     implementation_name = sys.implementation.name
@@ -217,7 +215,7 @@ def expand_path(path: str) -> str:
         }
 
 
-def get_scheme():
+def get_scheme(user: bool = False):
     """Return the Scheme for the current interpreter.
 
     The paths returned should be absolute.
@@ -226,7 +224,7 @@ def get_scheme():
         https://github.com/pypa/pip/blob/ae5fff36b0aad6e5e0037884927eaa29163c0611/src/pip/_internal/locations/__init__.py#L230
     """
 
-    def get_sysconfig_scheme():
+    def get_sysconfig_scheme(user: bool = False):
         """Get the "scheme" corresponding to the input parameters.
 
         Uses the `sysconfig` module to get the scheme.
@@ -275,6 +273,20 @@ def _should_use_osx_framework_prefix() -> bool:
                 and is_osx_framework()
             )
 
+        def _infer_user() -> str:
+            """Try to find a user scheme for the current platform."""
+            if _PREFERRED_SCHEME_API:
+                return _PREFERRED_SCHEME_API("user")
+            if is_osx_framework() and not running_under_virtualenv():
+                suffixed = "osx_framework_user"
+            else:
+                suffixed = f"{os.name}_user"
+            if suffixed in _AVAILABLE_SCHEMES:
+                return suffixed
+            # Fall back to posix_user if user scheme is unavailable.
+            # `pip` would raise exeception when "posix_user" not in _AVAILABLE_SCHEMES
+            return "posix_user"
+
         def _infer_prefix() -> str:
             """Try to find a prefix scheme for the current platform.
 
@@ -301,11 +313,15 @@ def _infer_prefix() -> str:
             suffixed = f"{os.name}_prefix"
             if suffixed in _AVAILABLE_SCHEMES:
                 return suffixed
-            if os.name in _AVAILABLE_SCHEMES:  # On Windows, prefx is just called "nt".
+            if os.name in _AVAILABLE_SCHEMES:  # On Windows, prefix is just called "nt".
                 return os.name
             return "posix_prefix"
 
-        scheme_name = _infer_prefix()
+        if user:
+            scheme_name = _infer_user()
+        else:
+            scheme_name = _infer_prefix()
+
         paths = sysconfig.get_paths(scheme=scheme_name)
 
         # Logic here is very arbitrary, we're doing it for compatibility, don't ask.
@@ -322,7 +338,7 @@ def _infer_prefix() -> str:
             "data": paths["data"],
         }
 
-    def get_distutils_scheme():
+    def get_distutils_scheme(user: bool = False):
         """Get the "scheme" corresponding to the input parameters.
 
         Uses the deprecated `distutils` module to get the scheme.
@@ -361,6 +377,7 @@ def get_distutils_scheme():
             warnings.simplefilter("ignore")
             i = d.get_command_obj("install", create=True)
 
+        i.user = user
         i.finalize_options()
 
         scheme = {}
@@ -376,8 +393,12 @@ def get_distutils_scheme():
             scheme.update({"purelib": i.install_lib, "platlib": i.install_lib})
 
         if running_under_virtualenv():
+            if user:
+                prefix = i.install_userbase
+            else:
+                prefix = i.prefix
             scheme["headers"] = os.path.join(
-                i.prefix,
+                prefix,
                 "include",
                 "site",
                 f"python{get_major_minor_version()}",
@@ -401,10 +422,13 @@ def get_distutils_scheme():
     )
 
     if use_sysconfig:
-        return get_sysconfig_scheme()
+        return get_sysconfig_scheme(user)
     else:
-        return get_distutils_scheme()
+        return get_distutils_scheme(user)
+
 
+# Read the environment variable `_UV_USE_USER_SCHEME` to determine if we should use the user scheme.
+user = os.getenv("_UV_USE_USER_SCHEME", "False").upper() in {"TRUE", "1"}
 
 markers = {
     "implementation_name": implementation_name,
@@ -427,7 +451,7 @@ def get_distutils_scheme():
     "base_executable": getattr(sys, "_base_executable", None),
     "sys_executable": sys.executable,
     "stdlib": sysconfig.get_path("stdlib"),
-    "scheme": get_scheme(),
+    "scheme": get_scheme(user),
     "virtualenv": get_virtualenv(),
 }
 print(json.dumps(interpreter_info))

crates/uv-interpreter/src/interpreter.rs

@@ -1,6 +1,6 @@
 use std::io::Write;
 use std::path::{Path, PathBuf};
-use std::process::Command;
+use std::process::{Command, Output};
 
 use configparser::ini::Ini;
 use fs_err as fs;
@@ -107,6 +107,15 @@ impl Interpreter {
         }
     }
 
+    /// Return a new [`Interpreter`] with user scheme.
+    pub fn with_user_scheme(self) -> Result<Self, Error> {
+        let info = InterpreterInfo::query_user_scheme_info(self.sys_executable())?;
+        Ok(Self {
+            scheme: info.scheme,
+            ..self
+        })
+    }
+
     /// Returns the path to the Python virtual environment.
     #[inline]
     pub fn platform(&self) -> &Platform {
@@ -347,68 +356,8 @@ impl InterpreterInfo {
     /// Return the resolved [`InterpreterInfo`] for the given Python executable.
     pub(crate) fn query(interpreter: &Path) -> Result<Self, Error> {
         let script = include_str!("get_interpreter_info.py");
-        let output = if cfg!(windows)
-            && interpreter
-                .extension()
-                .is_some_and(|extension| extension == "bat")
-        {
-            // Multiline arguments aren't well-supported in batch files and `pyenv-win`, for example, trips over it.
-            // We work around this batch limitation by passing the script via stdin instead.
-            // This is somewhat more expensive because we have to spawn a new thread to write the
-            // stdin to avoid deadlocks in case the child process waits for the parent to read stdout.
-            // The performance overhead is the reason why we only applies this to batch files.
-            // https://github.com/pyenv-win/pyenv-win/issues/589
-            let mut child = Command::new(interpreter)
-                .arg("-")
-                .stdin(std::process::Stdio::piped())
-                .stdout(std::process::Stdio::piped())
-                .spawn()
-                .map_err(|err| Error::PythonSubcommandLaunch {
-                    interpreter: interpreter.to_path_buf(),
-                    err,
-                })?;
-
-            let mut stdin = child.stdin.take().unwrap();
 
-            // From the Rust documentation:
-            // If the child process fills its stdout buffer, it may end up
-            // waiting until the parent reads the stdout, and not be able to
-            // read stdin in the meantime, causing a deadlock.
-            // Writing from another thread ensures that stdout is being read
-            // at the same time, avoiding the problem.
-            std::thread::spawn(move || {
-                stdin
-                    .write_all(script.as_bytes())
-                    .expect("failed to write to stdin");
-            });
-
-            child.wait_with_output()
-        } else {
-            Command::new(interpreter).arg("-c").arg(script).output()
-        }
-        .map_err(|err| Error::PythonSubcommandLaunch {
-            interpreter: interpreter.to_path_buf(),
-            err,
-        })?;
-
-        // stderr isn't technically a criterion for success, but i don't know of any cases where there
-        // should be stderr output and if there is, we want to know
-        if !output.status.success() || !output.stderr.is_empty() {
-            if output.status.code() == Some(3) {
-                return Err(Error::Python2OrOlder);
-            }
-
-            return Err(Error::PythonSubcommandOutput {
-                message: format!(
-                    "Querying Python at `{}` failed with status {}",
-                    interpreter.display(),
-                    output.status,
-                ),
-                exit_code: output.status,
-                stdout: String::from_utf8_lossy(&output.stdout).trim().to_string(),
-                stderr: String::from_utf8_lossy(&output.stderr).trim().to_string(),
-            });
-        }
+        let output = Self::execute_script(interpreter, script, None)?;
 
         let data: Self = serde_json::from_slice(&output.stdout).map_err(|err| {
             Error::PythonSubcommandOutput {
@@ -498,6 +447,106 @@ impl InterpreterInfo {
 
         Ok(info)
     }
+
+    /// Return the [`InterpreterInfo`] for the given Python interpreter with user scheme.
+    pub(crate) fn query_user_scheme_info(interpreter: &Path) -> Result<Self, Error> {
+        let script = include_str!("get_interpreter_info.py");
+        let envs = vec![("_UV_USE_USER_SCHEME", "1")];
+        let output = Self::execute_script(interpreter, script, Some(envs))?;
+
+        let data: Self = serde_json::from_slice(&output.stdout).map_err(|err| {
+            Error::PythonSubcommandOutput {
+                message: format!(
+                    "Querying Python at `{}` did not return the expected data: {err}",
+                    interpreter.display(),
+                ),
+                exit_code: output.status,
+                stdout: String::from_utf8_lossy(&output.stdout).trim().to_string(),
+                stderr: String::from_utf8_lossy(&output.stderr).trim().to_string(),
+            }
+        })?;
+
+        Ok(data)
+    }
+
+    /// Execute the given Python script using an interpreter.
+    fn execute_script(
+        interpreter: &Path,
+        script: &str,
+        envs: Option<Vec<(&str, &str)>>,
+    ) -> Result<Output, Error> {
+        let mut command = Command::new(interpreter);
+
+        if let Some(env_variables) = envs {
+            command.envs(env_variables);
+        }
+
+        let script_clone = script.to_string();
+        let output = if cfg!(windows)
+            && interpreter
+                .extension()
+                .is_some_and(|extension| extension == "bat")
+        {
+            // Multiline arguments aren't well-supported in batch files and `pyenv-win`, for example, trips over it.
+            // We work around this batch limitation by passing the script via stdin instead.
+            // This is somewhat more expensive because we have to spawn a new thread to write the
+            // stdin to avoid deadlocks in case the child process waits for the parent to read stdout.
+            // The performance overhead is the reason why we only applies this to batch files.
+            // https://github.com/pyenv-win/pyenv-win/issues/589
+            let mut child = command
+                .arg("-")
+                .stdin(std::process::Stdio::piped())
+                .stdout(std::process::Stdio::piped())
+                .spawn()
+                .map_err(|err| Error::PythonSubcommandLaunch {
+                    interpreter: interpreter.to_path_buf(),
+                    err,
+                })?;
+
+            let mut stdin = child.stdin.take().unwrap();
+
+            // From the Rust documentation:
+            // If the child process fills its stdout buffer, it may end up
+            // waiting until the parent reads the stdout, and not be able to
+            // read stdin in the meantime, causing a deadlock.
+            // Writing from another thread ensures that stdout is being read
+            // at the same time, avoiding the problem.
+            std::thread::spawn(move || {
+                stdin
+                    .write_all(script_clone.as_bytes())
+                    .expect("failed to write to stdin");
+            });
+
+            child.wait_with_output()
+        } else {
+            command.arg("-c").arg(script_clone).output()
+        }
+        .map_err(|err| Error::PythonSubcommandLaunch {
+            interpreter: interpreter.to_path_buf(),
+            err,
+        })?;
+
+        // stderr isn't technically a criterion for success, but i don't know of any cases where there
+        // should be stderr output and if there is, we want to know
+        if !output.status.success() || !output.stderr.is_empty() {
+            if output.status.code() == Some(3) {
+                return Err(Error::Python2OrOlder);
+            }
+
+            return Err(Error::PythonSubcommandOutput {
+                message: format!(
+                    "Querying Python at `{}` failed with status {}",
+                    interpreter.display(),
+                    output.status,
+                ),
+                exit_code: output.status,
+                stdout: String::from_utf8_lossy(&output.stdout).trim().to_string(),
+                stderr: String::from_utf8_lossy(&output.stderr).trim().to_string(),
+            });
+        }
+
+        Ok(output)
+    }
 }
 
 #[cfg(unix)]