Getting Started

New to Black? Don’t worry, you’ve found the perfect place to get started!

Do you like the Black code style?

Before using Black on some of your code, it might be a good idea to first understand how Black will format your code. Black isn’t for everyone and you may find something that is a dealbreaker for you personally, which is okay! The current Black code style is described here.

Try it out online

Also, you can try out Black online for minimal fuss on the Black Playground generously created by José Padilla.


Black can be installed by running pip install black. It requires Python 3.6.2+ to run, but can format Python 2 code too. Python 2 support needs the typed_ast dependency, which be installed with pip install black[python2]. If you want to format Jupyter Notebooks, install with pip install black[jupyter].

If you can’t wait for the latest hotness and want to install from GitHub, use:

pip install git+git://

Basic usage

To get started right away with sensible defaults:

black {source_file_or_directory}...

You can run Black as a package if running it as a script doesn’t work:

python -m black {source_file_or_directory}...

Next steps

Took a look at the Black code style and tried out Black? Fantastic, you’re ready for more. Why not explore some more on using Black by reading Usage and Configuration: The basics. Alternatively, you can check out the Introducing Black to your project guide.