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

pip-sync's `--python-executable` is unsupported (to install

Error message

pip-sync's `--python-executable` is unsupported (to install into a separate Python environment, try setting `VIRTUAL_ENV` instead)

What it means

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`.

Source

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

    #[clap(long, hide = true)]
    pip_args: Option<String>,
}

impl CompatArgs for PipSyncCompatArgs {
    /// Validate the arguments passed for `pip-sync` 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.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!(

View on GitHub (pinned to f1a42680ff)

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.

Example fix

# before
uv pip sync --python-executable /envs/app/bin/python requirements.txt

# after
VIRTUAL_ENV=/envs/app uv pip sync requirements.txt
# or: uv pip sync --python /envs/app/bin/python requirements.txt

Defensive patterns

Strategy: validation

Validate before calling

import os

def sync_into(venv_path: str, reqs: str) -> None:
    env = {**os.environ, "VIRTUAL_ENV": venv_path}
    argv = ["uv", "pip", "sync", reqs]
    assert "--python-executable" not in " ".join(argv)
    subprocess.run(argv, env=env, check=True)

Prevention

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.

When it happens

Trigger: `uv pip sync --python-executable /envs/app/bin/python requirements.txt` in scripts ported from pip-tools.

Common situations: 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.

Related errors

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