black

Black is an uncompromising Python code formatter — automatically formatting code to follow a single, deterministic style that eliminates formatting debates and ensures consistency across entire codebases, letting developers focus on logic instead of style.

What Is Black?

• Definition: Opinionated Python code formatter with zero configuration.
• Philosophy: "Any color you like, as long as it's black" — one style for all.
• Guarantee: Same input always produces same output (deterministic).
• Safety: Only changes formatting, never code behavior or AST.

Why Black Matters

• End Debates: No more arguments about spaces, quotes, or line breaks.
• Save Time: Automatic formatting vs manual style enforcement.
• Consistency: Entire codebase looks like one person wrote it.
• Faster Reviews: Focus on logic, not formatting nitpicks.
• Onboarding: New developers instantly match team style.

Key Features

Automatic Formatting:

# Before Black
def my_function(x,y,z):
    return x+y+z

# After Black
def my_function(x, y, z):
    return x + y + z

Style Choices:
- Line Length: 88 characters (10% more than 80, fits GitHub).
- Quotes: Double quotes preferred (except to avoid escaping).
- Trailing Commas: Added for multi-line structures.
- Whitespace: Consistent spacing around operators.

Quick Start

# Install
pip install black

# Format a file
black myfile.py

# Format entire directory
black src/

# Check without modifying (CI/CD)
black --check src/

# Show diff
black --diff myfile.py

Configuration

# pyproject.toml
[tool.black]
line-length = 88
target-version = ['py38', 'py39', 'py310']
include = '\.pyi?$'
extend-exclude = '/(migrations|venv)/'

Integration

VS Code:

{
    "python.formatting.provider": "black",
    "editor.formatOnSave": true
}

Pre-commit Hook:

repos:
  - repo: https://github.com/psf/black
    rev: 23.12.0
    hooks:
      - id: black

GitHub Actions:

- name: Check code formatting
  run: |
    pip install black
    black --check .

Magic Trailing Comma

Control line breaking behavior:

# Without trailing comma (stays on one line if fits)
short_list = [1, 2, 3]

# With trailing comma (forces multi-line)
long_list = [
    1,
    2,
    3,
]

Comparison

vs autopep8: Black is opinionated vs just fixing PEP 8 violations.
vs YAPF: Black has zero config vs highly configurable.
vs isort: Black formats all code vs just imports (use both together).

Best Practices

• Adopt Early: Introduce at project start to avoid massive reformatting.
• Format Entire Codebase: One-time commit with `black .`
• Enforce in CI/CD: Fail builds if not formatted with `black --check .`
• Use Pre-commit: Automatically format before commits.
• Combine with Linters: `black . && flake8 . && mypy .`

Adoption

Used by Django, Pandas, FastAPI, Pytest, and thousands of open-source projects.

Getting Started:
1. Install: `pip install black`
2. Format: `black .`
3. Add pre-commit hook
4. Configure editor for format-on-save
5. Add to CI/CD

Black eliminates bikeshedding about code style — it's fast, deterministic, and widely adopted, making consistency effortless so teams can focus on building great software.