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

pip-compile's `--emit-options` is unsupported (try `--emit-b

Error message

pip-compile's `--emit-options` is unsupported (try `--emit-build-options` instead)

What it means

pip-compile's `--emit-options` writes global pip options (like `--index-url`) into the generated requirements file. uv splits this concept: it never emits arbitrary pip options, but it can emit build options via its own flag, so the compatibility validator rejects `--emit-options` with a pointer to `--emit-build-options`. The negated `--no-emit-options` only warns since uv never emits options anyway.

Source

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

            return Err(anyhow!(
                "pip-compile's `--emit-trusted-host` is unsupported"
            ));
        }

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

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

View on GitHub (pinned to f1a42680ff)

Solutions

Replace `--emit-options` with `--emit-build-options` if you need build settings preserved in the output.
For index settings, pass them explicitly at install time (`uv pip sync --index-url ...`) or via `UV_INDEX_URL`, since uv will not write them into the file.
Remove the flag entirely if nothing downstream reads options from the requirements file.

Example fix

# before
uv pip compile --emit-options requirements.in

# after
uv pip compile --emit-build-options requirements.in

Defensive patterns

Strategy: validation

Validate before calling

EMIT_FLAG_MAP = {"--emit-options": "--emit-build-options"}

def migrate_emit_flags(argv: list[str]) -> list[str]:
    return [EMIT_FLAG_MAP.get(a, a) for a in argv]

Prevention

Decide explicitly which metadata belongs in the lockfile; uv only emits build options.
Pass index configuration at install time (`--index-url`, UV_INDEX_URL) instead of expecting it inside requirements files.
Add a lint that runs `uv pip compile` in CI so flag mismatches fail the build, not production.

When it happens

Trigger: `uv pip compile --emit-options requirements.in`; the error appears immediately during argument validation, before any network or resolution work.

Common situations: Pipelines that relied on the requirements file carrying its index-url to downstream `pip install -r` steps; migrations that copy the full pip-compile flag list into uv invocations.

Related errors

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