---
_Contents:_ **[Installation and usage](#installation-and-usage)** |
-**[Code style](#the-black-code-style)** | **[Pragmatism](#pragmatism)**
+**[Code style](#the-black-code-style)** | **[Pragmatism](#pragmatism)** |
**[pyproject.toml](#pyprojecttoml)** | **[Editor integration](#editor-integration)** |
**[blackd](#blackd)** | **[Version control integration](#version-control-integration)**
| **[Ignoring unmodified files](#ignoring-unmodified-files)** | **[Used by](#used-by)**
_Black_ doesn't provide many options. You can list them by running `black --help`:
```text
-black [OPTIONS] [SRC]...
+Usage: black [OPTIONS] [SRC]...
+
+ The uncompromising code formatter.
Options:
-c, --code TEXT Format the code passed in as a string.
-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
+ 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.
+
+ --color / --no-color Show colored diff. Only applies when
+ `--diff` is given.
+
--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
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
directories on all platforms (Windows, too).
Exclusions are calculated first, inclusions
later. [default: /(\.eggs|\.git|\.hg|\.mypy
- _cache|\.nox|\.tox|\.venv|_build|buck-
+ _cache|\.nox|\.tox|\.venv|\.svn|_build|buck-
out|build|dist)/]
+
+ --force-exclude TEXT Like --exclude, but files and directories
+ matching this regex will be excluded even
+ when they are passed explicitly as arguments
+
-q, --quiet Don't emit non-error messages to stderr.
- Errors are still emitted, silence those with
+ 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.
+ --config FILE Read configuration from PATH.
-h, --help Show this message and exit.
```
- it only outputs messages to users on standard error;
- exits with code 0 unless an internal error occurred (or `--check` was used).
+### Using _Black_ with other tools
+
+While _Black_ enforces formatting that conforms to PEP 8, other tools may raise warnings
+about _Black_'s changes or will overwrite _Black_'s changes. A good example of this is
+[isort](https://pypi.org/p/isort). Since _Black_ is barely configurable, these tools
+should be configured to neither warn about nor overwrite _Black_'s changes.
+
+Actual details on _Black_ compatible configurations for various tools can be found in
+[compatible_configs](./docs/compatible_configs.md).
+
### NOTE: This is a beta product
_Black_ is already [successfully used](#used-by) by many projects, small and big. It
_Black_ does make some exceptions to rules it otherwise holds. This section documents
what those exceptions are and why this is the case.
-### The magic trailling comma
+### The magic trailing comma
_Black_ in general does not take existing formatting into account.
### Emacs
-Use [proofit404/blacken](https://github.com/proofit404/blacken) or
-[Elpy](https://github.com/jorgenschaefer/elpy).
+Options include the following:
+
+- [purcell/reformatter.el](https://github.com/purcell/reformatter.el)
+- [proofit404/blacken](https://github.com/proofit404/blacken)
+- [Elpy](https://github.com/jorgenschaefer/elpy).
### PyCharm/IntelliJ IDEA
%LocalAppData%\Programs\Python\Python36-32\Scripts\black.exe # possible location
```
+Note that if you are using a virtual environment detected by PyCharm, this is an
+unneeded step. In this case the path to `black` is `$PyInterpreterDirectory$/black`.
+
3. Open External tools in PyCharm/IntelliJ IDEA
On macOS:
To install with [vim-plug](https://github.com/junegunn/vim-plug):
```
-Plug 'psf/black'
+Plug 'psf/black', { 'branch': 'stable' }
```
or with [Vundle](https://github.com/VundleVim/Vundle.vim):
Plugin 'psf/black'
```
+and execute the following in a terminal:
+
+```console
+$ cd ~/.vim/bundle/black
+$ git checkout origin/stable -b stable
+```
+
or you can copy the plugin from
-[plugin/black.vim](https://github.com/psf/black/tree/master/plugin/black.vim).
+[plugin/black.vim](https://github.com/psf/black/blob/stable/plugin/black.vim).
```
mkdir -p ~/.vim/pack/python/start/black/plugin
Poetry, PyPA applications (Warehouse, Pipenv, virtualenv), pandas, Pillow, every Datadog
Agent Integration, Home Assistant.
+The following organizations use _Black_: Dropbox.
+
Are we missing anyone? Let us know.
## Testimonials
Multiple contributions by:
-- [Abdur-Rahmaan Janhangeer](mailto:cryptolabour@gmail.com)
+- [Abdur-Rahmaan Janhangeer](mailto:arj.python@gmail.com)
- [Adam Johnson](mailto:me@adamj.eu)
- [Alexander Huynh](mailto:github@grande.coffee)
- [Andrew Thorp](mailto:andrew.thorp.dev@gmail.com)
projects / etc / vim.git / blobdiff