[//]: # (NOTE: THIS FILE IS AUTOGENERATED FROM README.md)

# 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`:

```text
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``.


