black Version Drift Fails CI - "would reformat" After an Upgrade

black’s formatting is stable within a year’s release series but can change across calendar-year versions. When CI’s black is a different version than the one developers ran, CI reports "would reformat" on code that is already formatted locally.

What this error means

black --check fails in CI with "would reformat" on files that pass black locally. The diff is pure style (string quotes, line wrapping). black --version differs between local and CI - a version-drift mismatch, not a real formatting lapse.

black output

would reformat /repo/app/main.py
Oh no! 1 file would be reformatted.
# local black 24.x leaves it alone; CI black 25.x rewraps it

Common causes

Different black versions local vs CI

black changes its stable style across calendar-year majors. An unpinned CI black on a newer year reformats code that a pinned local black considers clean.

Pre-commit and CI out of sync

The black pinned in .pre-commit-config.yaml differs from the one installed in CI requirements, so the two disagree on formatting.

How to fix it

Pin one black version everywhere

Use the same exact black in CI, requirements, and pre-commit so formatting is identical.

config

# requirements-dev.txt
black==24.10.0
# .pre-commit-config.yaml
- repo: https://github.com/psf/black
  rev: 24.10.0

Reformat with the pinned version and commit

Terminal

pip install "black==24.10.0"
black .
git add -u && git commit -m "Reformat with pinned black"

How to prevent it

Pin the exact black version across CI, requirements, and pre-commit.
Bump black in a dedicated reformat-only change.
Keep pre-commit and CI tool versions in lockstep.