Black is an uncompromising Python code formatter. Its core philosophy is that all code should be formatted to a single, consistent style, eliminating all stylistic debates from code reviews and team discussions. By strictly enforcing its rules, Black ensures that a codebase’s style remains uniform regardless of who writes the code, which dramatically improves readability and reduces cognitive load when switching between files or projects. It is not a linter; it does not check for logical errors or PEP 8 violations. Instead, it is a formatter that takes your code and rewrites it to conform to its style guide, which is itself a strict subset of PEP 8.

Core Formatting Philosophy and Rules

Black’s style is intentionally limited in its configurability. The most famous option is line length, which defaults to 88 characters (a nod to PEP 8’s suggested 79-character limit, but allowing 10% more). Other key formatting decisions include:

  • Strings: Prefers double quotes (")

  • Trailing Commas: Enforces trailing commas in comma-separated literals that are split across multiple lines. This leads to cleaner git diffs, as adding a new item only changes one line instead of two.

  • Line Breaks: Uses a deterministic algorithm to decide when to break lines, ensuring similar constructs are formatted similarly.

  • Parens: Avoids unnecessary parentheses.

# Code before Black (inconsistent quotes, no trailing comma, messy line breaks)
my_dict = {'key1': 'value1','key2': [1,2,3,
    4,5], 'key3': "value3"}

# Code after running `black` (consistent quotes, trailing comma, clean breaks)
my_dict = {
    "key1": "value1",
    "key2": [1, 2, 3, 4, 5],
    "key3": "value3",
}

Installation and Basic Usage

Black is installed via pip and can be run from the command line against a specific file, a directory, or as a pre-commit hook.

# Install Black
pip install black

# Format a single file
black my_script.py

# Format all Python files in a directory recursively
black ./project_directory/

# Check which files would be changed without formatting them (exit code 1 if changes needed)
black --check ./project_directory/

# Display a diff of the changes that would be made
black --diff my_script.py

Integration into Development Workflows

The true power of Black is realized when it’s integrated directly into a developer’s workflow, making formatting automatic and effortless.

1. Pre-commit Hooks: The most effective method is to use a tool like pre-commit. Once configured, Black will automatically format your code every time you try to create a git commit, ensuring no poorly formatted code ever enters the repository.

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/psf/black-pre-commit
    rev: 23.11.0 # Use the latest tag!
    hooks:
      - id: black
        # It is recommended to specify the language version
        args: [--target-version, py311]

2. Editor/IDE Integration: Nearly all modern code editors (VS Code, PyCharm, Sublime Text, Vim, etc.) have plugins that can format a file with Black on save. This provides immediate feedback and ensures you are always working with clean code.

Configuration and pyproject.toml

While “uncompromising,” Black does offer a handful of configuration options to accommodate different project needs. These are specified in a pyproject.toml file at the root of your project.

# pyproject.toml
[tool.black]
# The only commonly changed option: line-length
line-length = 100
# Target Python versions for formatting
target-version = ["py39"]
# Include files matching this pattern
include = '\.pyi?$'
# Exclude files and directories
extend-exclude = '''
/(
  |\.eggs
  |\.git
  |\.hg
  |\.mypy_cache
  |\.nox
  |\.tox
  |\.venv
  |venv
  |_build
  |buck-out
  |build
  |dist
)/
'''

Common Pitfalls and Edge Cases

  1. # fmt: off / # fmt: on: Sometimes, manually formatted code (e.g., a complex matrix of data) is more readable than Black’s output. You can disable formatting for a specific block by wrapping it in special comments.

    # fmt: off
# This entire section will be ignored by Black
poorly_formatted_list = [  1, 2,
  3, 4,  "five", "six"  ]
# fmt: on

    Use this sparingly, as it creates exceptions to the project’s consistency.

  2. String Concatenation: Black can sometimes reformat string concatenation in ways that are technically correct but may look surprising. It generally prefers to break long strings using implicit concatenation (Python’s feature where adjacent string literals are joined).

    # Before Black
long_string = "This is a very long string that will definitely exceed the line length limit and must be broken up."

# After Black (uses implicit concatenation)
long_string = (
    "This is a very long string that will definitely exceed the line length limit and"
    " must be broken up."
)

  3. Magic Trailing Comma: The “magic” trailing comma is a key feature. A trailing comma in a collection signals to Black to always format that collection with one element per line, even if it would otherwise fit on a single line. This is invaluable for diffs.

    # Without a trailing comma, Black will format it on one line.
short_list = [1, 2, 3]

# WITH a trailing comma, Black will format it vertically.
short_list = [
    1,
    2,
    3,
]