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**:
```python
# 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**
```bash
# 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**
```toml
# pyproject.toml
[tool.black]
line-length = 88
target-version = ['py38', 'py39', 'py310']
include = '\.pyi?$'
extend-exclude = '/(migrations|venv)/'
```
**Integration**
**VS Code**:
```json
{
"python.formatting.provider": "black",
"editor.formatOnSave": true
}
```
**Pre-commit Hook**:
```yaml
repos:
- repo: https://github.com/psf/black
rev: 23.12.0
hooks:
- id: black
```
**GitHub Actions**:
```yaml
- name: Check code formatting
run: |
pip install black
black --check .
```
**Magic Trailing Comma**
Control line breaking behavior:
```python
# 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.