The Black code style
Black is a PEP 8 compliant opinionated formatter. Black reformats entire files in place. Style configuration options are deliberately limited and rarely added. It doesn’t take previous formatting into account (see Pragmatism for exceptions).
Our documentation covers the current Black code style, but planned changes to it are also documented. They’re both worth taking a look at:
Changes to the Black code style are bound by the Stability Policy:
Please refer to this document before submitting an issue. What seems like a bug might be intended behaviour.
Pragmatism
Early versions of Black used to be absolutist in some respects. They took after its initial author. This was fine at the time as it made the implementation simpler and there were not many users anyway. Not many edge cases were reported. As a mature tool, Black does make some exceptions to rules it otherwise holds.
Please refer to this document before submitting an issue just like with the document above. What seems like a bug might be intended behaviour.
Used by
The following notable open-source projects trust Black with enforcing a consistent code style: pytest, tox, Pyramid, Django, Django Channels, Hypothesis, attrs, SQLAlchemy, Poetry, PyPA applications (Warehouse, Bandersnatch, Pipenv, virtualenv), pandas, Pillow, Twisted, LocalStack, every Datadog Agent Integration, Home Assistant, Zulip, Kedro, OpenOA, FLORIS, ORBIT, WOMBAT, and many more.
The following organizations use Black: Facebook, Dropbox, KeepTruckin, Lyft, Mozilla, Quora, Duolingo, QuantumBlack, Tesla, Archer Aviation.
Are we missing anyone? Let us know.
Testimonials
Mike Bayer, author of SQLAlchemy:
I can’t think of any single tool in my entire programming career that has given me a bigger productivity increase by its introduction. I can now do refactorings in about 1% of the keystrokes that it would have taken me previously when we had no way for code to format itself.
Dusty Phillips, writer:
Black is opinionated so you don’t have to be.
Hynek Schlawack, creator of attrs, core developer of
Twisted and CPython:
An auto-formatter that doesn’t suck is all I want for Xmas!
Carl Meyer, Django core developer:
At least the name is good.
Kenneth Reitz, creator of requests
and pipenv:
This vastly improves the formatting of our code. Thanks a ton!
Show your style
Use the badge in your project’s README.md:
[](https://github.com/psf/black)
Using the badge in README.rst:
.. image:: https://img.shields.io/badge/code%20style-black-000000.svg
:target: https://github.com/psf/black
Looks like this:
Change log
The log has become rather long. It moved to its own file.
See CHANGES.
Authors
The author list is quite long nowadays, so it lives in its own file.
See AUTHORS.md
Code of Conduct
Everyone participating in the Black project, and in particular in the issue tracker, pull requests, and social media activity, is expected to treat other people with respect and more generally to follow the guidelines articulated in the Python Community Code of Conduct.
At the same time, humor is encouraged. In fact, basic familiarity with Monty Python’s Flying Circus is expected. We are not savages.
And if you really need to slap somebody, do it with a fish while dancing.