{"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":"validation","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/672bb4edf04c84f8b0753346359daee4057158f2/crates/ruff/src/commands/format.rs#L70-L106","documentation":"`ruff format --range <start:end>` reformats a byte range inside a single file, so the command aborts when the given paths resolve to more than one Python file (the count of resolved files is included in the message).","triggerScenarios":"`ruff format --range 1:20 src/` when src/ contains two or more Python files; passing multiple files or a wide glob together with `--range`.","commonSituations":"Editor/IDE integrations forwarding a selection range plus a directory; scripts written for one file later pointed at a folder; globs that unexpectedly match extra .py files.","solutions":["Pass exactly one file: `ruff format --range 0:100 path/to/file.py`","Drop `--range` to format every resolved file","Narrow the path or glob so only one Python file matches"],"exampleFix":"# before\nruff format --range 1:50 src/\n\n# after\nruff format --range 1:50 src/main.py","handlingStrategy":"validation","validationCode":"n=$(find \"$dir\" -name '*.py' -o -name '*.pyi' | wc -l)\nif [ \"$n\" -ne 1 ]; then\n  echo \"--range needs exactly one file (found $n)\" >&2\n  exit 1\nfi\nruff format --range \"$range\" \"$dir\"","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Only pass --range together with a single explicit file path","In editor integrations, always forward the active file, not its directory","Remember hidden and generated .py files count toward the resolved total"],"tags":["cli","formatter","usage"],"backgroundTag":null,"analyzedSha":"672bb4edf04c84f8b0753346359daee4057158f2","analyzedAt":"2026-08-16T08:54:05.464Z","schemaVersion":2},"datasetVersion":"2026-08-16T13:17:31.715Z"}