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

pip-sync's `--user` is unsupported (use a virtual environmen

Error message

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

What it means

pip-sync's `--user` installs into the user site-packages directory. uv refuses user-site installs by design — it manages virtual environments and treats installation outside a venv as a footgun — so `PipSyncCompatArgs::validate()` rejects the flag and the message directs you to a virtual environment. (The `pip install --user` variant fails the same way at compat.rs:365.)

Source

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

    ///
    /// 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.ask {
            return Err(anyhow!(
                "pip-sync's `--ask` is unsupported (uv never asks for confirmation)"
            ));
        }

        if self.python_executable.is_some() {
            return Err(anyhow!(
                "pip-sync's `--python-executable` is unsupported (to install into a separate Python environment, try setting `VIRTUAL_ENV` instead)"
            ));
        }

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

        if self.client_cert.is_some() {
            return Err(anyhow!(
                "pip-sync's `--client-cert` is unsupported (uv doesn't support dedicated client certificates)"
            ));
        }

        if self.config.is_some() {
            return Err(anyhow!(
                "pip-sync's `--config` is unsupported (uv does not use a configuration file)"
            ));
        }

        if self.pip_args.is_some() {
            return Err(anyhow!(

View on GitHub (pinned to f1a42680ff)

Solutions

Create and use a venv: `uv venv && source .venv/bin/activate` then `uv pip sync requirements.txt`.
Or let uv pick the interpreter and env: `uv pip sync --python 3.12 requirements.txt`.
For CI/base images, install into an explicit venv path (`uv venv /usr/local/venv`) and set `VIRTUAL_ENV` to it.

Example fix

# before
uv pip sync --user requirements.txt

# after
uv venv
source .venv/bin/activate
uv pip sync requirements.txt

Defensive patterns

Strategy: validation

Validate before calling

def assert_no_user_flag(argv: list[str]) -> None:
    if "--user" in argv:
        raise ValueError("uv refuses user-site installs; create a venv and target it instead")

Prevention

Make 'create venv, then install' the default workflow in scripts and Dockerfiles.
Use `uv tool install` for CLIs you used to `pip install --user`.
Lint CI scripts for `--user` so pip-era habits fail fast.

When it happens

Trigger: `uv pip sync --user requirements.txt` or `uv pip install --user <pkg>` in scripts or muscle-memory commands carried over from pip.

Common situations: Legacy automation written when user-site installs were the norm; restricted systems without sudo where `--user` was the workaround; container images that pip-installed to user site to avoid touching the system interpreter.

Related errors

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