The uncompromising code formatter¶
By using Black, you agree to cede control over minutiae of hand-formatting. In return, Black gives you speed, determinism, and freedom from pycodestyle nagging about formatting. You will save time and mental energy for more important matters.
Black makes code review faster by producing the smallest diffs possible. Blackened code looks the same regardless of the project you’re reading. Formatting becomes transparent after a while and you can focus on the content instead.
Try it out now using the Black Playground.
Note - this is a beta product
Black is already successfully used by many projects, small and big. Black has a comprehensive test suite, with efficient parallel tests, our own auto formatting and parallel Continuous Integration runner. However, Black is still beta. Things will probably be wonky for a while. This is made explicit by the “Beta” trove classifier, as well as by the “b” in the version number. What this means for you is that until the formatter becomes stable, you should expect some formatting to change in the future. That being said, no drastic stylistic changes are planned, mostly responses to bug reports.
Also, as a safety measure which slows down processing, Black will check that the
reformatted code still produces a valid AST that is effectively equivalent to the
original (see the
section for details). If you’re feeling confident, use
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.
This vastly improves the formatting of our code. Thanks a ton!
Show your style¶
Use the badge in your project’s README.md:
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](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:
- Getting Started
- Usage and Configuration
- Frequently Asked Questions
- Does Black have an API?
- Is Black safe to use?
- How stable is Black’s style?
- Why is my file not formatted?
- Why is my Jupyter Notebook cell not formatted?
- Why are Flake8’s E203 and W503 violated?
- Does Black support Python 2?
- Why does my linter or typechecker complain after I format my code?
- Can I run Black with PyPy?
- Why does Black not detect syntax errors in my code?
- The basics
- Gauging changes
- Issue triage
- Release process
- Developer reference
- Change Log