black --check: Formatting Gate Command Reference

Fail the build when code is not Black-formatted.

black --check verifies that files already match Black formatting without modifying them. It is the CI counterpart to running black locally to format code.

Common flags / usage

• black --check . -- exit non-zero if any file would change
• --diff -- print the formatting diff that would be applied
• --check --diff -- gate and show what is wrong in one run
• exit 0 = formatted, exit 1 = would reformat

Example

- run: pip install black
- run: black --check --diff .

In CI

Use --check (not a bare black) so CI never rewrites the working tree -- it only reports. Adding --diff makes the log show exactly which lines violate formatting, so contributors can fix them quickly.

Key takeaways

• black --check reports formatting drift without editing files.
• --diff shows the changes Black would make.
• It exits non-zero on unformatted code, gating the build.

Related guides