Format Python however you like with Black

Format Python however you like with Black

Learn more about solving common Python problems in our series covering seven PyPI libraries.

OpenStack source code (Python) in VIM
Image credits : 
Alex Sanchez. CC BY-SA 4.0.

Subscribe now

Get the highlights in your inbox every week.

Python is one of the most popular programming languages in use today—and for good reasons: it's open source, it has a wide range of uses (such as web programming, business applications, games, scientific programming, and much more), and it has a vibrant and dedicated community supporting it. This community is the reason we have such a large, diverse range of software packages available in the Python Package Index (PyPI) to extend and improve Python and solve the inevitable glitches that crop up.

In this series, we'll look at seven PyPI libraries that can help you solve common Python problems. In the first article, we learned about Cython; today, we'll examine the Black code formatter.


Sometimes creativity can be a wonderful thing. Sometimes it is just a pain. I enjoy solving hard problems creatively, but I want my Python formatted as consistently as possible. Nobody has ever been impressed by code that uses "interesting" indentation.

But even worse than inconsistent formatting is a code review that consists of nothing but formatting nits. It is annoying to the reviewer—and even more annoying to the person whose code is reviewed. It's also infuriating when your linter tells you that your code is indented incorrectly, but gives no hint about the correct amount of indentation.

Enter Black. Instead of telling you what to do, Black is a good, industrious robot: it will fix your code for you.

To see how it works, feel free to write something beautifully inconsistent like:

def add(a, b): return a+b

def mult(a, b):
      return \
        a              *        b

Does Black complain? Goodness no, it just fixes it for you!

$ black math
reformatted math
All done! ✨ 🍰 ✨
1 file reformatted.
$ cat math
def add(a, b):
    return a + b

def mult(a, b):
    return a * b

Black does offer the option of failing instead of fixing and even outputting a diff-style edit. These options are great in a continuous integration (CI) system that enforces running Black locally. In addition, if the diff output is logged to the CI output, you can directly paste it into patch in the rare case that you need to fix your output but cannot install Black locally.

$ black --check --diff bad
--- math 2019-04-09 17:24:22.747815 +0000
+++ math 2019-04-09 17:26:04.269451 +0000
@@ -1,7 +1,7 @@
-def add(a, b): return a + b
+def add(a, b):
+    return a + b
 def mult(a, b):
-          return \
-                  a             *             b
+    return a * b
would reformat math
All done! 💥 💔 💥
1 file would be reformatted.
$ echo $?

In the next article in this series, we'll look at attrs, a library that helps you write concise, correct code quickly.

Programming at a browser, orange hands

Learn more about solving common Python problems in our series covering seven PyPI libraries.


About the author

Moshe sitting down, head slightly to the side. His t-shirt has Guardians of the Galaxy silhoutes against a background of sound visualization bars.
Moshe Zadka - Moshe has been involved in the Linux community since 1998, helping in Linux "installation parties". He has been programming Python since 1999, and has contributed to the core Python interpreter. Moshe has been a DevOps/SRE since before those terms existed, caring deeply about software reliability, build reproducibility and other such things. He has worked in companies as small as three people and as big as tens of thousands -- usually some place around where software meets system administration...