Black — The Uncompromising Python Code Formatter

Introduction

Black is an opinionated Python code formatter that rewrites your files in place to produce consistently styled code. It removes all style debates from code review by enforcing a single deterministic format, letting teams focus on logic instead of aesthetics.

What Black Does

• Reformats entire Python files in place to one canonical style
• Supports targeting specific Python versions (3.8 through 3.13+)
• Integrates with editors, pre-commit hooks, and CI pipelines
• Provides a --check mode that exits non-zero if files would change
• Handles magic trailing commas to control collection formatting

Architecture Overview

Black parses Python source into a concrete syntax tree using a fork of lib2to3, then rebuilds output line by line. It tries to fit expressions onto single lines, and when they exceed the configured line length (default 88), it splits them using a deterministic algorithm. The formatter is idempotent: running Black on already-formatted code produces identical output.

Self-Hosting & Configuration

• Install via pip, conda, or pipx for isolated CLI usage
• Configure in pyproject.toml under [tool.black] (line-length, target-version, etc.)
• Add to pre-commit with the official psf/black hook
• Run in CI with black --check --diff to catch unformatted code
• Exclude files or directories using extend-exclude in config

Key Features

• Zero configuration required for most projects
• Deterministic output ensures the same input always gives the same result
• Fast incremental formatting that caches file state
• Jupyter Notebook support via black[jupyter] extra
• Stable style guarantees within major versions to avoid noisy diffs

Comparison with Similar Tools

• autopep8 — fixes PEP 8 violations minimally; Black rewrites aggressively for full consistency
• YAPF — configurable with many knobs; Black deliberately removes configuration choices
• Ruff Formatter — Rust-based and faster; compatible with Black's style but still maturing
• isort — only sorts imports; Black focuses on code formatting and pairs well with isort
• Prettier — similar philosophy for JS/TS; Black applies the same opinionated approach to Python

FAQ

Q: Does Black break my code? A: Black only changes formatting, never semantics. It parses and re-emits valid Python, so behavior stays identical.

Q: Can I customize the line length? A: Yes. Set line-length in pyproject.toml or pass --line-length on the command line. The default is 88 characters.

Q: How does Black handle strings? A: By default Black normalizes string quotes to double quotes. Use --skip-string-normalization to keep original quoting.

Q: Is Black compatible with Ruff? A: Yes. Ruff's formatter is designed to produce output compatible with Black, and Ruff's linter can replace Flake8 alongside Black.

Sources

• https://github.com/psf/black
• https://black.readthedocs.io/en/stable/