# Black — The Uncompromising Python Code Formatter

> Black formats Python code automatically so teams never argue about style again. It enforces one consistent style with zero configuration.

## Install

Save as a script file and run:

# Black — The Uncompromising Python Code Formatter

## Quick Use
```bash
pip install black
black my_script.py
black src/ --check
```

## Introduction
Black is an opinionated Python code formatter that rewrites your files in place to produce consistently styled code. It removes all style debates from code review by enforcing a single deterministic format, letting teams focus on logic instead of aesthetics.

## What Black Does
- Reformats entire Python files in place to one canonical style
- Supports targeting specific Python versions (3.8 through 3.13+)
- Integrates with editors, pre-commit hooks, and CI pipelines
- Provides a `--check` mode that exits non-zero if files would change
- Handles magic trailing commas to control collection formatting

## Architecture Overview
Black parses Python source into a concrete syntax tree using a fork of lib2to3, then rebuilds output line by line. It tries to fit expressions onto single lines, and when they exceed the configured line length (default 88), it splits them using a deterministic algorithm. The formatter is idempotent: running Black on already-formatted code produces identical output.

## Self-Hosting & Configuration
- Install via pip, conda, or pipx for isolated CLI usage
- Configure in `pyproject.toml` under `[tool.black]` (line-length, target-version, etc.)
- Add to pre-commit with the official `psf/black` hook
- Run in CI with `black --check --diff` to catch unformatted code
- Exclude files or directories using `extend-exclude` in config

## Key Features
- Zero configuration required for most projects
- Deterministic output ensures the same input always gives the same result
- Fast incremental formatting that caches file state
- Jupyter Notebook support via `black[jupyter]` extra
- Stable style guarantees within major versions to avoid noisy diffs

## Comparison with Similar Tools
- **autopep8** — fixes PEP 8 violations minimally; Black rewrites aggressively for full consistency
- **YAPF** — configurable with many knobs; Black deliberately removes configuration choices
- **Ruff Formatter** — Rust-based and faster; compatible with Black's style but still maturing
- **isort** — only sorts imports; Black focuses on code formatting and pairs well with isort
- **Prettier** — similar philosophy for JS/TS; Black applies the same opinionated approach to Python

## FAQ
**Q: Does Black break my code?**
A: Black only changes formatting, never semantics. It parses and re-emits valid Python, so behavior stays identical.

**Q: Can I customize the line length?**
A: Yes. Set `line-length` in `pyproject.toml` or pass `--line-length` on the command line. The default is 88 characters.

**Q: How does Black handle strings?**
A: By default Black normalizes string quotes to double quotes. Use `--skip-string-normalization` to keep original quoting.

**Q: Is Black compatible with Ruff?**
A: Yes. Ruff's formatter is designed to produce output compatible with Black, and Ruff's linter can replace Flake8 alongside Black.

## Sources
- https://github.com/psf/black
- https://black.readthedocs.io/en/stable/

---
Source: https://tokrepo.com/en/workflows/f8be120b-40a0-11f1-9bc6-00163e2b0d79
Author: Script Depot