Skip to the content
Know your tech before you buy it. Makers: get listed from $49/mo

Black

black.readthedocs.io

  • Free plan
  • Windows
  • macOS
  • Linux
  • Self-hosted

What Black is

Black is a free Python formatter that follows PEP 8 and applies a consistent style across code. It reformats entire files in place, using an 88-character default line length, and offers few style choices; indentation style cannot be configured. After formatting, Black checks that the abstract syntax tree is effectively equivalent and raises an error if the check fails. Install it with pip; running Black requires Python 3.10 or newer. It is primarily a command-line tool and does not provide a Python interface. Its documented integrations include editors and IDEs such as Emacs, PyCharm, IntelliJ IDEA, Vim, Neovim, Visual Studio Code, and Sublime Text, as well as GitHub Actions and doctest formatting. Notebook formatting is available with the jupyter extra, although cells with certain magics or invalid syntax are skipped. Black also includes blackd, an HTTP server that binds to localhost by default. For stable releases, formatting remains unchanged across releases in the same calendar year when the same options are used. Black is licensed under the MIT License.

Who it suits

Black suits Python developers who want consistent formatting across projects and editor or CI workflows. Its limited style controls may not suit teams that need to configure indentation.

Good to know, and what to watch

  • Formats whole files with an 88-character default line length
  • Checks abstract syntax tree equivalence after formatting
  • Integrates with listed editors and GitHub Actions
  • Supports notebook formatting with the jupyter extra
  • Requires Python 3.10 or newer
  • Does not provide a Python interface
  • Indentation style cannot be configured
  • Some notebook cells are skipped

Black

Free

Free plan

Getting started

  1. Install Python 3.10 or newer
  2. Install Black with pip
  3. Add the jupyter extra for notebook formatting
  4. Connect Black to a supported editor or IDE
  5. Use GitHub Actions, Docker, or blackd if needed

Limits to check

Black has no configurable indentation style and no Python interface. Notebook formatting skips cells containing certain magics, non-Python or transformed magic code, or invalid syntax.

The verdict

Black offers a consistent, low-configuration formatting approach with editor and workflow integrations. Consider its command-line focus and fixed indentation style before adopting it.

Questions people ask

What does Black cost?

Black is free and licensed under the MIT License.

Which operating systems are supported?

Black supports Windows, macOS, and Linux, and also provides a local HTTP API through blackd.

Which language does Black format?

Black formats Python code and follows PEP 8.

Does Black provide a library API?

No. The documentation describes Black as fundamentally a command-line tool without a Python interface.

Can Black format Jupyter Notebooks?

Yes, when installed with the jupyter extra. Certain magic, non-Python, transformed-magic, or invalid-syntax cells are skipped.

Which integrations are available?

Documented integrations include Emacs, PyCharm, IntelliJ IDEA, Vim, Neovim, Visual Studio Code, Sublime Text, GitHub Actions, source version control, and doctest formatting.

What the maker publishes

API limit
Black is fundamentally a command-line tool and does not currently provide a Python interface. source
CI integration
Black provides a GitHub Actions integration that supports GitHub-hosted runner operating systems. source
Code review
Black says it can make code review faster by producing the smallest diffs possible. source
Command line tool
Black is fundamentally a command line tool and the documentation says it does not yet provide a Python interface. source
Configuration limit
Black provides no option to configure indentation style and says requests for that option will not be considered. source
Consistent style
Black limits style options and aims to make code look consistent across projects. source
Docker
Official Black Docker images are available, with tags for releases and prereleases. source
Editor integrations
The documentation describes integrations for editors including PyCharm, Vim, Neovim, Visual Studio Code, and Sublime Text. source
Editor support
Documented editor integrations include Emacs, PyCharm and IntelliJ IDEA, Vim, Neovim, Visual Studio Code, SublimeText, and others. source
Formatting
Black reformats whole files in place and uses a default line length of 88 characters. source
Installation
Black installs with pip and requires Python 3.10 or newer to run. source
Installation
Black installs with pip or pipx and requires Python 3.10 or later to run. source
Integrations
The documentation lists editor and IDE, GitHub Actions, source version control, and doctest formatting integrations. source
License
Black is licensed under the MIT License. source
License
Black is licensed under the MIT license. source
Local server
Black includes blackd, an HTTP server that binds to localhost by default. source
Notebook limits
Black skips notebook cells containing automagics, non-Python or multiline magics, transformed magic code, or invalid syntax. source
Notebook support
Jupyter Notebook formatting is available by installing Black with the jupyter extra. source
Notebook support
Jupyter Notebook formatting is available with the black[jupyter] installation extra. source
Purpose
Black is an opinionated formatter for Python code that follows PEP 8. source
Python compatibility
Black promises support for Python versions that have not reached end of life, for both running Black and formatting code. source
Safety check
Black checks that reformatted code has an effectively equivalent abstract syntax tree and raises an error if the check fails. source
Safety check
Black checks that reformatted code has a valid AST effectively equivalent to the original and raises an error without changing the file if issues are found. source
Style stability
For stable releases, code formatted with a release remains unchanged under other releases in the same calendar year when using the same options. source

Checked against the maker's pages on 29 Sept 2026.