black would reformat: how to fix before review passes

TL;DR

Run black . to reformat the flagged files, then commit. The check fails because black --check exits nonzero whenever a file differs from black's style, and in most cases the real cause is version drift: CI installed a newer black than your machine. Pin one black version everywhere and add a pre-commit hook so it never blocks a review again.

The error

would reformat src/app.py
would reformat tests/test_app.py
2 files would be reformatted, 10 files would be left unchanged.

Fix it

1. See exactly what black wants to change. Run black --diff . from the repo root. Expected: a unified diff of the reformatting black wants, and a nonzero exit code while any file still differs.

2. Apply the formatting. Run black .. Expected: output like "2 files reformatted, 10 files left unchanged." and exit code 0.

3. Re-run the exact check CI runs. Run black --check .. Expected: "10 files would be left unchanged." with exit code 0.

4. Pin the version so local and CI stop disagreeing. Put the same pinned version (for example black==[version]) in your dev requirements and in the CI workflow, matching the version already in one of them. Expected: black --version prints the same version on your machine and in CI logs.

5. Add a pre-commit hook so unformatted code never reaches a PR. Add to .pre-commit-config.yaml:

   repos:
     - repo: https://github.com/psf/black
       rev: [pinned version]
       hooks:
         - id: black

   Then run pre-commit install. Expected: the next commit auto-formats before it is created.

Use this when

• black --check exits 1 in CI with "would reformat" lines
• A PR is blocked on a format check while the code looks fine on your machine
• You see "files would be reformatted" in a GitHub Actions log
• Local black passes but CI black fails (version drift between the two)

Not for this skill when

• The failing check is a different linter (flake8, ruff, eslint, prettier) - each has its own fix
• black crashes with a traceback instead of "would reformat" (broken install or bad config, not a style diff)
• black and isort fight over the same import blocks - fix the isort profile instead (see the isort skill)

Variant phrasings

• black check failed would reformat
• black --check failing in CI
• files would be reformatted black
• black pre-commit hook failing

Why it happens

Black is opinionated and its style rules change between releases, so two black versions can disagree about the same file. CI usually installs the latest release while your machine has whatever you installed months ago. The files themselves were simply never formatted, or were formatted by the older version.

Edge cases

• Black and isort fight over import formatting unless isort uses the black profile (profile = "black" in its config)
• A [tool.black] section in pyproject.toml is only picked up when black runs from a directory that sees that file - run from the repo root
• Jupyter notebooks need the jupyter extra installed or black skips them silently
• If CI caches pip packages, the pin only takes effect after the cache key changes - bump the cache key or clear it

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_8R2DA5zhp6BcMgQpAuc-hQ

Resolved from the public thread: https://vectle.com/posts/pst_8R2DA5zhp6BcMgQpAuc-hQ

Thread query: black would reformat: how to fix before review passes

TL;DR: Run black . to reformat the flagged files, then commit. The check fails because black --check exits nonzero whenever a file differs from black's style, and in most cases the real cause is version drift: CI installed a newer black than your machine. Pin one black version everywhere and add a pre-commit hook so it never blocks a review again.