astral-sh/uv · error · anyhow::Error

pip's `--user` is unsupported (use a virtual environment ins

Error message

pip's `--user` is unsupported (use a virtual environment instead)

What it means

`uv pip install` accepts common pip flags, but `PipInstallCompatArgs::validate()` rejects `--user`: uv deliberately refuses user-site installations because they break isolation and are invisible to uv's environment management. Flags that merely do nothing (`--disable-pip-version-check`) only warn; `--user` errors because uv's behavior genuinely differs from what the flag promises.

Source

Thrown at crates/uv-cli/src/compat.rs:365

    disable_pip_version_check: bool,

    #[clap(long, hide = false)]
    user: bool,
}

impl CompatArgs for PipInstallCompatArgs {
    /// Validate the arguments passed for `pip install` compatibility.
    ///
    /// This method will warn when an argument is passed that has no effect but matches uv's
    /// behavior. If an argument is passed that does _not_ match uv's behavior, this method will
    /// return an error.
    fn validate(&self) -> Result<()> {
        if self.disable_pip_version_check {
            warn_user!("pip's `--disable-pip-version-check` has no effect");
        }

        if self.user {
            return Err(anyhow!(
                "pip's `--user` is unsupported (use a virtual environment instead)"
            ));
        }

        Ok(())
    }
}

/// Arguments for generic `pip` command compatibility.
///
/// These represent a subset of the `pip` interface that exists on all commands.
#[derive(Args)]
pub struct PipGlobalCompatArgs {
    #[clap(long, hide = true)]
    disable_pip_version_check: bool,
}

impl CompatArgs for PipGlobalCompatArgs {

View on GitHub (pinned to f1a42680ff)

Solutions

Create and target a venv: `uv venv ~/.venvs/tools && VIRTUAL_ENV=~/.venvs/tools uv pip install requests`.
Or use uv's tool layer for CLIs: `uv tool install httpie` (isolated per-tool environments, on PATH automatically).
Or scope installs to a project: `uv add requests` inside a uv-managed project.

Example fix

# before
uv pip install --user httpie

# after
uv tool install httpie
# or
uv venv && source .venv/bin/activate && uv pip install httpie

Defensive patterns

Strategy: validation

Validate before calling

def install_packages(pkgs: list[str]) -> None:
    argv = ["uv", "pip", "install", *pkgs]
    assert "--user" not in argv, "uv refuses --user; target a venv instead"
    env = {**os.environ, "VIRTUAL_ENV": os.path.abspath(".venv")}
    subprocess.run(argv, env=env, check=True)

Prevention

Replace pip-era `--user` workflows with `uv tool install` (CLIs) or per-project venvs (libraries).
In Dockerfiles, create a venv and set VIRTUAL_ENV/PATH so every later uv pip command targets it.
Alias `pip` to `uv pip` only after removing --user from your muscle-memory commands.

When it happens

Trigger: `uv pip install --user requests` (or `--user` appended by muscle memory / a pip alias / a ported script) outside a virtual environment.

Common situations: Users who ran `pip install --user` for years on systems without sudo; dotfile install scripts; SSH one-liners like `ssh host 'uv pip install --user httpie'`; Dockerfiles ported from pip-based images.

Related errors

AI-assisted analysis of astral-sh/uv@f1a42680ff (2026-08-16). Data as JSON: /api/errors/7eb39e1a2f55518b. Report an issue: GitHub.