{"record":{"id":"7eb39e1a2f55518b","repo":"astral-sh/uv","slug":"pip-s-user-is-unsupported-use-a-virtual-envir","errorCode":null,"errorMessage":"pip's `--user` is unsupported (use a virtual environment instead)","messagePattern":"pip's `--user` is unsupported \\(use a virtual environment instead\\)","errorType":"validation","errorClass":"anyhow::Error","httpStatus":null,"severity":"error","filePath":"crates/uv-cli/src/compat.rs","lineNumber":365,"sourceCode":"    disable_pip_version_check: bool,\n\n    #[clap(long, hide = false)]\n    user: bool,\n}\n\nimpl CompatArgs for PipInstallCompatArgs {\n    /// Validate the arguments passed for `pip install` compatibility.\n    ///\n    /// This method will warn when an argument is passed that has no effect but matches uv's\n    /// behavior. If an argument is passed that does _not_ match uv's behavior, this method will\n    /// return an error.\n    fn validate(&self) -> Result<()> {\n        if self.disable_pip_version_check {\n            warn_user!(\"pip's `--disable-pip-version-check` has no effect\");\n        }\n\n        if self.user {\n            return Err(anyhow!(\n                \"pip's `--user` is unsupported (use a virtual environment instead)\"\n            ));\n        }\n\n        Ok(())\n    }\n}\n\n/// Arguments for generic `pip` command compatibility.\n///\n/// These represent a subset of the `pip` interface that exists on all commands.\n#[derive(Args)]\npub struct PipGlobalCompatArgs {\n    #[clap(long, hide = true)]\n    disable_pip_version_check: bool,\n}\n\nimpl CompatArgs for PipGlobalCompatArgs {","sourceCodeStart":347,"sourceCodeEnd":383,"githubUrl":"https://github.com/astral-sh/uv/blob/f1a42680ff5272232d65748acf338b19778dde24/crates/uv-cli/src/compat.rs#L347-L383","documentation":"`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.","triggerScenarios":"`uv pip install --user requests` (or `--user` appended by muscle memory / a pip alias / a ported script) outside a virtual environment.","commonSituations":"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.","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."],"exampleFix":"# before\nuv pip install --user httpie\n\n# after\nuv tool install httpie\n# or\nuv venv && source .venv/bin/activate && uv pip install httpie","handlingStrategy":"validation","validationCode":"def install_packages(pkgs: list[str]) -> None:\n    argv = [\"uv\", \"pip\", \"install\", *pkgs]\n    assert \"--user\" not in argv, \"uv refuses --user; target a venv instead\"\n    env = {**os.environ, \"VIRTUAL_ENV\": os.path.abspath(\".venv\")}\n    subprocess.run(argv, env=env, check=True)","typeGuard":null,"tryCatchPattern":null,"preventionTips":["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."],"tags":["cli","pip","compatibility","virtualenv","user-site"],"backgroundTag":null,"analyzedSha":"f1a42680ff5272232d65748acf338b19778dde24","analyzedAt":"2026-08-16T04:51:47.599Z","schemaVersion":2},"datasetVersion":"2026-08-16T08:17:34.114Z"}