_Black_ is a well-behaved Unix-style command-line tool:
-- it does nothing if no sources are passed to it;
+- it does nothing if it finds no sources to format;
- 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).
+- exits with code 0 unless an internal error occurred or a CLI option prompted it.
## Usage
### Command line options
-_Black_ has quite a few knobs these days, although _Black_ is opinionated so style
-configuration options are deliberately limited and rarely added. You can list them by
-running `black --help`.
+The CLI options of _Black_ can be displayed by running `black --help`. All options are
+also covered in more detail below.
-<details>
+While _Black_ has quite a few knobs these days, it is still opinionated so style options
+are deliberately limited and rarely added.
+
+Note that all command-line options listed above can also be configured using a
+`pyproject.toml` file (more on that below).
+
+#### `-c`, `--code`
-<summary>Help output</summary>
+Format the code passed in as a string.
+```console
+$ black --code "print ( 'hello, world' )"
+print("hello, world")
```
- Usage: black [OPTIONS] [SRC]...
- The uncompromising code formatter.
+#### `-l`, `--line-length`
- 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]
+How many characters per line to allow. The default is 88.
- -t, --target-version [py27|py33|py34|py35|py36|py37|py38|py39]
- Python versions that should be supported by
- Black's output. [default: per-file auto-
- detection]
+See also [the style documentation](labels/line-length).
- --pyi Format all input files like typing stubs
- regardless of file extension (useful when
- piping source on standard input).
+#### `-t`, `--target-version`
+
+Python versions that should be supported by Black's output. You can run `black --help`
+and look for the `--target-version` option to see the full list of supported versions.
+You should include all versions that your code supports. If you support Python 3.8
+through 3.11, you should write:
+
+```console
+$ black -t py38 -t py39 -t py310 -t py311
+```
- -S, --skip-string-normalization
- Don't normalize string quotes or prefixes.
- -C, --skip-magic-trailing-comma
- Don't use trailing commas as a reason to
- split lines.
+In a [configuration file](#configuration-via-a-file), you can write:
+
+```toml
+target-version = ["py38", "py39", "py310", "py311"]
+```
+
+_Black_ uses this option to decide what grammar to use to parse your code. In addition,
+it may use it to decide what style to use. For example, support for a trailing comma
+after `*args` in a function call was added in Python 3.5, so _Black_ will add this comma
+only if the target versions are all Python 3.5 or higher:
+
+```console
+$ black --line-length=10 --target-version=py35 -c 'f(a, *args)'
+f(
+ a,
+ *args,
+)
+$ black --line-length=10 --target-version=py34 -c 'f(a, *args)'
+f(
+ a,
+ *args
+)
+$ black --line-length=10 --target-version=py34 --target-version=py35 -c 'f(a, *args)'
+f(
+ a,
+ *args
+)
+```
- --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.
+#### `--pyi`
- --diff Don't write the files back, just output a
- diff for each file on stdout.
+Format all input files like typing stubs regardless of file extension. This is useful
+when piping source on standard input.
- --color / --no-color Show colored diff. Only applies when
- `--diff` is given.
+#### `--ipynb`
- --fast / --safe If --fast given, skip temporary sanity
- checks. [default: --safe]
+Format all input files like Jupyter Notebooks regardless of file extension. This is
+useful when piping source on standard input.
- --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?$]
+#### `--python-cell-magics`
- --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: /(\.direnv|\.eggs|\.git|\.
- hg|\.mypy_cache|\.nox|\.tox|\.venv|venv|\.svn|_bu
- ild|buck-out|build|dist)/]
+When processing Jupyter Notebooks, add the given magic to the list of known python-
+magics. Useful for formatting cells with custom python magics.
- --extend-exclude TEXT Like --exclude, but adds additional files
- and directories on top of the excluded
- ones (useful if you simply want to add to
- the default).
+#### `-S, --skip-string-normalization`
- --force-exclude TEXT Like --exclude, but files and directories
- matching this regex will be excluded even
- when they are passed explicitly as
- arguments.
+By default, _Black_ uses double quotes for all strings and normalizes string prefixes,
+as described in [the style documentation](labels/strings). If this option is given,
+strings are left unchanged instead.
+#### `-C, --skip-magic-trailing-comma`
- --stdin-filename TEXT The name of the file when passing it through
- stdin. Useful to make sure Black will
- respect --force-exclude option on some
- editors that rely on using stdin.
+By default, _Black_ uses existing trailing commas as an indication that short lines
+should be left separate, as described in
+[the style documentation](labels/magic-trailing-comma). If this option is given, the
+magic trailing comma is ignored.
- -q, --quiet Don't emit non-error messages to stderr.
- Errors are still emitted; silence those with
- 2>/dev/null.
+#### `--preview`
- -v, --verbose Also emit messages to stderr about files
- that were not changed or were ignored due to
- exclusion patterns.
+Enable potentially disruptive style changes that may be added to Black's main
+functionality in the next major release. Read more about
+[our preview style](labels/preview-style).
- --version Show the version and exit.
- --config FILE Read configuration from FILE path.
- -h, --help Show this message and exit.
+(labels/exit-code)=
+
+#### `--check`
+
+Passing `--check` will make _Black_ exit with:
+
+- code 0 if nothing would change;
+- code 1 if some files would be reformatted; or
+- code 123 if there was an internal error
+
+```console
+$ black test.py --check
+All done! ✨ 🍰 ✨
+1 file would be left unchanged.
+$ echo $?
+0
+
+$ black test.py --check
+would reformat test.py
+Oh no! 💥 💔 💥
+1 file would be reformatted.
+$ echo $?
+1
+
+$ black test.py --check
+error: cannot format test.py: INTERNAL ERROR: Black produced code that is not equivalent to the source. Please report a bug on https://github.com/psf/black/issues. This diff might be helpful: /tmp/blk_kjdr1oog.log
+Oh no! 💥 💔 💥
+1 file would fail to reformat.
+$ echo $?
+123
```
-</details>
+#### `--diff`
+
+Passing `--diff` will make _Black_ print out diffs that indicate what changes _Black_
+would've made. They are printed to stdout so capturing them is simple.
+
+If you'd like colored diffs, you can enable them with `--color`.
+
+```console
+$ black test.py --diff
+--- test.py 2021-03-08 22:23:40.848954+00:00
++++ test.py 2021-03-08 22:23:47.126319+00:00
+@@ -1 +1 @@
+-print ( 'hello, world' )
++print("hello, world")
+would reformat test.py
+All done! ✨ 🍰 ✨
+1 file would be reformatted.
+```
+
+#### `--color` / `--no-color`
+
+Show (or do not show) colored diff. Only applies when `--diff` is given.
+
+#### `--fast` / `--safe`
+
+By default, _Black_ performs [an AST safety check](labels/ast-changes) after formatting
+your code. The `--fast` flag turns off this check and the `--safe` flag explicitly
+enables it.
+
+#### `--required-version`
+
+Require a specific version of _Black_ to be running. This is useful for ensuring that
+all contributors to your project are using the same version, because different versions
+of _Black_ may format code a little differently. This option can be set in a
+configuration file for consistent results across environments.
+
+```console
+$ black --version
+black, 23.9.1 (compiled: yes)
+$ black --required-version 23.9.1 -c "format = 'this'"
+format = "this"
+$ black --required-version 31.5b2 -c "still = 'beta?!'"
+Oh no! 💥 💔 💥 The required version does not match the running version!
+```
+
+You can also pass just the major version:
+
+```console
+$ black --required-version 22 -c "format = 'this'"
+format = "this"
+$ black --required-version 31 -c "still = 'beta?!'"
+Oh no! 💥 💔 💥 The required version does not match the running version!
+```
+
+Because of our [stability policy](../the_black_code_style/index.md), this will guarantee
+stable formatting, but still allow you to take advantage of improvements that do not
+affect formatting.
+
+#### `--include`
+
+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.
+
+#### `--exclude`
+
+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.
+
+#### `--extend-exclude`
+
+Like `--exclude`, but adds additional files and directories on top of the excluded ones.
+Useful if you simply want to add to the default.
+
+#### `--force-exclude`
+
+Like `--exclude`, but files and directories matching this regex will be excluded even
+when they are passed explicitly as arguments. This is useful when invoking _Black_
+programmatically on changed files, such as in a pre-commit hook or editor plugin.
+
+#### `--stdin-filename`
+
+The name of the file when passing it through stdin. Useful to make sure Black will
+respect the `--force-exclude` option on some editors that rely on using stdin.
+
+#### `-W`, `--workers`
+
+When _Black_ formats multiple files, it may use a process pool to speed up formatting.
+This option controls the number of parallel workers. This can also be specified via the
+`BLACK_NUM_WORKERS` environment variable.
+
+#### `-q`, `--quiet`
+
+Passing `-q` / `--quiet` will cause _Black_ to stop emitting all non-critical output.
+Error messages will still be emitted (which can silenced by `2>/dev/null`).
+
+```console
+$ black src/ -q
+error: cannot format src/black_primer/cli.py: Cannot parse: 5:6: mport asyncio
+```
+
+#### `-v`, `--verbose`
+
+Passing `-v` / `--verbose` will cause _Black_ to also emit messages about files that
+were not changed or were ignored due to exclusion patterns. If _Black_ is using a
+configuration file, a blue message detailing which one it is using will be emitted.
+
+```console
+$ black src/ -v
+Using configuration from /tmp/pyproject.toml.
+src/blib2to3 ignored: matches the --extend-exclude regular expression
+src/_black_version.py wasn't modified on disk since last run.
+src/black/__main__.py wasn't modified on disk since last run.
+error: cannot format src/black_primer/cli.py: Cannot parse: 5:6: mport asyncio
+reformatted src/black_primer/lib.py
+reformatted src/blackd/__init__.py
+reformatted src/black/__init__.py
+Oh no! 💥 💔 💥
+3 files reformatted, 2 files left unchanged, 1 file failed to reformat
+```
+
+#### `--version`
+
+You can check the version of _Black_ you have installed using the `--version` flag.
+
+```console
+$ black --version
+black, 23.9.1
+```
+
+#### `--config`
+
+Read configuration options from a configuration file. See
+[below](#configuration-via-a-file) for more details on the configuration file.
+
+#### `-h`, `--help`
+
+Show available command-line options and exit.
+
+### Environment variable options
+
+_Black_ supports the following configuration via environment variables.
+
+#### `BLACK_CACHE_DIR`
+
+The directory where _Black_ should store its cache.
+
+#### `BLACK_NUM_WORKERS`
+
+The number of parallel workers _Black_ should use. The command line option `-W` /
+`--workers` takes precedence over this environment variable.
+
+### Code input alternatives
+
+_Black_ supports formatting code via stdin, with the result being printed to stdout.
+Just let _Black_ know with `-` as the path.
+
+```console
+$ echo "print ( 'hello, world' )" | black -
+print("hello, world")
+reformatted -
+All done! ✨ 🍰 ✨
+1 file reformatted.
+```
+
+**Tip:** if you need _Black_ to treat stdin input as a file passed directly via the CLI,
+use `--stdin-filename`. Useful to make sure _Black_ will respect the `--force-exclude`
+option on some editors that rely on using stdin.
+
+You can also pass code as a string using the `-c` / `--code` option.
+
+### Writeback and reporting
+
+By default _Black_ reformats the files given and/or found in place. Sometimes you need
+_Black_ to just tell you what it _would_ do without actually rewriting the Python files.
+
+There's two variations to this mode that are independently enabled by their respective
+flags:
+
+- `--check` (exit with code 1 if any file would be reformatted)
+- `--diff` (print a diff instead of reformatting files)
+
+Both variations can be enabled at once.
+
+### Output verbosity
+
+_Black_ in general tries to produce the right amount of output, balancing between
+usefulness and conciseness. By default, _Black_ emits files modified and error messages,
+plus a short summary.
+
+```console
+$ black src/
+error: cannot format src/black_primer/cli.py: Cannot parse: 5:6: mport asyncio
+reformatted src/black_primer/lib.py
+reformatted src/blackd/__init__.py
+reformatted src/black/__init__.py
+Oh no! 💥 💔 💥
+3 files reformatted, 2 files left unchanged, 1 file failed to reformat.
+```
+
+The `--quiet` and `--verbose` flags control output verbosity.
## Configuration via a file
[PEP 518](https://www.python.org/dev/peps/pep-0518/) defines `pyproject.toml` as a
configuration file to store build system requirements for Python projects. With the help
-of tools like [Poetry](https://python-poetry.org/) or
-[Flit](https://flit.readthedocs.io/en/latest/) it can fully replace the need for
-`setup.py` and `setup.cfg` files.
+of tools like [Poetry](https://python-poetry.org/),
+[Flit](https://flit.readthedocs.io/en/latest/), or
+[Hatch](https://hatch.pypa.io/latest/) it can fully replace the need for `setup.py` and
+`setup.cfg` files.
### Where _Black_ looks for the file
line-length = 88
target-version = ['py37']
include = '\.pyi?$'
+# 'extend-exclude' excludes files or directories in addition to the defaults
extend-exclude = '''
# A regex preceded with ^/ will apply only to files and directories
# in the root of the project.
-^/foo.py # exclude a file named foo.py in the root of the project (in addition to the defaults)
+(
+ ^/foo.py # exclude a file named foo.py in the root of the project
+ | .*_pb2.py # exclude autogenerated Protocol Buffer files anywhere in the project
+)
'''
```
## Next steps
-You've probably noted that not all of the options you can pass to _Black_ have been
-covered. Don't worry, the rest will be covered in a later section.
-
A good next step would be configuring auto-discovery so `black .` is all you need
instead of laborously listing every file or directory. You can get started by heading
over to [File collection and discovery](./file_collection_and_discovery.md).
projects / etc / vim.git / blobdiff