psf/black

What Black does

Black is an opinionated Python formatter that reformats entire files in place. Instead of exposing many style options, it applies one stable style so code reads the same across projects and review diffs stay small. It targets Python developers and teams who want formatting decisions automated, including people working in Jupyter Notebooks.

By default Black checks that reformatted code still produces an equivalent AST, which slows processing slightly; --fast skips that check. The style is PEP 8 compliant and changes are governed by a documented stability policy, so large formatting shifts are not expected between releases.

Install and run

Black requires Python 3.11+ to run. Install it from PyPI:

pip install black

To format Jupyter Notebooks as well, install the extra:

pip install "black[jupyter]"

Run it on a file or directory with the defaults:

black {source_file_or_directory}

If invoking the script directly fails, run it as a module:

python -m black {source_file_or_directory}

Files are rewritten in place. For users who want to avoid installing Python, standalone executables built with PyInstaller are available from the latest GitHub release.

Configuration

Project defaults can be read from pyproject.toml, which is mainly useful for setting custom --include and --exclude / --force-exclude / --extend-exclude patterns. Black is designed to work without configuration; the defaults already match many other Black-formatted projects. See the usage and configuration documentation for file-based configuration details.

Constraints and compatibility

Black requires Python 3.11 or newer at runtime. It deliberately limits style options, and its behavior is documented in detail, including intended pragmatism around edge cases and the AST equivalence check; read the current style documentation before treating an output as a bug. The project is MIT licensed. Adding the badge to a project's README follows the provided Markdown or reST snippets.

HotRepo's take

In the daily Python ranking for 2026-11-06, Black recorded 12 new stars and ranked 17th in that language list, on a repository of 42,118 stars and 2,965 forks. That is a single snapshot, so it shows continued visibility in the Python list rather than a trend. For a formatter released in 2018 with a deliberately narrow option surface, the relevant signal is that it still appears on the Python daily list while teams continue to adopt its style through project configuration.