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

pip-sync's `--config` is unsupported (uv does not use a conf

Error message

pip-sync's `--config` is unsupported (uv does not use a configuration file)

What it means

pip-sync inherits pip's `--config PATH` for a pip.conf file. uv does not read pip configuration files in any form; its configuration surface is CLI flags, `UV_*` environment variables, and `uv.toml`/`pyproject.toml`. Because silently ignoring a config file would change what gets installed, `PipSyncCompatArgs::validate()` rejects the flag outright.

Source

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

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

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

View on GitHub (pinned to f1a42680ff)

Solutions

Remove `--config` and replicate needed settings in `uv.toml` or `[tool.uv]`.
Supply index/credentials via env (`UV_INDEX_URL`, `UV_INDEX_USERNAME`, `UV_INDEX_PASSWORD`) or `.netrc` where supported.
For per-directory pipelines, place a small `uv.toml` next to each requirements file.

Example fix

# before
uv pip sync --config /etc/pip-tools.conf requirements.txt

# after
# uv.toml: index settings + credentials
uv pip sync requirements.txt

Defensive patterns

Strategy: validation

Validate before calling

def assert_no_config_flag(argv: list[str]) -> None:
    if any(a == "--config" or a.startswith("--config=") for a in argv):
        raise ValueError("uv does not read config files; use uv.toml, UV_* env vars, or flags")

Prevention

Port pip.conf contents to uv.toml as part of the migration, not after the first failure.
Keep credentials in env vars or the credential API, never in files only pip reads.
Assert in CI that no `--config` remains in migrated commands.

When it happens

Trigger: `uv pip sync --config /etc/pip.conf requirements.txt` in provisioning scripts or Dockerfiles ported from pip-sync.

Common situations: Golden images with a global pip.conf for index URLs and credentials; multi-tenant CI runners passing a per-job config file; teams assuming pip-config compatibility because the subcommand is named `pip sync`.

Related errors

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