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

pip-compile's `--pip-args` is unsupported (try passing argum

Error message

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

What it means

pip-compile's `--pip-args "ARGS"` forwards arbitrary arguments to the underlying pip invocation. That passthrough cannot be mapped onto uv (every option has its own spelling and semantics), so `PipCompileCompatArgs::validate()` rejects any `Some(pip_args)` value and tells you to pass arguments to uv directly. The pip-sync variant fails identically (compat.rs:243).

Source

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

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

        if self.emit_options {
            return Err(anyhow!(
                "pip-compile's `--emit-options` is unsupported (try `--emit-build-options` instead)"
            ));
        }

        if self.no_emit_options {
            warn_user!("pip-compile's `--no-emit-options` has no effect (uv never emits options)");
        }

        if self.pip_args.is_some() {
            return Err(anyhow!(
                "pip-compile's `--pip-args` is unsupported (try passing arguments to uv directly)"
            ));
        }

        Ok(())
    }
}

/// Arguments for `pip list` compatibility.
///
/// These represent a subset of the `pip list` interface that uv supports by default.
#[derive(Args)]
pub struct PipListCompatArgs {
    #[clap(long, hide = true)]
    disable_pip_version_check: bool,
}

impl CompatArgs for PipListCompatArgs {

View on GitHub (pinned to f1a42680ff)

Solutions

Spell each forwarded option as a native uv flag: `--index-url`/`--extra-index-url`, `--retries`, `--timeout`, etc.
For repeated sets of options, store them in `uv.toml` or `UV_*` env vars instead of a quoted blob.
Delete `--pip-args` from shared scripts so the failure surfaces for everyone, not just uv users.

Example fix

# before
uv pip compile --pip-args "--index-url=https://pypi.internal/simple" requirements.in

# after
uv pip compile --index-url https://pypi.internal/simple requirements.in

Defensive patterns

Strategy: validation

Validate before calling

def split_pip_args(pip_args: str) -> list[str]:
    """Expand a pip-tools --pip-args blob into individual uv flags."""
    import shlex
    return shlex.split(pip_args)  # then validate each against `uv pip compile --help`

Prevention

Never keep a generic option-blob variable in scripts shared across pip-like tools; enumerate flags.
When migrating, run `uv pip compile --help` and map each old flag explicitly.
Put stable options in uv.toml so command lines stay short and auditable.

When it happens

Trigger: `uv pip compile --pip-args "--index-url=https://pypi.internal/simple" requirements.in` or `uv pip sync --pip-args '--retries 5' requirements.txt`.

Common situations: Escape-hatch habits from pip-tools where undocumented options were shoved through `--pip-args`; generated CI scripts that append a generic `--pip-args` block to every tool; docker entrypoints parameterized with a single PIP_ARGS variable.

Related errors

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