black
Format Python code automatically
TLDR
Auto-format a file or entire directory
Format the code passed in as a string
Show whether a file or a directory would have changes made to them if they were to be formatted
Show changes that would be made to a file or a directory without performing them (dry-run)
Auto-format a file or directory, emitting exclusively error messages to stderr
Auto-format a file or directory without replacing single quotes with double quotes (adoption helper, avoid using this for new projects)
SYNOPSIS
black [OPTIONS] [PATH ...]
PARAMETERS
--line-length INTEGER
The preferred line length. Defaults to 88.
--target-version PYTHON_VERSION
Python versions that should be supported by Black's output. The command can support multiple versions at once. Example: py37,py38,py39.
--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.
--diff
Instead of writing to the file, print a diff to standard output.
--include PATTERN
A regular expression that matches files and directories that should be included.
May be specified multiple times.
--exclude PATTERN
A regular expression that matches files and directories that should be excluded.
May be specified multiple times.
--extend-exclude PATTERN
Like --exclude, but adds to the default exclusion regex.
--force-exclude PATTERN
Like --exclude, but excludes even when --include is used.
--fast
Skip sanity checks.
--verbose
Show more output.
--quiet
Don't emit non-error messages to stderr. Errors are still emitted; silence those with 2>/dev/null.
--version
Show the version and exit.
PATH
Files and directories to format. If no path is specified, Black will attempt to discover and format all Python files in the current directory.
DESCRIPTION
The `black` command, *hypothetically*, automatically formats Python code to adhere to the Black code style. It prioritizes consistency and readability by enforcing a single, uncompromising code style. `black` automates the formatting process, saving developers time and ensuring code consistency across projects. It modifies files in-place by default, which significantly speeds up development workflow. The command is designed to be opinionated, avoiding configuration options that would allow developers to deviate from the standard style.
Beyond formatting, `black` also aims to minimize diffs by prioritizing horizontal alignment for multiline statements and reformatting code to reduce semantic changes.
CAVEATS
Modifies files in-place unless `--check` or `--diff` is used. Requires Python 3.6+ to run. Relies on stable AST transformations, which can sometimes lead to unexpected formatting changes in edge cases.
EXIT STATUS
The `black` command returns 0 if no changes are needed or if formatting was successful. It returns 1 if changes were needed and the `--check` flag was used. Any other non-zero exit code indicates an error.
EXAMPLES
Format a single file: black my_file.py
Format all Python files in the current directory: black .
Check if a file needs formatting without modifying it: black --check my_file.py
Show the diff of changes that would be made: black --diff my_file.py
HISTORY
The `black` command was conceived with the aim of providing a completely opinionated code formatter, eliminating debates about code style. First released, it quickly gained popularity within the Python community due to its ease of use and its consistent formatting results.