astral-sh/ruff · error

The argument `--config=

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

Ruff's CLI rejects combining `--isolated` (which makes ruff ignore all configuration files) with an explicit `--config=<path>`. The two options are contradictory, so argument parsing bails with this error pointing at both flags and suggesting `--help`.

Solutions

1. Remove `--config=...` if you truly want isolated, default-settings behavior.
2. Remove `--isolated` when you need the settings from the specified config file.
3. Move the shared settings into the config file and drop `--isolated` from wrapper scripts/aliases.

Example fix

// before
ruff check --isolated --config=ruff.toml src/
// after
ruff check --config=ruff.toml src/

# Reject the conflicting combination before invoking ruff:
flags = sys.argv[1:]
if '--isolated' in flags and any(f.startswith('--config=') or f == '--config' for f in flags):
    raise SystemExit('--config cannot be used with --isolated')

When it happens

Trigger: Invoking ruff with both `--isolated` and `--config=path/to/pyproject.toml|ruff.toml` (or a resolved config file argument) on the same command line.

Common situations: Shell aliases or wrapper scripts that always add `--isolated` while users append a config path; CI scripts combining flags from different sources; editor integrations injecting `--config` into commands already using `--isolated`.

Related errors

• You cannot specify more than one configuration file on the…
• Expected
• No files found under the given path
• Unknown option
• Working directory does not exist

AI-assisted analysis of astral-sh/ruff@15f3fe6b15 (2026-09-05). Data as JSON: /api/errors/c38914474a4ee62b. Report an issue: GitHub.

Appendix: 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 15f3fe6b15)