pytest-dev/pytest · error · UsageError

-o/--override-ini expects option=value style

Error message

-o/--override-ini expects option=value style (got: {ini_config!r}).

What it means

The -o/--override-ini command-line flag takes one or more key=value pairs that override ini options at runtime. pytest splits each argument on the first '='. If the argument has no '=' (so .split('=',1) returns a single-element list and unpacking two values fails with ValueError), pytest re-raises as UsageError with the offending argument quoted.

Solutions

Supply the override as key=value, e.g. pytest -o addopts=-ra.
For multiple overrides, repeat -o for each: pytest -o foo=1 -o bar=2.
Quote the whole pair if it contains shell metacharacters: pytest -o 'addopts=-ra -q'.

Example fix

// before
pytest -o addopts tests/
// after
pytest -o addopts=-ra tests/

Defensive patterns

Strategy: validation

Validate before calling

def is_valid_override(arg: str) -> bool:
    return '=' in arg and arg.split('=', 1)[0].strip() != ''

overrides = ['addopts', 'addopts=-ra']
for o in overrides:
    assert is_valid_override(o), f'bad -o value: {o!r}'

Type guard

null

Try / catch

null

Prevention

Always form -o overrides as key=value with a non-empty key.
Quote overrides that contain spaces to survive the shell.

When it happens

Trigger: Calling pytest -o addopts (missing =value); pytest -o =value (empty key); pytest -o 'addopts =-ra' where shell or quoting stripped the '='; passing a flag-style '-o verbose' instead of 'verbose=true'.

Common situations: Shell quoting mistakes; forgetting the value half of the override; copy-pasting an ini-style line that lacks '='.

Related errors

AI-assisted analysis of pytest-dev/pytest@0d6fbdeffa (2026-08-11). Data as JSON: /api/errors/5e2f9947536be9eb. Report an issue: GitHub.

Appendix: source

Thrown at src/_pytest/config/findpaths.py:390

    return [get_dir_from_path(path) for path in possible_paths if safe_exists(path)]


def parse_override_ini(override_ini: Sequence[str] | None) -> ConfigDict:
    """Parse the -o/--override-ini command line arguments and return the overrides.

    :raises UsageError:
        If one of the values is malformed.
    """
    overrides = {}
    # override_ini is a list of "ini=value" options.
    # Always use the last item if multiple values are set for same ini-name,
    # e.g. -o foo=bar1 -o foo=bar2 will set foo to bar2.
    for ini_config in override_ini or ():
        try:
            key, user_ini_value = ini_config.split("=", 1)
        except ValueError as e:
            raise UsageError(
                f"-o/--override-ini expects option=value style (got: {ini_config!r})."
            ) from e
        else:
            overrides[key] = ConfigValue(user_ini_value, origin="override", mode="ini")
    return overrides


CFG_PYTEST_SECTION = "[pytest] section in {filename} files is no longer supported, change to [tool:pytest] instead."


def determine_setup(
    *,
    inifile: str | None,
    override_ini: Sequence[str] | None,
    args: Sequence[str],
    rootdir_cmd_arg: str | None,
    invocation_dir: Path,
) -> tuple[Path, Path | None, ConfigDict, Sequence[str]]:

View on GitHub (pinned to 0d6fbdeffa)