{"record":{"id":"670c8c5d53f3a84e","repo":"astral-sh/uv","slug":"pip-sync-s-python-executable-is-unsupported-t","errorCode":null,"errorMessage":"pip-sync's `--python-executable` is unsupported (to install into a separate Python environment, try setting `VIRTUAL_ENV` instead)","messagePattern":"pip-sync's `--python-executable` is unsupported \\(to install into a separate Python environment, try setting `VIRTUAL_ENV` instead\\)","errorType":"validation","errorClass":"anyhow::Error","httpStatus":null,"severity":"error","filePath":"crates/uv-cli/src/compat.rs","lineNumber":219,"sourceCode":"    #[clap(long, hide = true)]\n    pip_args: Option<String>,\n}\n\nimpl CompatArgs for PipSyncCompatArgs {\n    /// Validate the arguments passed for `pip-sync` 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.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!(","sourceCodeStart":201,"sourceCodeEnd":237,"githubUrl":"https://github.com/astral-sh/uv/blob/f1a42680ff5272232d65748acf338b19778dde24/crates/uv-cli/src/compat.rs#L201-L237","documentation":"pip-sync's `--python-executable PATH` selects which interpreter's environment to install into. uv's pip interface selects the target environment differently — from the active `VIRTUAL_ENV`, `--python`, or discovery — and cannot honor a raw executable path, so `PipSyncCompatArgs::validate()` rejects the flag with the supported alternative: set `VIRTUAL_ENV`.","triggerScenarios":"`uv pip sync --python-executable /envs/app/bin/python requirements.txt` in scripts ported from pip-tools.","commonSituations":"Multi-env automation where a variable holds the interpreter path; tox/nox-like drivers that install into several environments in a loop; CI jobs that never activate a venv and instead point pip-tools at the interpreter.","solutions":["Export `VIRTUAL_ENV=/envs/app` before `uv pip sync` (uv installs into that venv).","Or select with uv's own flag: `uv pip sync --python /envs/app/bin/python requirements.txt`.","Or use project workflows (`uv sync --python 3.12`) where environment selection is first-class."],"exampleFix":"# before\nuv pip sync --python-executable /envs/app/bin/python requirements.txt\n\n# after\nVIRTUAL_ENV=/envs/app uv pip sync requirements.txt\n# or: uv pip sync --python /envs/app/bin/python requirements.txt","handlingStrategy":"validation","validationCode":"import os\n\ndef sync_into(venv_path: str, reqs: str) -> None:\n    env = {**os.environ, \"VIRTUAL_ENV\": venv_path}\n    argv = [\"uv\", \"pip\", \"sync\", reqs]\n    assert \"--python-executable\" not in \" \".join(argv)\n    subprocess.run(argv, env=env, check=True)","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Standardize env selection via VIRTUAL_ENV or `--python` in all uv pip commands.","In multi-env loops, set VIRTUAL_ENV per iteration rather than passing interpreter paths.","Delete `--python-executable` from ported scripts in the same commit as the tool switch."],"tags":["cli","pip-tools","compatibility","sync","virtualenv"],"backgroundTag":null,"analyzedSha":"f1a42680ff5272232d65748acf338b19778dde24","analyzedAt":"2026-08-16T04:51:47.599Z","schemaVersion":2},"datasetVersion":"2026-08-16T08:17:34.114Z"}