The Black Code Style#

Black is a PEP 8 compliant opinionated formatter with its own style.

While keeping the style unchanged throughout releases has always been a goal, the Black code style isn’t set in stone. It evolves to accommodate for new features in the Python language and, occasionally, in response to user feedback. Large-scale style preferences presented in The Black code style are very unlikely to change, but minor style aspects and details might change according to the stability policy presented below. Ongoing style considerations are tracked on GitHub with the style issue label.

Stability Policy#

The following policy applies for the Black code style, in non pre-release versions of Black:

  • If code has been formatted with Black, it will remain unchanged when formatted with the same options using any other release in the same calendar year.

    This means projects can safely use black ~= 22.0 without worrying about formatting changes disrupting their project in 2022. We may still fix bugs where Black crashes on some code, and make other improvements that do not affect formatting.

    In rare cases, we may make changes affecting code that has not been previously formatted with Black. For example, we have had bugs where we accidentally removed some comments. Such bugs can be fixed without breaking the stability policy.

  • The first release in a new calendar year may contain formatting changes, although these will be minimised as much as possible. This is to allow for improved formatting enabled by newer Python language syntax as well as due to improvements in the formatting logic.

  • The --preview and --unstable flags are exempt from this policy. There are no guarantees around the stability of the output with these flags passed into Black. They are intended for allowing experimentation with proposed changes to the Black code style. The --preview style at the end of a year should closely match the stable style for the next year, but we may always make changes.

Documentation for both the current and future styles can be found: