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.

Usage

To get started right away with sensible defaults:

black {source_file_or_directory}

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   Where to wrap around.  [default: 88]
  --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.  [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. On Windows, use forward
                              slashes for directories.  [default: \.pyi?$]
  --exclude TEXT              A regular expression that matches files and
                              directories that should be excluded on
                              recursive searches. On Windows, use forward
                              slashes for directories.  [default:
                              build/|buck-out/|dist/|_build/|\.git/|\.hg/|
                              \.mypy_cache/|\.nox/|\.tox/|\.venv/]
  -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.
  --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.