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
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.
Try it out now using the Black Playground.
Contents: Installation and usage | Code style | pyproject.toml | Editor integration | blackd | Version control integration | Ignoring unmodified files | Testimonials | Show your style | Contributing | Change Log | Authors
Installation and usage
Black can be installed by running
pip install black. It requires
Python 3.6.0+ to run but you can reformat Python 2 code with it, too.
To get started right away with sensible defaults:
Command line options
Black doesn't provide many options. You can list them by running
black [OPTIONS] [SRC]... Options: -l, --line-length INTEGER How many characters per line to allow. [default: 88] -t, --target-version [py27|py33|py34|py35|py36|py37|py38] Python versions that should be supported by Black's output. [default: per-file auto- detection] --py36 Allow using Python 3.6-only syntax on all input files. This will put trailing commas in function signatures and calls also after *args and **kwargs. Deprecated; use --target-version instead. [default: per-file auto-detection] --pyi Format all input files like typing stubs regardless of file extension (useful when piping source on standard input). -S, --skip-string-normalization Don't normalize string quotes or prefixes. --check Don't write the files back, just return the status. Return code 0 means nothing would change. Return code 1 means some files would be reformatted. Return code 123 means there was an internal error. --diff Don't write the files back, just output a diff for each file on stdout. --fast / --safe If --fast given, skip temporary sanity checks. [default: --safe] --include TEXT A regular expression that matches files and directories that should be included on recursive searches. An empty value means all files are included regardless of the name. Use forward slashes for directories on all platforms (Windows, too). Exclusions are calculated first, inclusions later. [default: \.pyi?$] --exclude TEXT A regular expression that matches files and directories that should be excluded on recursive searches. An empty value means no paths are excluded. Use forward slashes for directories on all platforms (Windows, too). Exclusions are calculated first, inclusions later. [default: /(\.eggs|\.git|\.hg|\.mypy _cache|\.nox|\.tox|\.venv|_build|buck- out|build|dist)/] -q, --quiet Don't emit non-error messages to stderr. Errors are still emitted, silence those with 2>/dev/null. -v, --verbose Also emit messages to stderr about files that were not changed or were ignored due to --exclude=. --version Show the version and exit. --config PATH Read configuration from PATH. -h, --help Show this message and exit.
Black is a well-behaved Unix-style command-line tool:
- it does nothing if no sources are passed to it;
- it will read from standard input and write to standard output if
-is used as the filename;
- it only outputs messages to users on standard error;
- exits with code 0 unless an internal error occurred (or
NOTE: This is a beta product
Black is already successfully used by several projects, small and big. It also sports a decent test suite. However, it is still very new. Things will probably be wonky for a while. This is made explicit by the "Beta" trove classifier, as well as by the "b" in the version number. What this means for you is that until the f