Black

Black is an opinionated code formatter for Python that formats code to a consistent style with minimal configuration.

Installation and Setup

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

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?$'
extend-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 .

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: