astral-sh/ruff · error

You cannot specify more than one configuration file on the c

Error message

You cannot specify more than one configuration file on the command line.

  tip: remove either `--config={first}` or `--config={second}`.
       For more information, try `--help`.

What it means

ruff accepts exactly one --config argument pointing at a file per invocation; a second file-path --config is rejected with a tip naming both paths. Multiple inline setting overrides (--config lint.line-length=100) do not count — only FilePath-style arguments trip this error.

Source

Thrown at crates/ruff/src/args.rs:758

                        &path_dedot::CWD,
                    )?);
                }
                SingleConfigArgument::FilePath(path) => {
                    if isolated {
                        bail!(
                            "\
The argument `--config={}` cannot be used with `--isolated`

  tip: You cannot specify a configuration file and also specify `--isolated`,
       as `--isolated` causes ruff to ignore all configuration files.
       For more information, try `--help`.
",
                            path.display()
                        );
                    }
                    if let Some(ref config_file) = config_file {
                        let (first, second) = (config_file.display(), path.display());
                        bail!(
                            "\
You cannot specify more than one configuration file on the command line.

  tip: remove either `--config={first}` or `--config={second}`.
       For more information, try `--help`.
"
                        );
                    }
                    config_file = Some(path);
                }
            }
        }
        Ok(Self {
            isolated,
            log_level,
            config_file,
            overrides,
            per_flag_overrides,

View on GitHub (pinned to d1087a4b9e)

Solutions

1. Keep a single config file and merge any extra settings into it.
2. For deltas, use inline overrides next to the one file: --config ruff.toml --config lint.line-length=100.
3. If two tools both inject --config, disable one (e.g. clear the editor's ruff.config setting for CLI runs).

Example fix

# before
ruff check --config ruff.toml --config pyproject.toml src/

# after: one file plus inline overrides
ruff check --config ruff.toml --config lint.line-length=100 src/

def config_files(argv: list[str]) -> list[str]:
    out = []
    for i, a in enumerate(argv):
        if a == '--config' and i + 1 < len(argv):
            out.append(argv[i + 1])
        elif a.startswith('--config='):
            value = a.split('=', 1)[1]
            if '=' not in value:
                out.append(value)
    return out

assert len(config_files(sys.argv)) <= 1, 'only one --config file allowed'

When it happens

Trigger: Running ruff check --config ruff.toml --config pyproject.toml src/, or a wrapper/extension that injects its own --config while the user also passes one.

Common situations: Editor extensions (e.g. a configured ruff.config) layered on top of CLI-driven runs; scripts appending a project config to a command that already has one; migrating configs and passing both old and new.

Related errors

• The argument `--config={}` cannot be used with `--isolated`
• Unknown option: {key}
• No files found under the given path
• Unsupported serialization format for statistics: {:?}
• The `--range` option is only supported when formatting a sin

AI-assisted analysis of astral-sh/ruff@d1087a4b9e (2026-08-20). Data as JSON: /api/errors/0123fc0cccb906d8. Report an issue: GitHub.