black
black documentation
- Version in MegaLinter: 24.4.2
- 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_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 Flavours
This linter is available in the following flavours
| Flavor | Description | Embedded linters | Info | |
|---|---|---|---|---|
 |
all | Default MegaLinter Flavor | 125 |   |
| cupcake | MegaLinter for the most commonly used languages | 84 |   |
|
| formatters | Contains only formatters | 17 |   |
|
| python | Optimized for PYTHON based projects | 64 |   |
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 [hex_codes_in_unicode_sequences|string_processing|hug_parens_with_braces_and_square_brackets|unify_docstring_detection|no_normalize_fmt_skip_whitespace|wrap_long_dict_values_in_parens|multiline_string_handling|typed_params_trailing_comma|is_simple_lookup_for_doublestar_expression|docstring_check_for_newline|remove_redundant_guard_parens|parens_for_long_if_clauses_in_case_block]
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
- PIP packages (Python):