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]

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.

[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: https://github.com/astral-sh/uv/issues/2077#issuecomment-1971579880

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 https://github.com/astral-sh/uv/issues/2077

[charliermarsh]

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

[Malix-Labs]

Is there any blocker that requires some help to merge this PR? We are waiting for that feature to be merged to migrate every devcontainer we have to use uv

[imfing]

Is there any blocker that requires some help to merge this PR? We are waiting for that feature to be merged to migrate every devcontainer we have to use uv

In #2077, there were extensive discussions, and from what I gathered, it seemed the uv team prefer advocating for the adoption of virtual environments in uv.

I kept this PR open in case things change, and if the uv team is okay with adding the flag, I will update the PR.

[Malix-Labs]

Well then, installing in immutable containers (such as codespaces) would require an useless venv, as --system doesn't work

[zanieb]

@Malix-off can you please discuss this on the issue instead of this pull request? I'd prefer to keep the discussion here focused on implementation details. Thanks.

[Malix-Labs]

@zanieb absolutely, good practice btw and sorry about those annoyances

[imfing]

Noticed that --target flag was added in https://github.com/astral-sh/uv/pull/3257, which can be used as a workaround for --user by providing the user-specific site-packages directory