Black is an uncompromising Python code formatter maintained by the Python Software Foundation that automatically reformats entire Python files according to a strict, opinionated style. The tool eliminates debates over formatting minutiae by enforcing a single consistent style across codebases, making code review faster through minimal diffs and allowing developers to focus on code content rather than formatting decisions. Black requires Python 3.10 or higher to run and can be installed via pip, with optional support for formatting Jupyter Notebooks through an additional dependency.
The formatter implements a PEP 8 compliant style with deliberately limited configuration options, reflecting its philosophy that sensible defaults should suffice for most projects. Black reads project-specific settings from pyproject.toml files for custom include and exclude patterns, but the tool is designed to work effectively without any configuration. As a safety measure, Black verifies that reformatted code produces a valid Abstract Syntax Tree equivalent to the original, though users can bypass this check with a fast mode flag. The tool has evolved from an absolutist approach in early versions to incorporate pragmatic exceptions for edge cases as it matured and gained widespread adoption.
Black has achieved significant adoption across the Python community, with notable open-source projects including pytest, Django, SQLAlchemy, pandas, Pillow, and Home Assistant relying on it for code style enforcement. Major organizations including Dropbox, Lyft, Mozilla, and Tesla use Black across their codebases. The tool's impact on developer productivity is reflected in testimonials from prominent Python developers, with SQLAlchemy creator Mike Bayer describing it as providing the largest productivity increase of any tool in his programming career.
The repository is written in Python and published under an MIT license. Black maintains comprehensive test coverage with efficient parallel testing and continuous integration infrastructure. The project welcomes contributions through its documented contribution guidelines and maintains an active Discord community for developer discussion. The codebase has grown to include extensive documentation on ReadTheDocs covering usage, configuration, the Black code style specification, stability policies, and pragmatic exceptions to formatting rules. Black's stability policy ensures that stylistic changes are primarily responses to bug reports and support for new Python syntax rather than arbitrary reformatting changes, providing confidence to projects that have adopted the tool.
