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

pip-sync's `--pip-args` is unsupported (try passing argument

Error message

pip-sync's `--pip-args` is unsupported (try passing arguments to uv directly)

What it means

pip-sync's `--pip-args "ARGS"` forwards a raw option string to the embedded pip invocation. uv is not pip; there is no nested command to forward arguments to, and blanket passthrough would break its guarantees, so `PipSyncCompatArgs::validate()` rejects any value and the message says to pass arguments to uv directly.

Source

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

            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!(
                "pip-sync's `--pip-args` is unsupported (try passing arguments to uv directly)"
            ));
        }

        Ok(())
    }
}

#[derive(Debug, Copy, Clone, ValueEnum)]
enum Resolver {
    Backtracking,
    Legacy,
}

/// Arguments for `venv` compatibility.
///
/// These represent a subset of the `virtualenv` interface that uv supports by default.
#[derive(Args)]

View on GitHub (pinned to f1a42680ff)

Solutions

Convert each option to its uv spelling on the command line (`--extra-index-url`, `--retries`, `--no-cache`, ...).
Move stable options into `uv.toml`/`UV_*` variables and keep only per-run flags in the script.
Delete the generic passthrough variable so future unsupported options fail visibly instead of hiding in a quoted string.

Example fix

# before
uv pip sync --pip-args '--extra-index-url https://pypi.internal/simple' requirements.txt

# after
uv pip sync --extra-index-url https://pypi.internal/simple requirements.txt

Defensive patterns

Strategy: validation

Validate before calling

def expand_pip_args_for_sync(pip_args: str) -> list[str]:
    import shlex
    flags = shlex.split(pip_args)
    for f in flags:
        assert not f.startswith("--pip-args")
    return flags  # append directly to `uv pip sync` argv

Prevention

Eliminate option-blob variables; list each flag explicitly in scripts.
Validate expanded flags against `uv pip sync --help` in a unit test for your CI glue.
Move repeated options into uv.toml or UV_* environment variables.

When it happens

Trigger: `uv pip sync --pip-args '--extra-index-url https://pypi.internal/simple' requirements.txt`; commonly a variable-expanded blob like `--pip-args "$SYNC_ARGS"` inside a shared script.

Common situations: Escape hatches from pip-tools kept 'just in case'; parameterized CI templates where one string configures either pip-sync or uv; local wrapper functions that append generic pip options.

Related errors

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