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

pip-sync's `--client-cert` is unsupported (uv doesn't suppor

Error message

pip-sync's `--client-cert` is unsupported (uv doesn't support dedicated client certificates)

What it means

The pip-sync compatibility validator applies the same rules as `uv pip compile`: `--client-cert` (mTLS client certificate) has no uv equivalent — uv's TLS options cover CA bundles (`--cert`, `SSL_CERT_FILE`) but not dedicated client certificates — so any `Some(client_cert)` returns an error instead of dropping your credential setup silently.

Source

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

            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!(
                "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(())
    }

View on GitHub (pinned to f1a42680ff)

Solutions

Remove `--client-cert` from the uv command line.
Terminate mTLS at a local proxy and point `--index-url` at it, so uv speaks plain HTTPS.
Track uv's TLS roadmap for client-certificate support instead of leaving the flag in scripts to fail later.

Example fix

# before
uv pip sync --client-cert client.pem requirements.txt

# after
# mTLS terminated at proxy.internal; uv uses plain HTTPS
uv pip sync --index-url https://proxy.internal/simple requirements.txt

Defensive patterns

Strategy: validation

Validate before calling

def check_mtls_flags(argv: list[str]) -> None:
    if any(a == "--client-cert" or a.startswith("--client-cert=") for a in argv):
        raise ValueError("uv has no client-certificate support; terminate mTLS upstream or use another tool")

Prevention

Design registries so plain HTTPS + internal CA is enough for automation tools.
Keep an mTLS-capable proxy in front of internal indexes.
Check uv's TLS docs each upgrade; client-cert support may land and change the workaround.

When it happens

Trigger: `uv pip sync --client-cert client.pem requirements.txt` against a registry that requires mutual TLS; often the sync half of a pip-tools pipeline whose compile half also passed `--client-cert` (which fails separately at compat.rs:111).

Common situations: Enterprise environments with mTLS-protected Artifactory; bots whose only certificate handling was `PIP_CLIENT_CERT`; migration projects that moved both compile and sync steps to uv at once.

Understand the failure class

SSL/TLS and certificate errors — how TLS handshakes and certificate validation fail.

Related errors

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