black

Project Overview

Black is one of the most popular Python code formatters, known as the uncompromising one: style options are deliberately few, and results are deterministic and consistent across projects. You cede control over formatting minutiae in return for speed, determinism, and freedom from style nagging. Blackened code looks the same in every project and produces minimal diffs for faster code review.

Leave formatting to Black and spend the energy on the code itself.

Key Features

• Auto formatting: reformats entire files so style is uniform without debate
• PEP 8 compliant: makes deterministic style decisions on top of PEP 8
• Minimal diffs: produces the smallest possible changes for focused review
• Safety check: verifies AST equivalence by default so semantics never change
• pyproject config: supports include and exclude options via pyproject.toml
• Notebook support: install black[jupyter] to format Jupyter Notebooks
• Pre-commit hooks: commonly paired with pre-commit for automatic formatting

Target Audience

• Python developers
• Open-source maintainers
• Teams ending style debates
• Tech leads who value review efficiency
• CI pipeline maintainers

Quick Start

1. Install Black

pip install black

2. Format a file or directory

black {source_file_or_directory}

3. On machines without Python, download a standalone executable from GitHub Releases

4. Optionally configure include and exclude patterns in pyproject.toml

Core Advantages

• Zero style debates: few options mean teams stop spending time on style
• Deterministic: the same input always yields the same output
• Semantically safe: AST equivalence is verified so formatting never changes behavior
• Battle tested: used long-term by Django, SQLAlchemy, pandas, and many more

System Requirements

Notes

• Stable style: the project is stable and no longer makes large style changes
• Exceptions: some pragmatism exceptions exist; consult the docs before filing issues
• Speed tradeoff: the AST safety check slows processing slightly; use --fast if confident