black(1)
Format Python code automatically to a consistent style following PEP 8 conventions.
Synopsis
black [OPTIONS] [SRC]...Description
black is an opinionated Python code formatter that automatically reformats Python source code to a consistent style. It enforces PEP 8 compliance and removes debates about formatting by applying deterministic rules.
black reads Python files or entire directories, reformats all code to match its style guide (line length 88 characters by default), and writes the changes back. It is designed to be run automatically in CI/CD pipelines and pre-commit hooks to ensure uniform code style across projects.
Common options
| Flag | What it does |
|---|---|
-l, --line-length | Set target line length (default: 88 characters) |
-S, --skip-string-normalization | Skip conversion of string quotes (single to double) |
-C, --skip-source-first-line | Skip formatting if source code starts with a special comment |
-t, --target-version | Target Python version (e.g., py36, py37, py38, py39, py310) |
--pyi | Format .pyi stub files (Python type stub files) |
--fast | Skip AST validation after formatting (faster but less safe) |
--check | Don't write changes, only report which files would be reformatted |
--diff | Show diff instead of applying changes |
-q, --quiet | Suppress status messages and only report errors |
--verbose | Show extra debugging output during formatting |
Examples
Format a single Python file in place
black myfile.pyFormat all Python files in the src directory recursively
black src/Check if file would be reformatted without making changes
black --check myfile.pyShow the diff of changes that would be made without applying them
black --diff myfile.pyFormat with a custom line length of 100 characters instead of 88
black --line-length 100 myfile.pyFormat code but preserve existing string quote styles
black --skip-string-normalization src/Format for Python 3.9, using appropriate syntax
black --target-version py39 myfile.pyQuickly format all Python files in current directory silently
black --fast --quiet .