ruff format: Format Python Code
ruff format rewrites Python files to a consistent style, similar to Black, and is part of the same ruff binary.
format is the formatter half of Ruff. It mutates files by default, which is great locally but is not what you want as a CI gate.
What it does
ruff format reformats the given files or directories in place and reports how many files were changed or left unchanged. It is a separate subcommand from check: formatting and linting are run independently. Output style is largely Black-compatible.
Common usage
ruff format .
ruff format src tests
# format a single file
ruff format src/app.pyFlags
| Flag | What it does |
|---|---|
| <paths> | Files or directories to format (default: current directory) |
| --check | Do not write; exit non-zero if files would be reformatted |
| --diff | Print the formatting changes as a diff, do not write |
| --line-length <n> | Override the configured line length |
| --target-version <ver> | Python version to target for syntax |
In CI
Never run plain ruff format in CI; it rewrites files and exits 0, so the gate passes while the runner has uncommitted changes. Use ruff format --check (or --diff) so unformatted code fails the build without modifying anything.
Common errors in CI
"N files reformatted" with exit 0 from a plain ruff format means CI just edited files it should not have. A parse error prints "error: Failed to parse ... " and exits non-zero. Mixed results between developers usually trace to different line-length or target-version settings; pin them in pyproject.toml.