“Any color you like.”
Black is the uncompromising Python code formatter. By using it, you agree to cede
control over minutiae of hand-formatting. In return, Black gives you speed,
determinism, and freedom from pycodestyle nagging about formatting. You will save time
and mental energy for more important matters.
Blackened code looks the same regardless of the project you're reading. Formatting
becomes transparent after a while and you can focus on the content instead.
Black makes code review faster by producing the smallest diffs possible.
Watch the PyCon 2019 talk to learn more.
Read the documentation on ReadTheDocs!
Installation and usage
Installation
Black can be installed by running pip install black. It requires Python 3.11+ to
run. If you want to format Jupyter Notebooks, install with
pip install "black[jupyter]".
If you want to run Black without installing Python, download one of the
PyInstaller-built standalone executables from the
latest GitHub release.
Usage
To get started right away with sensible defaults:
black {source_file_or_directory}
You can run Black as a package if running it as a script doesn't work:
python -m black {source_file_or_directory}
Further information can be found in our docs:
Black is already successfully used by many
projects, small and big. Black has a comprehensive test suite, with efficient parallel
tests, and our own auto formatting and parallel Continuous Integration runner. Now that
we have become stable, you should not expect large formatting changes in the future.
Stylistic changes will mostly be responses to bug reports and support for new Python
syntax. For more information please refer to
The Black Code Style.
Also, as a safety measure which slows down processing, Black will check that the
reformatted code still produces a valid AST that is effectively equivalent to the
original (see the
Pragmatism
section for details). If you're feeling confident, use --fast.
The Black code style
Black is a PEP 8 compliant opinionated formatter. Black reformats entire files in
place. Style configuration options are deliberately limited and rarely added. It doesn't
take previous formatting into account (see
Pragmatism
for exceptions).
Our documentation covers the current Black code style, but planned changes to it are
also documented. They're both worth taking a look at:
Changes to the Black code style are bound by the Stability Policy:
Please refer to this document before submitting an issue. What seems like a bug might be
intended behaviour.
Pragmatism
Early versions of Black used to be absolutist in some respects. They took after its
initial author. This was fine at the time as it made the implementation simpler and
there were not many users anyway. Not many edge cases were reported. As a mature tool,
Black does make some exceptions to rules it otherwise holds.
Please refer to this document before submitting an issue just like with the document
above. What seems like a bug might be intended behaviour.
Configuration
Black is able to read project-specific default values for its command line options
from a pyproject.toml file. This is especially useful for specifying custom
--include and --exclude/--force-exclude/--extend-exclude patterns for your
project.
You can find more details in our documentation:
And if you're looking for more general configuration documentation:
Pro-tip: If you're asking yourself "Do I need to configure anything?" the answer is
"No". Black is all about sensible defaults. Applying those defaults will have your
code in compliance with many other Black formatted projects.
Used by
The following notable open-source projects trust Black with enforcing a consistent
code style: pytest, tox, Pyramid, Django, Django Channels, Hypothesis, attrs,
SQLAlchemy, Poetry, PyPA applications (Warehouse, Bandersnatch, Pipenv, virtualenv),
pandas, Pillow, Twisted, LocalStack, every Datadog Agent Integration, Home Assistant,
Zulip, Kedro, OpenOA, FLORIS, ORBIT, WOMBAT, and many more.
The following organizations use Black: Dropbox, KeepTruckin, Lyft, Mozilla, Quora,
Duolingo, QuantumBlack, Tesla, Archer Aviation.
Are we missing anyone? Let us know.
Testimonials
Mike Bayer, creator of SQLAlchemy:
This is the beginning of the README. Read the rest at the original. Read the full README ↗
