{"record":{"id":"1dc5c19f40243340","repo":"astral-sh/ruff","slug":"the-range-option-is-only-supported-when-format","errorCode":null,"errorMessage":"The `--range` option is only supported when formatting a single file but the specified paths resolve to {} files.","messagePattern":"The `--range` option is only supported when formatting a single file but the specified paths resolve to (.+?) files\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/ruff/src/commands/format.rs","lineNumber":88,"sourceCode":"/// Format a set of files, and return the exit status.\npub(crate) fn format(\n    cli: FormatArguments,\n    config_arguments: &ConfigArguments,\n    pyproject_config: &PyprojectConfig,\n) -> Result<ExitStatus> {\n    let mode = FormatMode::from_cli(&cli);\n    let files = resolve_default_files(cli.files, false);\n    let (paths, resolver) = project_files_in_path(&files, pyproject_config, config_arguments)?;\n\n    let output_format = pyproject_config.settings.output_format;\n\n    if paths.is_empty() {\n        warn_user_once!(\"No Python files found under the given path(s)\");\n        return Ok(ExitStatus::Success);\n    }\n\n    if cli.range.is_some() && paths.len() > 1 {\n        return Err(anyhow::anyhow!(\n            \"The `--range` option is only supported when formatting a single file but the specified paths resolve to {} files.\",\n            paths.len()\n        ));\n    }\n\n    warn_incompatible_formatter_settings(&resolver);\n\n    // Discover the package root for each Python file.\n    let package_roots = resolver.package_roots(\n        &paths\n            .iter()\n            .flatten()\n            .map(ResolvedFile::path)\n            .collect::<Vec<_>>(),\n    );\n\n    let caches = if cli.no_cache {\n        None","sourceCodeStart":70,"sourceCodeEnd":106,"githubUrl":"https://github.com/astral-sh/ruff/blob/5bb508f59481c1a02d5c7ff8568b9ffd8a763eef/crates/ruff/src/commands/format.rs#L70-L106","documentation":"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.","triggerScenarios":"Invoking `ruff format --range <start>-<end>` with a path (directory or multiple files) that resolves to `paths.len() > 1` files.","commonSituations":"Passing a directory to `ruff format --range`, using a glob that matches several files, or combining `--range` with stdin-plus-file arguments.","solutions":["Pass exactly one Python file path together with `--range`.","If you need to reformat multiple files, drop `--range` and format the files wholly.","If a directory was intended, first resolve the single target file (e.g. `ruff format --range 1-50 path/to/file.py`)."],"exampleFix":"// before\n$ ruff format --range 1-50 src/\n// after\n$ ruff format --range 1-50 src/module.py","handlingStrategy":"validation","validationCode":"#!/bin/sh\nRANGE=\"$1\"; shift\nif [ -n \"$RANGE\" ] && [ \"$#\" -gt 1 ]; then\n  echo \"--range requires exactly one file\"; exit 2\nfi\nruff format --range \"$RANGE\" \"$@\"","typeGuard":null,"tryCatchPattern":"match format_with_range(args) {\n    Err(e) if e.to_string().contains(\"--range\") && e.to_string().contains(\"files\") => {\n        eprintln!(\"Pass a single file with --range; run `ruff format` without --range for batches\");\n    }\n    other => other?,\n}","preventionTips":["Only combine `--range` with a single explicit file path.","Never pass directories or globs when using `--range`.","In scripts, count resolved inputs and drop `--range` when more than one file is targeted."],"tags":["cli","formatter","arguments","ruff"],"backgroundTag":"option-requires-single-file","analyzedSha":"5bb508f59481c1a02d5c7ff8568b9ffd8a763eef","analyzedAt":"2026-09-05T10:32:37.492Z","contentChangedAt":"2026-09-05T10:32:37.492Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}