Installation and usage¶
Installation¶
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.
Command line options¶
Black doesn’t provide many options. You can list them by running
black --help
:
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
--check
was used).
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 formatter becomes stable, you should expect some formatting to change in the future. That being said, no drastic stylistic changes are planned, mostly responses to bug reports.
Also, as a temporary safety measure, Black will check that the
reformatted code still produces a valid AST that is equivalent to the
original. This slows it down. If you’re feeling confident, use
--fast
.