Repository files navigation

“Any color you like.”

Black is the uncompromising Python code formatter. By using it, you agree to cedecontrol over minutiae of hand-formatting. In return,Black gives you speed,determinism, and freedom frompycodestyle nagging about formatting. You will save timeand mental energy for more important matters.

Blackened code looks the same regardless of the project you're reading. Formattingbecomes transparent after a while and you can focus on the content instead.

Black makes code review faster by producing the smallest diffs possible.

Try it out now using theBlack Playground. Watch thePyCon 2019 talk to learn more.

Read the documentation on ReadTheDocs!

Black can be installed by runningpip install black. It requires Python 3.9+ to run.If you want to format Jupyter Notebooks, install withpip install "black[jupyter]".

If you can't wait for the latesthotness and want to install from GitHub, use:

pip install git+https://github.com/psf/black

To get started right away with sensible defaults:

black {source_file_or_directory}

You can runBlack 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:

• Usage and Configuration

Black is alreadysuccessfully used by manyprojects, small and big.Black has a comprehensive test suite, with efficient paralleltests, and our own auto formatting and parallel Continuous Integration runner. Now thatwe 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 Pythonsyntax. For more information please refer toThe Black Code Style.

Also, as a safety measure which slows down processing,Black will check that thereformatted code still produces a valid AST that is effectively equivalent to theoriginal (see thePragmatismsection for details). If you're feeling confident, use--fast.

Black is a PEP 8 compliant opinionated formatter.Black reformats entire files inplace. Style configuration options are deliberately limited and rarely added. It doesn'ttake previous formatting into account (seePragmatismfor exceptions).

Our documentation covers the currentBlack code style, but planned changes to it arealso documented. They're both worth taking a look at:

• TheBlack Code Style: Current style
• TheBlack Code Style: Future style

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

• TheBlack Code Style: Stability Policy

Please refer to this document before submitting an issue. What seems like a bug might beintended behaviour.

Early versions ofBlack used to be absolutist in some respects. They took after itsinitial author. This was fine at the time as it made the implementation simpler andthere 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.

• TheBlack code style: Pragmatism

Please refer to this document before submitting an issue just like with the documentabove. What seems like a bug might be intended behaviour.

Black is able to read project-specific default values for its command line optionsfrom apyproject.toml file. This is especially useful for specifying custom--include and--exclude/--force-exclude/--extend-exclude patterns for yourproject.

You can find more details in our documentation:

• The basics: Configuration via a file

And if you're looking for more general configuration documentation:

• Usage and Configuration

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 yourcode in compliance with many otherBlack formatted projects.

The following notable open-source projects trustBlack with enforcing a consistentcode 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 useBlack: Dropbox, KeepTruckin, Lyft, Mozilla,Quora, Duolingo, QuantumBlack, Tesla, Archer Aviation.

Are we missing anyone? Let us know.

Mike Bayer,author ofSQLAlchemy:

I can't think of any single tool in my entire programming career that has given me abigger productivity increase by its introduction. I can now do refactorings in about1% of the keystrokes that it would have taken me previously when we had no way forcode to format itself.

Dusty Phillips,writer:

Black is opinionated so you don't have to be.

Hynek Schlawack,creator ofattrs, core developer ofTwisted and CPython:

An auto-formatter that doesn't suck is all I want for Xmas!

Carl Meyer,Django core developer:

At least the name is good.

Kenneth Reitz, creator ofrequestsandpipenv:

This vastly improves the formatting of our code. Thanks a ton!

Use the badge in your project's README.md:

[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)

Using the badge in README.rst:

.. image:: https://img.shields.io/badge/code%20style-black-000000.svg    :target: https://github.com/psf/black

Looks like this:

MIT

Welcome! Happy to see you willing to make the project better. You can get started byreading this:

• Contributing: The basics

You can also take a look at the rest of the contributing docs or talk with thedevelopers:

• Contributing documentation
• Chat on Discord

The log has become rather long. It moved to its own file.

SeeCHANGES.

The author list is quite long nowadays, so it lives in its own file.

SeeAUTHORS.md

Everyone participating in theBlack project, and in particular in the issue tracker,pull requests, and social media activity, is expected to treat other people with respectand more generally to follow the guidelines articulated in thePython Community Code of Conduct.

At the same time, humor is encouraged. In fact, basic familiarity with Monty Python'sFlying Circus is expected. We are not savages.

And if youreally need to slap somebody, do it with a fish while dancing.