Black

Black is a free, MIT-licensed formatter that rewrites Python files to apply a consistent style based on PEP 8. It formats whole files in place, using a default line length of 88 characters, while keeping style choices limited; indentation style cannot be configured. After reformatting, Black checks whether the abstract syntax tree remains effectively equivalent and raises an error if the check fails. It installs with pip and requires Python 3.10 or newer. Black works as a command-line tool rather than a Python library interface. Its documented integrations cover editors and IDEs including Emacs, PyCharm, IntelliJ IDEA, Vim, Neovim, Visual Studio Code, and Sublime Text, as well as GitHub Actions and doctest formatting. Install the jupyter extra for notebook formatting, though Black skips some cells, including those with certain magics or invalid syntax. The package also includes blackd, an HTTP server that binds to localhost by default. Stable releases preserve formatting within the same calendar year when options match.

Black offers a consistent, low-configuration approach to Python formatting, with editor and workflow integrations. Its command-line focus and fixed indentation style may not suit users who need a configurable library interface.

Black suits Python developers and teams who want a shared formatting style with limited configuration. It can also fit workflows using supported editors, GitHub Actions, or Jupyter notebooks.

Black is a free, open-source formatter for Python that applies a shared style to whole files. It suits developers and teams who want formatting in their command-line and editor workflows without maintaining many style choices. Its firm approach is useful for consistency, but not for projects that need configurable indentation or a Python library interface.

Overview

Black follows PEP 8 and rewrites files in place, using a default line length of 88 characters. Rather than offer a broad set of style controls, it limits options so code can look consistent across projects. That trade-off can reduce formatting debates and, by aiming for small diffs, help keep code review focused. It also means teams must accept Black’s style rather than adapt it to every existing convention.

After formatting, Black checks that the code’s abstract syntax tree remains effectively equivalent and raises an error if that check fails. Stable releases are intended to preserve the same formatting across releases within a calendar year when the same options are used, which can help avoid unnecessary style churn.

Key features

• Whole-file formatting: Black formats complete files in place. Its 88-character default gives teams a consistent baseline, but its approach is not suited to workflows that require formatting only changed lines.
• Notebook support: Install Black with the jupyter extra to format Jupyter notebooks. It skips cells with automagics, non-Python or multiline magics, transformed magic code, or invalid syntax, so notebooks mixing these patterns will not receive uniform formatting.
• Workflow integrations: Documentation covers editor and IDE integrations, including Emacs, PyCharm and IntelliJ IDEA, Vim, Neovim, Visual Studio Code, and Sublime Text. GitHub Actions support covers GitHub-hosted runner operating systems; source version control and doctest formatting integrations are also documented.
• Local and container use: The included blackd HTTP server binds to localhost by default, and official Docker images are tagged for releases and prereleases. These options give teams alternatives to invoking the formatter directly in every workflow.
• Python compatibility: Black requires Python 3.10 or newer to run and promises support for Python versions that have not reached end of life, both for running the tool and formatting code.

Pricing

Black costs free. The free plan is the MIT-licensed Python formatter, with no paid plan or trial needed. Its open-source license and free availability suit individual developers and teams standardizing Python formatting without a software subscription.

Platforms

Black supports Windows, macOS, and Linux, and can be self-hosted. It installs with pip. The local HTTP API refers to blackd; it does not mean Black offers a Python library API.

Who it's for

Choose Black if your project values a predictable shared Python style, whole-file formatting, and integrations with editors or GitHub Actions. It is less suitable when a team needs to configure indentation, format only changed lines, or call the formatter through a Python interface: Black is fundamentally a command-line tool and does not currently provide that interface.

Pros and cons

• Pro: A deliberately limited style makes consistent formatting easier to share across projects.
• Pro: The syntax-equivalence check can flag a failed safety check rather than silently accepting a changed structure.
• Pro: Editor, CI, notebook, Docker, and local-server options let teams fit Black into several development workflows.
• Con: Indentation style cannot be configured, which rules it out for teams required to preserve a different convention.
• Con: The command-line focus and lack of a Python interface make it a poor fit as an embeddable formatting library.
• Con: Notebook cells containing certain magic commands or invalid syntax are skipped, leaving some notebook code outside the formatter’s coverage.

Alternatives

For another free formatter focused on a particular language or environment, consider Code Formatting Tools. Accessibility Test Framework for Android is a free alternative on Android, Linux, macOS, and Windows. For Swift on macOS or iOS, consider swift-format. For Rust on Linux, macOS, or Windows, rustfmt is free. dprint is a free, MIT-licensed CLI with self-managed installation, available on Linux, macOS, Windows, and self-hosted environments. Go developers can choose gofmt, a free command-line executable included with Go. For web-based JavaScript formatting, js-beautify is free and MIT-licensed. PHP CS Fixer is a free option for Linux or self-hosted use and supports PHP 7.4–8.5. Scala teams can use Scalafmt, a free formatter available on Linux, macOS, Windows, and self-hosted environments.

Verdict

Black is a strong choice for Python developers who want free, consistent formatting integrated into their editor or command-line workflow, with an additional syntax-equivalence check. Look elsewhere if your project depends on configurable indentation or needs a Python library API; Black’s consistency comes from keeping those choices off the table.