README

The Uncompromising Code Formatter













 “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:

sh
black {source_file_or_directory}


You can run _Black_ as a package if running it as a script doesn't work:

sh
python -m black {source_file_or_directory}


Further information can be found in our docs:

- Usage and Configuration

_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:

- The _Black_ Code Style: Current style
- The _Black_ Code Style: Future style

Changes to the _Black_ code style are bound by the Stability Policy:

- The _Black_ Code Style: 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

Top issues

Latest release

Highlights

This release fixes a security issue in Black's bundled GitHub Action. Repositories that
use the action are encouraged to update to the latest version of Black immediately. This
update is received automatically when using psf/black@stable, and is independent of
the version of Black installed by the action.

When the GitHub Action reads version specifiers from tool.black.required-version, it
now only accepts released versions of Black, as it already did for black requirements
in dependency lists. Other values, such as URL references, are now rejected. This issue
has been registered a