Black

Installation and Setup

Install from the Python Package Index (PyPI) inside a virtual environment:

• Windows
• Linux + macOS

PS> py -m pip install black
PS> py -m black --version  # Verify the installation

$ python -m pip install black
$ python -m black --version  # Verify the installation

Configuration typically lives in pyproject.toml at the project root:

[tool.black]
line-length = 88
target-version = ["py313"]
include = "\\.pyi?$"
exclude = [
  "^build/",
  "^dist/",
  "^.venv/"
]

Key Features

• Formats code deterministically to reduce diffs and style debates.
• Favors a single, consistent style and exposes only a few toggles like line length and target versions.
• Reads configuration from pyproject.toml and respects include and exclude patterns.
• Supports parallel and incremental formatting for speed on large projects.
• Integrates with editors, pre-commit hooks, and continuous integration (CI) through standard exit codes.

Usage

Format a file or directory in place:

$ python -m black path/to/file.py
$ python -m black src/ tests/

Check formatting without writing changes:

$ python -m black --check .

Show a unified diff of proposed changes:

$ python -m black --diff path/to/file.py

Override the configured line length for a one-off run:

$ python -m black --line-length 100 .

Select a target Python version to guide formatting decisions:

$ python -m black --target-version py311 .

Related Resources

Tutorial

Python Code Quality: Best Practices and Tools

In this tutorial, you'll learn about code quality and the key factors that make Python code high-quality. You'll explore effective strategies, powerful tools, and best practices to elevate your code to the next level.

intermediate best-practices python tools

For additional information on related topics, take a look at the following resources:

• Python Code Quality: Best Practices and Tools (Quiz)