{"record":{"id":"25e0d10a6d54510b","repo":"astral-sh/uv","slug":"pip-sync-s-user-is-unsupported-use-a-virtual","errorCode":null,"errorMessage":"pip-sync's `--user` is unsupported (use a virtual environment instead)","messagePattern":"pip-sync'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":225,"sourceCode":"    ///\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.ask {\n            return Err(anyhow!(\n                \"pip-sync's `--ask` is unsupported (uv never asks for confirmation)\"\n            ));\n        }\n\n        if self.python_executable.is_some() {\n            return Err(anyhow!(\n                \"pip-sync's `--python-executable` is unsupported (to install into a separate Python environment, try setting `VIRTUAL_ENV` instead)\"\n            ));\n        }\n\n        if self.user {\n            return Err(anyhow!(\n                \"pip-sync's `--user` is unsupported (use a virtual environment instead)\"\n            ));\n        }\n\n        if self.client_cert.is_some() {\n            return Err(anyhow!(\n                \"pip-sync's `--client-cert` is unsupported (uv doesn't support dedicated client certificates)\"\n            ));\n        }\n\n        if self.config.is_some() {\n            return Err(anyhow!(\n                \"pip-sync's `--config` is unsupported (uv does not use a configuration file)\"\n            ));\n        }\n\n        if self.pip_args.is_some() {\n            return Err(anyhow!(","sourceCodeStart":207,"sourceCodeEnd":243,"githubUrl":"https://github.com/astral-sh/uv/blob/f1a42680ff5272232d65748acf338b19778dde24/crates/uv-cli/src/compat.rs#L207-L243","documentation":"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.)","triggerScenarios":"`uv pip sync --user requirements.txt` or `uv pip install --user <pkg>` in scripts or muscle-memory commands carried over from pip.","commonSituations":"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.","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."],"exampleFix":"# before\nuv pip sync --user requirements.txt\n\n# after\nuv venv\nsource .venv/bin/activate\nuv pip sync requirements.txt","handlingStrategy":"validation","validationCode":"def assert_no_user_flag(argv: list[str]) -> None:\n    if \"--user\" in argv:\n        raise ValueError(\"uv refuses user-site installs; create a venv and target it instead\")","typeGuard":null,"tryCatchPattern":null,"preventionTips":["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."],"tags":["cli","pip-tools","compatibility","sync","virtualenv","user-site"],"backgroundTag":null,"analyzedSha":"f1a42680ff5272232d65748acf338b19778dde24","analyzedAt":"2026-08-16T04:51:47.599Z","schemaVersion":2},"datasetVersion":"2026-08-16T08:17:34.114Z"}