astral-sh/ruff · error

The argument `--config={}` cannot be used with `--isolated`

Error message

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`.

What it means

Argument validation in ruff's CLI setup. --isolated tells ruff to ignore all configuration discovery, so also naming a config file with --config <path> is contradictory and rejected with a tip before any checking starts (anyhow::bail, non-zero exit). Only file-path --config values trigger this; inline overrides such as --config lint.select=... remain allowed together with --isolated.

Source

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

    ) -> anyhow::Result<Self> {
        let (log_level, config_options, isolated) = global_options.partition();
        let mut config_file: Option<PathBuf> = None;
        let mut overrides = Configuration::default();

        for option in config_options {
            match option {
                SingleConfigArgument::SettingsOverride(overridden_option) => {
                    let overridden_option = Arc::try_unwrap(overridden_option)
                        .unwrap_or_else(|option| option.deref().clone());
                    overrides = overrides.combine(Configuration::from_options(
                        overridden_option,
                        None,
                        &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`.

View on GitHub (pinned to d1087a4b9e)

Solutions

1. Remove --isolated if you want the named config file to apply.
2. Remove --config <file> if you want pristine default settings.
3. For 'mostly isolated with a few tweaks', use --isolated plus inline overrides: --isolated --config lint.select=E501.

Example fix

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

# after: choose one
ruff check --isolated src/
ruff check --config ruff.toml src/

def ruff_argv_ok(argv: list[str]) -> bool:
    if '--isolated' not in argv:
        return True
    for i, a in enumerate(argv):
        value = None
        if a == '--config' and i + 1 < len(argv):
            value = argv[i + 1]
        elif a.startswith('--config='):
            value = a.split('=', 1)[1]
        if value is not None and '=' not in value:  # a file path, not an override
            return False
    return True

When it happens

Trigger: Running ruff check --isolated --config ruff.toml src/ (same combination for ruff format or other subcommands), or a script/editor that concatenates both flags from different sources.

Common situations: CI pipelines assembling flags from multiple env vars; editor integrations injecting --config while the command line already has --isolated; aliases that bundle --isolated with a shared config.

Related errors

• You cannot specify more than one configuration file on the c
• 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/c38914474a4ee62b. Report an issue: GitHub.