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] [path...]

--version
    Show program's version number and exit.

--diff
    Don't write files back, just print diffs to stdout. This is useful for reviewing changes before applying them.

--check
    Don't write files back, just return the status code. Useful for CI/CD pipelines to verify formatting compliance.

--line-length <INT>
    How many characters per line to allow. Default is 88. Black is opinionated, so this is one of the few configurable options.

--target-version <py{36,37,38,39,310,311,312}>
    Python versions that Black should target, primarily affecting quotes and trailing commas. Can be specified multiple times.

--include <TEXT>
    A regular expression that matches files and directories to include. Default is '(\.pyi?|\.ipynb)$'.

--exclude <TEXT>
    A regular expression that matches files and directories to exclude. Useful for ignoring generated code or specific parts of a project.

--quiet
    Don't emit non-error output to stderr. Suppresses progress messages.

--verbose
    Emit all non-error output to stderr. Provides more detailed information about files processed.

-h, --help
    Show the help message and exit.

black is a deterministic and opinionated Python code formatter. It's designed to provide a consistent code style across projects, reducing bikeshedding and cognitive load during development and code reviews. Unlike linters, black doesn't just suggest changes; it automatically reformats your code to adhere to a strict subset of PEP 8, along with its own uncompromising rules. This ensures that all code formatted by black looks the same, regardless of the original author's style.

It is a Python package, typically installed via pip, and executed from the command line. Its core philosophy is to remove manual formatting decisions, allowing developers to focus solely on the logic and functionality of their code. black is idempotent, meaning running it multiple times on the same code will produce the identical output.

black is intentionally opinionated and offers very limited configuration. This can be a limitation for teams that require highly specific formatting rules not aligned with Black's philosophy. It requires a Python interpreter to run, as it's not a native Linux binary. While generally safe, it's always recommended to use version control (e.g., Git) when applying black to an existing codebase, as it will overwrite files in place.

black can be configured via a pyproject.toml file in your project root. This file can specify options like line-length, target-version, and include/exclude patterns, allowing consistent settings across team members without needing to pass command-line arguments each time.

Most modern Python IDEs and text editors (e.g., VS Code, PyCharm, Sublime Text, Vim) offer seamless integration with black, allowing users to format code automatically on save or via a keyboard shortcut, further streamlining the development process.

black was created by Łukasz Langa and first publicly released in 2018. Its development was driven by the desire to eliminate the time spent on formatting decisions and to enforce a consistent, unchangeable style. It rapidly gained popularity within the Python community due to its uncompromising nature and the benefits of unified code style, quickly becoming a standard tool in many Python development workflows and CI/CD pipelines.

autopep8, isort, flake8, pylint, mypy