CheatPress

Black Python formatter

Version 26.10.1 · source

Black, Postcard, light preview Light · Postcard 102 × 152 mm · PDF Black, Postcard, dark preview Dark · Postcard 102 × 152 mm · PDF Black, Postcard, ink saver preview Ink saver · Postcard 102 × 152 mm · PDF
Black, A5, light preview Light · A5 148 × 210 mm · PDF Black, A5, dark preview Dark · A5 148 × 210 mm · PDF Black, A5, ink saver preview Ink saver · A5 148 × 210 mm · PDF
Black, A4, light preview Light · A4 210 × 297 mm · PDF Black, A4, dark preview Dark · A4 210 × 297 mm · PDF Black, A4, ink saver preview Ink saver · A4 210 × 297 mm · PDF
Black, A4 landscape, light preview Light · A4 landscape 297 × 210 mm · PDF Black, A4 landscape, dark preview Dark · A4 landscape 297 × 210 mm · PDF Black, A4 landscape, ink saver preview Ink saver · A4 landscape 297 × 210 mm · PDF
Black, A3, light preview Light · A3 297 × 420 mm · PDF Black, A3, dark preview Dark · A3 297 × 420 mm · PDF Black, A3, ink saver preview Ink saver · A3 297 × 420 mm · PDF
Black, A3 landscape, light preview Light · A3 landscape 420 × 297 mm · PDF Black, A3 landscape, dark preview Dark · A3 landscape 420 × 297 mm · PDF Black, A3 landscape, ink saver preview Ink saver · A3 landscape 420 × 297 mm · PDF
Black, Letter, light preview Light · Letter 8.5 × 11 in · PDF Black, Letter, dark preview Dark · Letter 8.5 × 11 in · PDF Black, Letter, ink saver preview Ink saver · Letter 8.5 × 11 in · PDF
Black, Tabloid, light preview Light · Tabloid 11 × 17 in · PDF Black, Tabloid, dark preview Dark · Tabloid 11 × 17 in · PDF Black, Tabloid, ink saver preview Ink saver · Tabloid 11 × 17 in · PDF

Start here

black .
Format everything here
black <file.py>
Format one file
black --check .
Verify, change nothing
black --diff .
Preview the changes
black -l <n> .
Set line length
black -
Format stdin to stdout
black --version
Which version?
black -v .
Show skipped files

Concepts

  1. Source files .py .pyi .ipynb
  2. Black config + CLI flags
  3. Equivalence check AST must match
  4. Formatted files exit 0 / 1 / 123

Run

black .
Format all files under the current dir
black <file.py> <dir>
Format given files and folders
black --check .
Exit 1 if anything would change
black --diff .
Print the changes, write nothing
black --check --diff .
Show what a CI failure is about
black --diff --color .
Colored diff
black -q .
Only print errors
black -v .
Report ignored and unchanged files
black --version
Print the installed version
black -W <n> .
Number of parallel workers

Style options

black -l <n> .
Maximum line length (default 88)
black -t <py311> .
Target Python version (repeatable)
Inferred from requires-python in pyproject.toml, else detected per file.
black -S .
Keep string quotes as they are
black -C .
Ignore magic trailing commas
black --pyi <file>
Treat input as a typing stub
black --ipynb <file>
Treat input as a Jupyter notebook
black -x <file>
Skip the first line of the source
black --preview .
Try upcoming style changes
No stability guarantee between releases.
black --unstable .
Preview plus features with known issues

Files and stdin

black -
Read stdin, write formatted code to stdout
black -c "<code>"
Format a code string
black --stdin-filename <path> -
Name stdin so excludes apply
black --extend-exclude '<regex>' .
Skip more paths, keep defaults
Regex, not glob. A leading / anchors at the project root.
black --exclude '<regex>' .
Replace the default exclusions
black --force-exclude '<regex>' .
Exclude even explicitly passed files
black --include '<regex>' .
Which files to pick up (default py, pyi, ipynb)
black --line-ranges <1-20> <file>
Format only these lines (repeatable)
Single file only; also turns off the safe check.

Config

[tool.black]
Settings table in pyproject.toml
black --config <file> .
Use exactly this config file
black --required-version <26> .
Fail if Black's version differs
black --no-cache .
Ignore the per-user cache
black --cache-dir <dir> .
Cache location
black --fast .
Skip the AST equivalence check
BLACK_CACHE_DIR / BLACK_NUM_WORKERS
Environment overrides
Common pyproject keys
Key Same as
line-length -l
target-version -t (a list)
skip-string-normalization -S
extend-exclude --extend-exclude
required-version --required-version

Ignoring code

# fmt: skip
Leave this line alone
# fmt: off
Start an unformatted region
# fmt: on
End the region
# fmt: skip # noqa
Combine with other pragmas

Exit codes

Code Meaning
0 Done, or nothing to change with --check
1 --check: files would be reformatted
123 Internal error

Recipes

pyproject.toml
[tool.black]line-length = 100target-version = ['py311']extend-exclude = '''/(\.tox|migrations)/'''
CI gate
black --check --diff .
Format only changed files
git diff --name-only --diff-filter=d -- '*.py' | xargs black
Pre-commit hook
# .pre-commit-config.yamlrepos:  - repo: https://github.com/psf/black-pre-commit-mirror    rev: 26.10.1    hooks:      - id: black