black --check "would reformat" exits 1 in CI

By Kaveh Alemi·Latchkey

black --check does not modify files; it reports which would change and exits 1 if any are not formatted. The summary "N files would be reformatted" lists the count.

What this error means

The format check prints "would reformat path/to/file.py", a summary line like "Oh no! ... 1 file would be reformatted", and exits with code 1.

would reformat /home/runner/work/app/app/main.py
Oh no! 💥 💔 💥
1 file would be reformatted, 12 files would be left unchanged.

Common causes

Files were not formatted with black

The listed files differ from black's output, so --check reports them and fails.

A black version change shifted formatting

A different black version (or a changed stable style) formats code differently than the version that last formatted it.

How to fix it

Format and commit

1. Run black . to format the files.
2. Commit the reformatted files.
3. Re-run black --check . and confirm exit 0.

black .
black --check .

Pin black across local and CI

Lock the black version so local formatting matches the CI --check.

pip install "black==24.4.2"

How to prevent it

• Run black in a pre-commit hook.
• Pin black to an exact version in your dependencies.
• Keep one black config (target-version, line-length) shared by all.

Frequently asked questions

Related guides

References

• Node.js documentation
• npm CLI documentation
• GitHub Actions documentation