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

[imfing]

Summary

Hi team, excited for your awesome work of uv.

This PR attempts to implement --user flag for uv pip subcommands: install, freeze, list and show.

Closes #2077

also #1584

Per PEP 370 – Per user site-packages directory, pip supports user scheme package installation which would be useful for multi-user environment or CI use cases without the need of virtual environment or breaking system Python packages.

Example usage:

export PYTHONUSERBASE=~/.local/myappenv
uv pip install --user SomePackage
# SomePackage is available under ~/.local/myappenv

Implementation details

The implementation aims to bring minimal changes to the existing functionalities of uv pip, as well as supporting --user for pip compatibility.

Here are some breakdowns of the implementation:

• add _infer_user() to crates/uv-interpreter/src/get_interpreter_info.py which returns the user scheme if specified
• add PythonEnvironment::from_user_scheme() which queries the interpreter info with user scheme, thus the platlib, purelib, scripts, data and include should point to the user site
• use the user scheme Python environment for uv pip subcommands when the --user flag is present, making the subcommands use only the user site for package search and installation.

Right now the implementation doesn't include the global packages mentioned in User Installs since we only consider site packages from the scheme.purelib. I'm thinking about adding that later for better compatibility with pip install.

I am new to uv, looking forward to the team's feedback and suggestions :)

Test Plan

May need some advice and guidance on what's the best practice on testing this.

[charliermarsh]

This looks like a nice PR! The main blocker is that I need to decide if we want to support --user. I think it leads to some limitations in pip but I just haven't had time to investigate it. For example, it was suggested elsewhere that --user and --editable are no longer supported in pip -- is that true?

[charliermarsh]

Does this intentionally not cache?

[imfing]

I've noticed that query_cached uses the executable's last modified time as a cache key. In the case of user scheme, the interpreter may remain the same, e.g. the system Python interpreter, but the InterpreterInfo.scheme changes to the user site, e.g. ~/.local.

I will take a further look into using uv_cache to cache the script execution here.

[charliermarsh]

Again, just want to say: this is very nice work! In fact I'm more inclined to support this now that we have a nice PR for it. But I do want to understand the implications a little more first.

[charliermarsh]

Can we use is_some_and or unwrap_or here instead of unwrapping?

[imfing]

Thank you for the comments 😄

For example, it was suggested elsewhere that --user and --editable are no longer supported in pip -- is that true?

It seems there might be some confusion stemming from an issue discussed here: #2077 (comment)

One of the problems is that you cannot run --user and --editable any more with pip.

As far as i know, both --user and --editable are still supported in the latest pip install options.
There appears to be no intention from the pip developers to deprecate these flags. I couldn't find any discussion about this either.

I don't have the full context so the complexity might arise specifically in the context of using Airflow. It would be great if the author of that comment could provide some further details.

For reference, I conducted a quick local test combining the --user and --editable flags:

❯ python3 -m venv venv --system-site-packages
❯ source venv/bin/activate
❯ pip install --user -e sampleproject/
Obtaining
  Installing build dependencies ... 
...
Successfully built sampleproject
Installing collected packages: peppercorn, sampleproject
...
Successfully installed peppercorn-0.6 sampleproject-3.0.0

❯ pip list --user
Package       Version Editable project location
------------- ------- -----------------------------------------
peppercorn    0.6
sampleproject 3.0.0   /Users/me/sampleproject

[zanieb]

There's some more discussion on this active in #2077

[charliermarsh]

I may expand the section on --user in PIP_COMPATIBILITY.md in the interim.