black
Black is "the uncompromising code formatter" for Python that automatically formats your code to be consistent and PEP 8 compliant. By using Black, you agree to cede control over minutiae of hand-formatting in return for speed, determinism, and freedom from formatting debates.
Key features:
- Opinionated Formatting: Minimal configuration with sensible defaults - "Black is opinionated so you don't have to be"
- Deterministic Output: Same code always produces identical formatting, regardless of environment
- Speed and Efficiency: Fast formatting with parallel processing capabilities
- Smallest Diffs: Produces minimal git diffs by being consistent across all projects
- AST Safety: Verifies that reformatted code produces a valid AST equivalent to the original
- Wide Compatibility: Supports multiple Python versions and syntax features
Formatting principles:
- Consistency Over Preferences: Uniform style across all Python projects using Black
- Readability First: Optimizes for code readability and maintainability
- Minimal Configuration: Works out of the box with virtually no setup required
What Black formats:
- Code Structure: Consistent indentation, line breaks, and whitespace
- String Formatting: Standardizes quote usage and multi-line strings
- Import Organization: Works well with isort for import formatting
- Expression Layout: Optimizes function calls, list comprehensions, and complex expressions
Benefits:
- Faster Code Reviews: Eliminates style discussions and focuses on logic
- Mental Energy Savings: No time spent on formatting decisions
- Team Consistency: Entire team uses identical formatting standards
- Reduced Conflicts: Fewer git merge conflicts due to formatting differences
Black is successfully used by many projects, small and big, and has become the de facto standard for Python code formatting. It's now stable with comprehensive test coverage and should not expect large formatting changes in the future.
Note: Black formats code according to its opinionated style. If you prefer different formatting options, you might consider other formatters, though Black's consistency is its main strength.
black documentation
- Version in MegaLinter: 25.1.0
- Visit Official Web Site
- See How to configure black rules
- If custom
pyproject.tomlconfig file isn't found, pyproject.toml will be used
- If custom
Configuration in MegaLinter
- Enable black by adding
PYTHON_BLACKin ENABLE_LINTERS variable - Disable black by adding
PYTHON_BLACKin DISABLE_LINTERS variable
- Enable autofixes by adding
PYTHON_BLACKin APPLY_FIXES variable
| Variable | Description | Default value |
|---|---|---|
| PYTHON_DEFAULT_STYLE | For black to be active, PYTHON_DEFAULT_STYLE must be black |
black |
| PYTHON_BLACK_ARGUMENTS | User custom arguments to add in linter CLI call Ex: -s --foo "bar" |
|
| PYTHON_BLACK_COMMAND_REMOVE_ARGUMENTS | User custom arguments to remove from command line before calling the linter Ex: -s --foo "bar" |
|
| PYTHON_BLACK_FILTER_REGEX_INCLUDE | Custom regex including filter Ex: (src\|lib) |
Include every file |
| PYTHON_BLACK_FILTER_REGEX_EXCLUDE | Custom regex excluding filter Ex: (test\|examples) |
Exclude no file |
| PYTHON_BLACK_CLI_LINT_MODE | Override default CLI lint mode - file: Calls the linter for each file- list_of_files: Call the linter with the list of files as argument- project: Call the linter from the root of the project |
list_of_files |
| PYTHON_BLACK_FILE_EXTENSIONS | Allowed file extensions. "*" matches any extension, "" matches empty extension. Empty list excludes all filesEx: [".py", ""] |
[".py"] |
| PYTHON_BLACK_FILE_NAMES_REGEX | File name regex filters. Regular expression list for filtering files by their base names using regex full match. Empty list includes all files Ex: ["Dockerfile(-.+)?", "Jenkinsfile"] |
Include every file |
| PYTHON_BLACK_PRE_COMMANDS | List of bash commands to run before the linter | None |
| PYTHON_BLACK_POST_COMMANDS | List of bash commands to run after the linter | None |
| PYTHON_BLACK_UNSECURED_ENV_VARIABLES | List of env variables explicitly not filtered before calling PYTHON_BLACK and its pre/post commands | None |
| PYTHON_BLACK_CONFIG_FILE | black configuration file nameUse LINTER_DEFAULT to let the linter find it |
pyproject.toml |
| PYTHON_BLACK_RULES_PATH | Path where to find linter configuration file | Workspace folder, then MegaLinter default rules |
| PYTHON_BLACK_DISABLE_ERRORS | Run linter but consider errors as warnings | true |
| PYTHON_BLACK_DISABLE_ERRORS_IF_LESS_THAN | Maximum number of errors allowed | 0 |
| PYTHON_BLACK_CLI_EXECUTABLE | Override CLI executable | ['black'] |
IDE Integration
Use black in your favorite IDE to catch errors before MegaLinter !
MegaLinter Flavors
This linter is available in the following flavors
| Flavor | Description | Embedded linters | Info | |
|---|---|---|---|---|
 |
all | Default MegaLinter Flavor | 127 |   |
| cupcake | MegaLinter for the most commonly used languages | 88 |   |
|
| formatters | Contains only formatters | 18 |   |
|
| python | Optimized for PYTHON based projects | 66 |   |
Behind the scenes
How are identified applicable files
- File extensions:
.py
How the linting is performed
- black is called once with the list of files as arguments (
list_of_filesCLI lint mode)
Example calls
black --diff --check myfile.py
black --config pyproject.toml --diff --check myfile.py
black --config pyproject.toml myfile.py
Help content
Usage: black [OPTIONS] SRC ...
The uncompromising code formatter.
Options:
-c, --code TEXT Format the code passed in as a string.
-l, --line-length INTEGER How many characters per line to allow.
[default: 88]
-t, --target-version [py33|py34|py35|py36|py37|py38|py39|py310|py311|py312|py313]
Python versions that should be supported by
Black's output. You should include all
versions that your code supports. By
default, Black will infer target versions
from the project metadata in pyproject.toml.
If this does not yield conclusive results,
Black will use per-file auto-detection.
--pyi Format all input files like typing stubs
regardless of file extension. This is useful
when piping source on standard input.
--ipynb Format all input files like Jupyter
Notebooks regardless of file extension. This
is useful when piping source on standard
input.
--python-cell-magics TEXT When processing Jupyter Notebooks, add the
given magic to the list of known python-
magics (capture, prun, pypy, python,
python3, time, timeit). Useful for
formatting cells with custom python magics.
-x, --skip-source-first-line Skip the first line of the source code.
-S, --skip-string-normalization
Don't normalize string quotes or prefixes.
-C, --skip-magic-trailing-comma
Don't use trailing commas as a reason to
split lines.
--preview Enable potentially disruptive style changes
that may be added to Black's main
functionality in the next major release.
--unstable Enable potentially disruptive style changes
that have known bugs or are not currently
expected to make it into the stable style
Black's next major release. Implies
--preview.
--enable-unstable-feature [string_processing|hug_parens_with_braces_and_square_brackets|wrap_long_dict_values_in_parens|multiline_string_handling|always_one_newline_after_import]
Enable specific features included in the
`--unstable` style. Requires `--preview`. No
compatibility guarantees are provided on the
behavior or existence of any unstable
features.
--check Don't write the files back, just return the
status. Return code 0 means nothing would
change. Return code 1 means some files would
be reformatted. Return code 123 means there
was an internal error.
--diff Don't write the files back, just output a
diff to indicate what changes Black would've
made. They are printed to stdout so
capturing them is simple.
--color / --no-color Show (or do not show) colored diff. Only
applies when --diff is given.
--line-ranges START-END When specified, Black will try its best to
only format these lines. This option can be
specified multiple times, and a union of the
lines will be formatted. Each range must be
specified as two integers connected by a
`-`: `<START>-<END>`. The `<START>` and
`<END>` integer indices are 1-based and
inclusive on both ends.
--fast / --safe By default, Black performs an AST safety
check after formatting your code. The --fast
flag turns off this check and the --safe
flag explicitly enables it. [default:
--safe]
--required-version TEXT Require a specific version of Black to be
running. This is useful for ensuring that
all contributors to your project are using
the same version, because different versions
of Black may format code a little
differently. This option can be set in a
configuration file for consistent results
across environments.
--exclude TEXT A regular expression that matches files and
directories that should be excluded on
recursive searches. An empty value means no
paths are excluded. Use forward slashes for
directories on all platforms (Windows, too).
By default, Black also ignores all paths
listed in .gitignore. Changing this value
will override all default exclusions.
[default: /(\.direnv|\.eggs|\.git|\.hg|\.ipy
nb_checkpoints|\.mypy_cache|\.nox|\.pytest_c
ache|\.ruff_cache|\.tox|\.svn|\.venv|\.vscod
e|__pypackages__|_build|buck-
out|build|dist|venv)/]
--extend-exclude TEXT Like --exclude, but adds additional files
and directories on top of the default values
instead of overriding them.
--force-exclude TEXT Like --exclude, but files and directories
matching this regex will be excluded even
when they are passed explicitly as
arguments. This is useful when invoking
Black programmatically on changed files,
such as in a pre-commit hook or editor
plugin.
--stdin-filename TEXT The name of the file when passing it through
stdin. Useful to make sure Black will
respect the --force-exclude option on some
editors that rely on using stdin.
--include TEXT A regular expression that matches files and
directories that should be included on
recursive searches. An empty value means all
files are included regardless of the name.
Use forward slashes for directories on all
platforms (Windows, too). Overrides all
exclusions, including from .gitignore and
command line options. [default:
(\.pyi?|\.ipynb)$]
-W, --workers INTEGER RANGE When Black formats multiple files, it may
use a process pool to speed up formatting.
This option controls the number of parallel
workers. This can also be specified via the
BLACK_NUM_WORKERS environment variable.
Defaults to the number of CPUs in the
system. [x>=1]
-q, --quiet Stop emitting all non-critical output. Error
messages will still be emitted (which can
silenced by 2>/dev/null).
-v, --verbose Emit messages about files that were not
changed or were ignored due to exclusion
patterns. If Black is using a configuration
file, a message detailing which one it is
using will be emitted.
--version Show the version and exit.
--config FILE Read configuration options from a
configuration file.
-h, --help Show this message and exit.
Installation on mega-linter Docker image
- Dockerfile commands :
# renovate: datasource=pypi depName=black
ARG PIP_BLACK_VERSION=25.1.0
- PIP packages (Python):