astral-sh/ruff · error

The `--range` option is only supported when formatting a…

Error message

The `--range` option is only supported when formatting a single file but the specified paths resolve to {} files.

What it means

Ruff's formatter supports `--range` to reformat only a byte range of one file. When the given paths resolve to more than one Python file, formatting a single range is ill-defined, so `format` returns this error before doing any work.

Solutions

1. Pass exactly one Python file path together with `--range`.
2. If you need to reformat multiple files, drop `--range` and format the files wholly.
3. If a directory was intended, first resolve the single target file (e.g. `ruff format --range 1-50 path/to/file.py`).

Example fix

// before
$ ruff format --range 1-50 src/
// after
$ ruff format --range 1-50 src/module.py

#!/bin/sh
RANGE="$1"; shift
if [ -n "$RANGE" ] && [ "$#" -gt 1 ]; then
  echo "--range requires exactly one file"; exit 2
fi
ruff format --range "$RANGE" "$@"

match format_with_range(args) {
    Err(e) if e.to_string().contains("--range") && e.to_string().contains("files") => {
        eprintln!("Pass a single file with --range; run `ruff format` without --range for batches");
    }
    other => other?,
}

When it happens

Trigger: Invoking `ruff format --range <start>-<end>` with a path (directory or multiple files) that resolves to `paths.len() > 1` files.

Common situations: Passing a directory to `ruff format --range`, using a glob that matches several files, or combining `--range` with stdin-plus-file arguments.

Related errors

• Can only write to stdout when formatting from stdin, but…
• Content not correctly formatted
• cannot contain newline characters
• Expected
• No files found under the given path

AI-assisted analysis of astral-sh/ruff@5bb508f594 (2026-09-05). Data as JSON: /api/errors/1dc5c19f40243340. Report an issue: GitHub.

Appendix: source

Thrown at crates/ruff/src/commands/format.rs:88

/// Format a set of files, and return the exit status.
pub(crate) fn format(
    cli: FormatArguments,
    config_arguments: &ConfigArguments,
    pyproject_config: &PyprojectConfig,
) -> Result<ExitStatus> {
    let mode = FormatMode::from_cli(&cli);
    let files = resolve_default_files(cli.files, false);
    let (paths, resolver) = project_files_in_path(&files, pyproject_config, config_arguments)?;

    let output_format = pyproject_config.settings.output_format;

    if paths.is_empty() {
        warn_user_once!("No Python files found under the given path(s)");
        return Ok(ExitStatus::Success);
    }

    if cli.range.is_some() && paths.len() > 1 {
        return Err(anyhow::anyhow!(
            "The `--range` option is only supported when formatting a single file but the specified paths resolve to {} files.",
            paths.len()
        ));
    }

    warn_incompatible_formatter_settings(&resolver);

    // Discover the package root for each Python file.
    let package_roots = resolver.package_roots(
        &paths
            .iter()
            .flatten()
            .map(ResolvedFile::path)
            .collect::<Vec<_>>(),
    );

    let caches = if cli.no_cache {
        None

View on GitHub (pinned to 5bb508f594)