black

Auto-format a file or entire directory

$ black [path/to/file_or_directory]

$ black [[-c|--code]] "[code]"

$ black --check [path/to/file_or_directory]

$ black --diff [path/to/file_or_directory]

$ black [[-q|--quiet]] [path/to/file_or_directory]

$ black [[-S|--skip-string-normalization]] [path/to/file_or_directory]

black [OPTIONS] [SRC] ...

-h, --help
    Show help message and exit

--version
    Show program's version number and exit

-c, --config PATH
    Path to configuration file (pyproject.toml by default)

-l, --line-length N
    Set line length for formatting (default: 88)

--color / --no-color
    Show colored / not-colored diff output

--skip-string-normalization
    Don't normalize string quotes or prefixes

--skip-magic-trailing-comma
    Don't add trailing commas where required

--include TEXT
    Include files matching regex (default: '\.pyi?$')

--exclude TEXT
    Exclude files matching regex (default: '/(\.git|\.hg|\.mypy_cache|\.tox|\.venv|_build|buck-out|build|dist)/')

--pyi
    Format all .pyi files

--python-version VER
    Python version for syntax checking (e.g., py38)

--target-version TARGET_VERSION
    Target Python version(s) for formatting

--required-version REQ_VERSION
    Require Black version for pyproject.toml

--check
    Exit with error if files need formatting (no write)

--diff
    Print diffs of changes instead of writing files

--fast / --safe
    Fast mode (AST only) / Safe mode (parse + AST)

--quiet
    Suppress non-error output

--verbose
    Verbose output

--workers N
    Parallel worker count (default: CPU count * 4)

--worker-timeout N
    Worker timeout in seconds (default: 120)

Black is a Python code formatter that automatically reformats code to conform to a strict subset of PEP 8 style guide. It is designed to be opinionated, removing the need for configuration in most cases, ensuring consistent formatting across projects. Black reformats entire files or directories in place, handling spacing, line lengths, imports, and more.

Usage involves installing via pip (pip install black) and running it on Python files or directories. It processes .py files by default but supports .pyi stubs. Black prioritizes readability, using double quotes, single spaces, and a default line length of 88 characters.

Key benefits include eliminating style debates in teams, reducing git diff noise from formatting changes, and integrating seamlessly with editors like VS Code or pre-commit hooks. While powerful, its "one true way" approach may require adjustment periods for developers accustomed to custom styles.

Black is highly opinionated with minimal configuration; it may reformat code in ways that alter behavior if preview features are unstable. Always use --check or --diff first in CI. Not suitable for non-Python files.

0: Success
1: Files would be reformatted (--check)
123: Files need sorting or other issues

Primarily via pyproject.toml: [tool.black] line-length = 88
include = '\.pyi?$'

Supports VS Code, Vim, Emacs via plugins; use black-formatter LSP for IDEs.

Created by Łukasz Langa, first released on PyPI in December 2018 (version 18.9b0). Rapidly adopted due to its simplicity and PEP 8 compliance. Now at version 24.x, supports Python 3.8+, with ongoing development focusing on performance and preview style features.

python(1), pip(1), pre-commit(1)