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
Plans
Every plan and priceBlack
Free plan
Getting started
- Install Python 3.10 or newer
- Install Black with pip
- Add the jupyter extra for notebook formatting
- Connect Black to a supported editor or IDE
- 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.