ruff format --check: Fail CI on Unformatted Code
ruff format --check reports which files would be reformatted and exits non-zero if any would, without changing them.
This is the formatting gate for CI. It is read-only and its exit code tells you whether anyone forgot to run the formatter.
What it does
ruff format --check formats in memory, compares the result to the files on disk, and lists any that differ. It writes nothing. It exits 0 when every file is already formatted and 1 when one or more files would be reformatted.
Common usage
ruff format --check .
ruff format --check src tests
# combine with the linter in one CI step
ruff check . && ruff format --check .Flags
| Flag | What it does |
|---|---|
| --check | Verify only; exit 1 if any file would be reformatted |
| --diff | Also print what would change (implies check semantics) |
| <paths> | Files or directories to verify |
| --quiet | Reduce output to just the failing files |
In CI
Pair ruff check . with ruff format --check . so both linting and formatting gate the build. The --check exit code maps cleanly onto a failed GitHub Actions step, and because it writes nothing the working tree stays clean.
Common errors in CI
"Would reformat: src/app.py" plus "N files would be reformatted" and exit 1 means a developer did not run ruff format before pushing; fix by running ruff format locally and committing. If --check passes locally but fails in CI, the Ruff version or line-length differs between environments; pin both.