NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
PyPI · #248 most downloaded on PyPI
The uncompromising code formatter.
Last release today
04 Oct 2026
Release timing varies
gaps range from 2 weeks to 8 months
Nearly every release is documented
notes for 34 of 35 stable releases
1 version withdrawn
withdrawn after publishing
9 years old
74 releases · first in 2018
Nothing published for this version
Fix unstable formatting of annotated assignments whose subscript annotation contains an inline comment (e.g. x: list[ # pyright: ignore[...] )
x: list[ # pyright: ignore[...]) (#5130)# type: ignore) immediately before a# fmt: skip line, avoiding AST equivalence failures (#5139)One column per quarter.
Add support for unpacking in comprehensions (PEP 798) and for lazy imports (PEP 810), both new syntactic features in Python 3.15
# fmt: skip being ignored in nested if expressions with parenthesized in# fmt: off comment inside brackets (#5097)# fmt: skip is placed on the@overload groups) in .pyi stub.pyi stub# type: ignore) follows the closing bracket (#5096)SourceASTParseError to distinguish source parse failures from internal safetyast.parse() rejects (#5080)Prevent Jupyter notebook magic masking collisions from corrupting cells by using exact-length placeholders for short magics and aborting if a placehol
--python-cell-magics so customRemove deprecated function uvloop.install() in favor of uvloop.new_event_loop()
# type: ignore comments would be merged with otherif guards in case blocks were incorrectly split when the pattern hadstring_processing crashing on unassigned long string literals with trailinguvloop.install() in favor of uvloop.new_event_loop()maybe_install_uvloop function to maybe_use_uvloop to simplify loopblack requirements in the GitHub Action when use_pyproject isblack @ https://... are rejected. Users should upgrade to the latest version of thepsf/black@stable, and is independent of the version of Black installed by theIntroduces the 2026 stable style ( #4892 ), stabilizing the following changes:
Introduces the 2026 stable style (#4892), stabilizing the following changes:
always_one_newline_after_import: Always force one blank line after importfix_fmt_skip_in_one_liners: Fix # fmt: skip behavior on one-liner declarations,def foo(): return "mock" # fmt: skip, where previously the declaration wouldfix_module_docstring_detection: Fix module docstrings being treated as normalfix_type_expansion_split: Fix type expansions split in generic functions (#4777)multiline_string_handling: Make expressions involving multiline strings more compactnormalize_cr_newlines: Add \r style newlines to the potential newlines toremove_parens_around_except_types: Remove parentheses around multiple exceptionexcept and except* without as (#4720)remove_parens_from_assignment_lhs: Remove unnecessary parentheses from the left-handstandardize_type_comments: Format type comments which have zero or more spaces# and type: or between type: and value to # type: (value) (#4645)The following change was not in any previous stable release:
_width_table.py and added tests for the Khmer language (#4253)This release alo bumps pathspec to v1 and fixes inconsistencies with Git's
.gitignore logic (#4958). Now, files will be ignored if a pattern matches them, even
if the parent directory is directly unignored. For example, Black would previously
format exclude/not_this/foo.py with this .gitignore:
exclude/
!exclude/not_this/
Now, exclude/not_this/foo.py will remain ignored. To ensure exclude/not_this/ and
all of it's children are included in formatting (and in Git), use this .gitignore:
*/exclude/*
!*/exclude/not_this/
This new behavior matches Git. The leading */ are only necessary if you wish to ignore
matching subdirectories (like the previous behavior did), and not just matching root
directories.
This is a preview of the Black stable style for 2026 ( #4892 ). Please test it and share your feedback !
This is a preview of the Black stable style for 2026 (#4892). Please test it and
share your feedback!
The following formatting changes are included:
always_one_newline_after_import: Always force one blank line after importfix_fmt_skip_in_one_liners: Fix # fmt: skip behavior on one-liner declarations,def foo(): return "mock" # fmt: skip, where previously the declaration wouldfix_module_docstring_detection: Fix module docstrings being treated as normalfix_type_expansion_split: Fix type expansions split in generic functions (#4777)multiline_string_handling: Make expressions involving multiline strings more compactnormalize_cr_newlines: Add \r style newlines to the potential newlines toremove_parens_around_except_types: Remove parentheses around multiple exceptionexcept and except* without as. See PEP 758 for details (#4720)remove_parens_from_assignment_lhs: Remove unnecessary parentheses from the left-handstandardize_type_comments: Format type comments which have zero or more spaces# and type: or between type: and value to # type: (value) (#4645)_width_table.py and added tests for the Khmer language (#4253)Please test out the draft 2026 style in version 26.1a1! This style will be finalized in the January release (26.1.0). Most of the changes in --preview
Please test out the draft 2026 style in version 26.1a1! This style will be finalized in
the January release (26.1.0). Most of the changes in --preview will be in the 2026
stable style, but not all.
Please share your feedback!
This release (25.12.0) will still produce the 2025 style.
# fmt: off/# fmt: on blocks were incorrectly# %% [markdown] comments (#4845)# fmt: skip comments are used in a multi-part if-clause, onfmt: directives aren't on the top level (#4856)fmt: skip skipping the line after instead of the line it's on (#4855)fix_fmt_skip_in_one_liners crashing on with statements (#4853)fix_fmt_skip_in_one_liners crashing on annotated parameters (#4854)# fmt: skip on them (#4894)output-file input to GitHub Action psf/black to write formatter output to aAdd support for the new Python 3.14 t-string syntax introduced by PEP 750
# fmt: off and # fmt: on were reformatted (#4811)multiline_string_handling from --unstable to --preview (#4760)# type: <value> (#4645)fix_fmt_skip_in_one_liners preview feature to respect # fmt: skip for compoundno_cache option to control caching behavior. (#4803)psf/black to support the required-version major-version-onlyRemove support for pre-python 3.7 await/async as soft keywords/variable names
await/async as soft keywords/variable namesdel statement containing tuples (#4628)with# fmt: skip followed by a comment at the end of file (#4635)as clause of a with statement (#4634)with statement (#4646)\ followed by a \r followed by a comment (#4663)\\r\n (#4673)await ... (where ... is a literal Ellipsis) (#4676)# fmt: skip would stillmultiline_string_handling with ternaries and dictionaries (#4657)string_processing would not split f-strings directly afterin clause of comprehensions across lines if necessary (#4699)except and except* withoutas. (#4720)\r style newlines to the potential newlines to normalize file newlines both frompsf/black to read Black version from an additional section in[project.dependency-groups] (#4606)This release introduces the new 2025 stable style ( #4558 ), stabilizing the following changes:
This release introduces the new 2025 stable style (#4558), stabilizing
the following changes:
# fmt: skip comments is no longer normalized (#4146)* and more complex type variable tuple (#4440)The following changes were not in any previous release:
with statements containing tuple generators/unpackingstring_processing and wrap_long_dict_values_in_parens from removingwrap_long_dict_values_in_parens from the unstable to preview style (#4561)is_fstring_start function in Black's tokenizer (#4541)--stdin-filename set to a force excluded path, stdin won't beBlack is now officially tested with Python 3.13 and provides Python 3.13 mypyc-compiled wheels.
X | Y style unions.
(#4453)%% magic (#4462)def fn(*args: *tuple[*Ts, T]) -> None: pass) (#4440)--unstable (#4466)blackd now requires a newer version of aiohttp. (#4451)Fix crash when # fmt: off is used before a closing parenthesis or bracket.
# fmt: off is used before a closing parenthesis or bracket. (#4363)\{ inside f-strings very well (#4422).gitignore (#4415)This is a bugfix release to fix two regressions in the new f-string parser introduced in 24.4.1.
This is a bugfix release to fix two regressions in the new f-string parser introduced in 24.4.1.
Add support for the new Python 3.12 f-string syntax introduced by PEP 701
git archive is skipped (#4313)Fix unwanted crashes caused by AST equivalency check
if guards in case blocks are now wrapped in parentheses when the line is too long.
(#4269)use_pyproject to the GitHub Action psf/black. This will read the
Black version from pyproject.toml. (#4294)…encouraged to upgrade immediately to fix CVE-2024-21503.
This release is a milestone: it fixes Black's first CVE security vulnerability. If you run Black on untrusted input, or if you habitually put thousands of leading tab characters in your docstrings, you are strongly encouraged to upgrade immediately to fix CVE-2024-21503.
This release also fixes a bug in Black's AST safety check that allowed Black to make incorrect changes to certain f-strings that are valid in Python 3.12 and higher.
--check is used with --quiet (#4236)Black will swallow any SyntaxWarnings or DeprecationWarnings produced by the ast module when performing equivalence checks
hug_parens_with_braces_and_square_brackets feature to the unstable style
due to an outstanding crash and proposed formatting tweaks (#4198)case statement if guards (#4214).pyproject.toml that is missing a tool.black section when
discovering project root and configuration. Since Black continues to use version
control as an indicator of project root, this is expected to primarily change behavior
for users in a monorepo setup (desirably). If you wish to preserve previous behavior,
simply add an empty [tool.black] to the previously discovered pyproject.toml
(#4204)SyntaxWarnings or DeprecationWarnings produced by the ast
module when performing equivalence checks (#4189)Bugfix release to fix a bug that made Black unusable on certain file systems with strict limits on path length.
Bugfix release to fix a bug that made Black unusable on certain file systems with strict limits on path length.
Remove the long-deprecated --experimental-string-processing flag. This feature can currently be enabled with --preview --enable-unstable-feature strin…
This release introduces the new 2024 stable style (#4106), stabilizing the following changes:
if-else expressions (#2278)... are formatted more
compactly (#3796)with statement
(#3489)--skip-magic-trailing-comma or -C, trailing commas are stripped from
subscript expressions with more than 1 element (#3209)# fmt: skip with other comments (#3959)There are already a few improvements in the --preview style, which are slated for the
2025 stable style. Try them out and
share your feedback. In the past, the preview
style has included some features that we were not able to stabilize. This year, we're
adding a separate --unstable style for features with known problems. Now, the
--preview style only includes features that we actually expect to make it into next
year's stable style.
Several bug fixes were made in features that are moved to the stable style in this release:
--unstable style, covering preview features that have known problems that would
block them from going into the stable style. Also add the --enable-unstable-feature
flag; for example, use
--enable-unstable-feature hug_parens_with_braces_and_square_brackets to apply this
preview feature throughout 2024, even if a later Black release downgrades the feature
to unstable (#4096)# fmt: skip comments (#4146)pyproject.toml contains an invalid key (#4165)--experimental-string-processing flag. This feature can
currently be enabled with --preview --enable-unstable-feature string_processing.
(#4096)Thank you to everyone who provided feedback to help make Black's 2024 style even better. Thank you also to everyone who contributed code to Black.
This is a preview of the 2024 stable style, showing the formatting that Black will use in 2024. Please test it out and share your feedback.
This is a preview of the 2024 stable style, showing the formatting that Black will use in 2024. Please test it out and share your feedback.
This applies the following changes:
... are formatted more
compactly (#3796)with statement
(#3489)--skip-magic-trailing-comma or -C, trailing commas are stripped from
subscript expressions with more than 1 element (#3209)# fmt: skip with other comments (#3959)The following two changes may be included, but have outstanding issues that will need to be resolved:
if-else expressions (#2278)Fixed a bug that included dependencies from the d extra by default
Fixed a bug that included dependencies from the d extra by default (#4108)
It's almost 2024, which means it's time for a new edition of _Black_'s stable style! Together with this release, we'll put out an alpha release 24.1a1
It's almost 2024, which means it's time for a new edition of Black's stable style! Together with this release, we'll put out an alpha release 24.1a1 showcasing the draft 2024 stable style, which we'll finalize in the January release. Please try it out and share your feedback.
This release (23.12.0) will still produce the 2023 style. Most but not all of the
changes in --preview mode will be in the 2024 stable style.
# fmt: off automatically dedents when used with the --line-ranges
option, even when it is not within the specified line range. (#4084)--line-length (#4086)--line-ranges now skips Black's internal stability check in --safe mode. This
avoids a crash on rare inputs that have many unformatted same-content lines. (#4034)Support formatting ranges of lines with the new --line-ranges command-line option
--line-ranges command-line option
(#4020)await (a ** b) (#3994)case blocks were not split into multiple lines. Also enable
general trailing comma rules on case blocks (#4024)--include (#3976)Maintanence release to get a fix out for GitHub Action edge case
summary
parameter. (#3958)Fix comments getting removed from inside parenthesized strings
BLACK_CACHE_DIR is set (#3937)type were not acccepted inside match statements
(#3950)Due to various issues, the previous release (23.9.0) did not include compiled mypyc wheels, which make Black significantly faster. These issues have n
Due to various issues, the previous release (23.9.0) did not include compiled mypyc wheels, which make Black significantly faster. These issues have now been fixed, and this release should come with compiled wheels once again.
There will be no wheels for Python 3.12 due to a bug in mypyc. We will provide 3.12 wheels in a future release as soon as the mypyc bug is fixed.
More concise formatting for dummy implementations
if sys.version_info > (3, x):) and a function definition on the same level (#3862)IPython if notebook cells do not contain magics (#3782)blackd with single character input (#3558)https://github.com/psf/black to https://github.com/psf/black-pre-commit-mirror in
your .pre-commit-config.yaml will make Black about 2x faster (#3828).black.env folder specified by ENV_PATH will now be removed on the completion
of the GitHub Action (#3759)Use aware UTC datetimes internally, avoids deprecation warning on Python 3.12
type: ignore within parentheses
(#3740)--workers argument to Black can now be specified via the BLACK_NUM_WORKERS
environment variable (#3743).pytest_cache, .ruff_cache and .vscode are now excluded by default (#3691)pyproject.toml settings when running --stdin-filename
and the pyproject.toml found isn't in the current working directory (#3719)exclude and extend-exclude have invalid data types in
pyproject.toml, instead of silently doing the wrong thing (#3764)LANG=C (#3768)IPython in a case where we wouldn't need it (#3748)blackd argument parser now shows the default values for options in their help
text (#3712)PYTHONWARNDEFAULTENCODING = 1
(#3763)Document that only the most recent release is supported for security issues; vulnerabilities should be reported through Tidelift
This release fixes a longstanding confusing behavior in Black's GitHub action, where the version of the action did not determine the version of Black being run (issue #3382). In addition, there is a small bug fix around imports and a number of improvements to the preview style.
Please try out the
preview style
with black --preview and tell us your feedback. All changes in the preview style are
expected to become part of Black's stable style in January 2024.
# fmt: skip and # fmt: off no longer have an extra blank line
added when they are right after another import line (#3610)async def, async for, and async with statements are now formatted consistently
compared to their non-async version. (#3609)with statements that contain two context managers will be consistently wrapped in
parentheses (#3589)、 U+3001
IDEOGRAPHIC COMMA, 。 U+3002 IDEOGRAPHIC FULL STOP, & ， U+FF0C FULLWIDTH COMMA)
besides before spaces (#3445)... (#3564)This is the first release of 2023, and following our stability policy, it comes with a number of improvements to our stable style, notably improvement
This is the first release of 2023, and following our stability policy, it comes with a number of improvements to our stable style, notably improvements to empty line handling and the removal of redundant parentheses in several contexts.
There are also many changes to the preview style; try out black --preview and give us feedback to help us set the stable style for next year.
In addition to style changes, Black now automatically infers the supported Python versions from your pyproject.toml file, removing the need to set Black's target versions separately.
<!-- Changes that affect Black's stable style -->
--skip-string-normalization / -S now prevents docstring prefixes from being normalized as expected (#3168) (since 22.8.0)--skip-magic-trailing-comma or -C, trailing commas are stripped from subscript expressions with more than 1 element (#3209) (22.8.0)with statements (#2926) (22.6.0)#%% are now standardised to # %% (#2919) (22.3.0)except statements (#2939) (22.3.0)for loops (#2945) (22.3.0)# fmt: off and # fmt: on (#3439)<!-- Changes that affect Black's preview style -->
if-else expressions (#2278)# fmt: skip applied or there is a standalone comment between decorators (#3470)with statements or tuples (#3473)await (yield) when Black is compiled with mypyc (#3533)<!-- Changes to how Black can be configured -->
--target-version from the project metadata specified in pyproject.toml (#3219)<!-- Changes to how Black is packaged, such as dependency requirements -->
0.971 to 0.991 so mypycified Black can be built on armv7 (#3380)
tomli requirement on 3.11 alpha releases, working around a bug that would cause the requirement not to be installed on any non-final Python releases (#3448)packaging version 22.0 or later. This is required for new functionality that needs to parse part of the project metadata (#3219)<!-- Changes to Black's terminal output and error messages -->
black --help multiple times will return the same help contents each time (#3516)pyproject.toml configuration variables (#3392)<!-- For example, Docker, GitHub Actions, pre-commit, editors -->
latest_prerelease tag automation to follow latest black alpha release on docker images (#3465)<!-- Major changes to documentation and policies. Small docs changes don't need a changelog entry. -->
vim-plug installation instructions to offer more explicit options (#3468)This release provides a preview of Black's 2023 stable style. Black's default formatting style includes the following changes:
This release provides a preview of Black's 2023 stable style. Black's default formatting style includes the following changes:
--skip-string-normalization / -S now prevents docstring prefixes from being
normalized as expected (#3168) (since 22.8.0)--skip-magic-trailing-comma or -C, trailing commas are stripped from
subscript expressions with more than 1 element (#3209) (22.8.0)with statements (#2926) (22.6.0)#%% are now standardised to # %% (#2919) (22.3.0)except statements (#2939) (22.3.0)for loops (#2945) (22.3.0)Please try it out and give feedback here: https://github.com/psf/black/issues/3407
A stable 23.1.0 release will follow in January 2023.
<!-- Changes that affect Black's preview style -->
<!-- Changes that affect Black's preview style -->
<!-- Changes to how Black can be configured -->
.gitignore rules by considering the .gitignore location
and the relative path to the target file (#3338).gitignore presence when more than one source directory is
specified (#3336)<!-- Changes to the parser or to version autodetection -->
any(match := my_re.match(text) for text in texts)) (#3327).<!-- For example, Docker, GitHub Actions, pre-commit, editors -->
let g:black_use_virtualenv = 0(#3309).gitignore rules by considering the .gitignore location
and the relative path to the target file (#3338).gitignore presence when more than one source directory is
specified (#3336)any(match := my_re.match(text) for text in texts)) (#3327).let g:black_use_virtualenv = 0(#3309)Runtime support for Python 3.6 has been removed. Formatting 3.6 code will still be supported until further notice.
# fmt: on is used on a different block level than # fmt: off
(#3281).ipynb_checkpoints directories are now excluded by default (#3293)--skip-source-first-line / -x option to ignore the first line of source code
while formatting (#3299)g:black_preview) to enable/disable the preview style (#3246)jupyter
option (#3282)<23) for Black
version (#3265)Change from deprecated asyncio.get_event_loop() to create our event loop which removes DeprecationWarning
# fmt: on/off in the middle of an expression or code block (#3158)# fmt: skip on colon (:) lines (#3148)--skip-string-normalization / -S now prevents docstring prefixes from being normalized as expected (#3168)--skip-magic-trailing-comma or -C, trailing commas are stripped from subscript expressions with more than 1 element (#3209)blackd now supports enabling the preview style via the X-Preview header (#3217)--stdin-filename (#3216).gitignore files in source directories given on the command line are now also respected, previously only .gitignore files in the project root and automatically discovered directories were respected (#3237)Black: so it's clear they come from Black (#3194)asyncio.get_event_loop() to create our event loop which removes DeprecationWarning (#3164)blib2to3 library since it regularly emits error logs about failed caching that can and should be ignored (#3193)Full Changelog: https://github.com/psf/black/compare/22.6.0...22.8.0
Thank you!
# fmt: off/on/skip code and continuing to improve the preview style, notably the (still) experimental string processingBlack: to most emitted messagesblackd (finally :tada:).gitignore bug that we should've caught many moons ago... and everyone else who contributed documentation, tests, or other improvements to the Black project!
Finally congratulations to the first time contributors this time around!
Fix unstable formatting involving #fmt: skip and # fmt:skip comments (notice the lack of spaces)
#fmt: skip and # fmt:skip comments (notice the lack of spaces) (#2970)with statements (#2926)scripts/migrate-black.py script to ease introduction of Black to a Git project (#3038)--version flag (#2997)tomli instead of tomllib on Python 3.11 builds where tomllib is not available (#2987)except *ExceptionGroup:) is now supported (#3016)Array[Batch, *Shape] or def fn(*args: *T) -> None) is now supported (#3071)strtobool function. It didn't parse true/on/false/off. (#3025)Full Changelog: https://github.com/psf/black/compare/22.3.0...22.6.0
Thank you!
... and everyone else who contributed documentation, tests, or other improvements to the Black project!
Finally congrats to first contributors!
black-primer, the deprecated internal devtool, has been removed and copied to a separate repository
#%% are now standardised to # %% (#2919)except statements (#2939)for loops (#2945)__pypackages__ directories by default (#2836)--required-version (#2832).tomllib instead of tomli
(#2903)black-primer, the deprecated internal devtool, has been removed and copied to a
separate repository (#2924)for and async for
statements, e.g for item in *items_1, *items_2: pass (#2879).Deprecate --experimental-string-processing and move the functionality under --preview
At long last, Black is no longer a beta product! This is the first non-beta release and the first release covered by our new stability policy.
--preview flag (#2752)--experimental-string-processing and move the functionality under --preview (#2789)case {"key": 1 | 2 as password} (#2686)case 1 as a, 2 as b (#2716)case Foo(bar=baz as quux) (#2749)return and yield constructs now implies 3.8+ (#2700)values: Tuple[int, ...] = 1, 2, 3) now implies 3.8+ (#2708)match() or case() when there is a trailing newline or a comment inside of the parentheses. (#2760)from __future__ import annotations statement now implies Python 3.7+ (#2690)--target-version is set to 3.10 and higher). (#2728)python-cell-magics) to format cells with custom magics in Jupyter Notebooks (#2744)BLACK_CACHE_DIR (#2739).-target-version=py310. (#2758)SRC or --code mandatory and mutually exclusive (#2804)typing-extensions is no longer a required dependency in Python 3.10+ (#2772)click lower bound to 8.0.0 as Black crashes on 7.1.2 (#2791)https:// (#2761)black-primer tool (#2809)Full Changelog: https://github.com/psf/black/compare/21.12b0...22.1.0
And also congrats to first contributors!
Fix determination of f-string expression spans
%%writefile. (#2630)--target-version py310 if we detect 3.10-only syntax (#2668)match statements with open sequence subjects, like match a, b: or match a, *b: (#2639) (#2659)match/case statements that contain match/case soft keywords multiple times, like match re.match() (#2661)case statements with an inline body (#2665)match subject (#2667)match statement (#2649)match under --target-version py310 up to ~50% (#2670)regex (#2644) (#2663)regex dependencyAnd also congrats to first contributors!
Bumped regex version minimum to 2021.4.4 to fix Pattern class usage
Warn about Python 2 deprecation in more cases by improving Python 2 only syntax detection
--target-version py310 is explicitly specified (#2586)skip_magic_trailing_comma from pyproject.toml (#2613)Deprecate Python 2 formatting support
--workers parameter (#2514)target_version in the vim plugin (#1319)Fix missing modules in self-contained binaries
Add support for formatting Jupyter Notebook files
appdirs dependency to platformdirs (#2375)setuptools-scm build-time dependency version (#2457)language_version to avoid overriding default_language_version (#2430)Configuration files using TOML features higher than spec v0.5.0 are now supported
FORCE_OPTIONAL_PARENTHESES feature is enabled (#2332)latest_release tag automation to follow latest black release on docker
images (#2374)Fix failure caused by fmt: skip and indentation
fmt: skip and indentation (#2281)--code flag (#2259)uvloop.install() when Black is used as a library (#2303)--required-version option to require a specific version to be running (#2300)R prefixes would be lowercased for docstrings (#2285)\N{...}) when --experimental-string-processing is
used (#2319)fmt: skip and indentation (#2281)--code flag (#2259)uvloop.install() when Black is used as a library (#2303)--required-version option to require a specific version to be running (#2300)R prefixes would be lowercased for docstrings (#2285)\N{...}) when --experimental-string-processing is
used (#2319)A space is no longer inserted into empty docstrings
.gitignore files in all levels, not only root/.gitignore file (apply
.gitignore rules like git does) (#2225)aiohttp-cors dependency. Only 0.4.0 or higher is
supported. (#2231)--experimental-string-processing will be enabled by default in the future (#2273)Refactor src/black/__init__.py into many files
src/black/__init__.py into many files (#2206)master branch with the main branch. Some additional changes in the source code were also made. (#2210)Set --pyi mode if --stdin-filename ends in .pyi
--pyi mode if --stdin-filename ends in .pyi (#2169)--no-diff to black-primer to suppress formatting changes (#2187)Fix crash if the user configuration directory is inaccessible.
Fix crash if the user configuration directory is inaccessible. (#2158)
Clarify circumstances in which Black may change the AST (#2159)
primer.json (used by black-primer by default) with black. (#2154)Fix crash if the user configuration directory is inaccessible. (#2158)
Clarify circumstances in which Black may change the AST (#2159)
Allow .gitignore rules to be overridden by specifying exclude in pyproject.toml
or on the command line. (#2170)
primer.json (used by black-primer by default) with black. (#2154)Fix crash on docstrings ending with "\ ".
Fix crash on docstrings ending with "\ ". (#2142)
Fix crash when atypical whitespace is cleaned out of dostrings (#2120)
Reflect the --skip-magic-trailing-comma and --experimental-string-processing flags
in the name of the cache file. Without this fix, changes in these flags would not take
effect if the cache had already been populated. (#2131)
Don't remove necessary parentheses from assignment expression containing assert / return statements. (#2143)
Fixed a rare but annoying formatting instability created by the combination of optional trailing commas inserted by Black and optional parentheses loo
Fixed a rare but annoying formatting instability created by the combination of
optional trailing commas inserted by Black and optional parentheses looking at
pre-existing "magic" trailing commas. This fixes issue #1629 and all of its many many
duplicates. (#2126)
Black now processes one-line docstrings by stripping leading and trailing spaces,
and adding a padding space when needed to break up """". (#1740)
Black now cleans up leading non-breaking spaces in comments (#2092)
Black now respects --skip-string-normalization when normalizing multiline
docstring quotes (#1637)
Black no longer removes all empty lines between non-function code and decorators
when formatting typing stubs. Now Black enforces a single empty line. (#1646)
Black no longer adds an incorrect space after a parenthesized assignment expression
in if/while statements (#1655)
Added --skip-magic-trailing-comma / -C to avoid using trailing commas as a reason
to split lines (#1824)
fixed a crash when PWD=/ on POSIX (#1631)
fixed "I/O operation on closed file" when using --diff (#1664)
Prevent coloured diff output being interleaved with multiple files (#1673)
Added support for PEP 614 relaxed decorator syntax on python 3.9 (#1711)
Added parsing support for unparenthesized tuples and yield expressions in annotated assignments (#1835)
use lowercase hex strings (#1692)
added --extend-exclude argument (PR #2005)
speed up caching by avoiding pathlib (#1950)
--diff correctly indicates when a file doesn't end in a newline (#1662)
Added --stdin-filename argument to allow stdin to respect --force-exclude rules
(#1780)
Lines ending with fmt: skip will now be not formatted (#1800)
PR #2053: Black no longer relies on typed-ast for Python 3.8 and higher
PR #2053: Python 2 support is now optional, install with
python3 -m pip install black[python2] to maintain support.
Exclude venv directory by default (#1683)
Fixed "Black produced code that is not equivalent to the source" when formatting Python 2 docstrings (#2037)
explicitly depend on Click 7.1.2 or newer as Black no longer works with versions older than 7.0
Black no longer works with versions
older than 7.0removed deprecated --py36 option
re-implemented support for explicit trailing commas: now it works consistently within any bracket pair, including nested structures (#1288 and duplicates)
Black now reindents docstrings when reindenting code around it (#1053)
Black now shows colored diffs (#1266)
Black is now packaged using 'py3' tagged wheels (#1388)
Black now supports Python 3.8 code, e.g. star expressions in return statements
(#1121)
Black no longer normalizes capital R-string prefixes as those have a
community-accepted meaning (#1244)
Black now uses exit code 2 when specified configuration file doesn't exit (#1361)
Black now works on AWS Lambda (#1141)
added --force-exclude argument (#1032)
removed deprecated --py36 option (#1236)
fixed --diff output when EOF is encountered (#526)
fixed # fmt: off handling around decorators (#560)
fixed unstable formatting with some # type: ignore comments (#1113)
fixed invalid removal on organizing brackets followed by indexing (#1575)
introduced black-primer, a CI tool that allows us to run regression tests against
existing open source users of Black (#1402)
introduced property-based fuzzing to our test suite based on Hypothesis and Hypothersmith (#1566)
implemented experimental and disabled by default long string rewrapping (#1132),
hidden under a --experimental-string-processing flag while it's being worked on;
this is an undocumented and unsupported feature, you lose Internet points for
depending on it (#1609)
added support for PEP 572 assignment expressions
added support for PEP 572 assignment expressions (#711)
added support for PEP 570 positional-only arguments (#943)
added support for async generators (#593)
added support for pre-splitting collections by putting an explicit trailing comma inside (#826)
added black -c as a way to format code passed from the command line (#761)
--safe now works with Python 2 code (#840)
fixed grammar selection for Python 2-specific code (#765)
fixed feature detection for trailing commas in function definitions and call sites (#763)
# fmt: off/# fmt: on comment pairs placed multiple times within the same block of
code now behave correctly (#1005)
Black no longer crashes on Windows machines with more than 61 cores (#838)
Black no longer crashes on standalone comments prepended with a backslash (#767)
Black no longer crashes on from ... import blocks with comments (#829)
Black no longer crashes on Python 3.7 on some platform configurations (#494)
Black no longer fails on comments in from-imports (#671)
Black no longer fails when the file starts with a backslash (#922)
Black no longer merges regular comments with type comments (#1027)
Black no longer splits long lines that contain type comments (#997)
removed unnecessary parentheses around yield expressions (#834)
added parentheses around long tuples in unpacking assignments (#832)
added parentheses around complex powers when they are prefixed by a unary operator (#646)
fixed bug that led Black format some code with a line length target of 1 (#762)
Black no longer introduces quotes in f-string subexpressions on string boundaries (#863)
if Black puts parenthesis around a single expression, it moves comments to the wrapped expression instead of after the brackets (#872)
blackd now returns the version of Black in the response headers (#1013)
blackd can now output the diff of formats on source code when the X-Diff header is
provided (#969)
deprecated --py36 (use --target-version=py36 instead)
new option --target-version to control which Python versions Black-formatted code
should target (#618)
deprecated --py36 (use --target-version=py36 instead) (#724)
Black no longer normalizes numeric literals to include _ separators (#696)
long del statements are now split into multiple lines (#698)
type comments are no longer mangled in function signatures
improved performance of formatting deeply nested data structures (#509)
Black now properly formats multiple files in parallel on Windows (#632)
Black now creates cache files atomically which allows it to be used in parallel
pipelines (like xargs -P8) (#673)
Black now correctly indents comments in files that were previously formatted with tabs (#262)
blackd now supports CORS (#622)
numeric literals are now formatted by _Black_ (#452, #461, #464, #469):
numeric literals are now formatted by Black (#452, #461, #464, #469):
numeric literals are normalized to include _ separators on Python 3.6+ code
added --skip-numeric-underscore-normalization to disable the above behavior and
leave numeric underscores as they were in the input
code with _ in numeric literals is recognized as Python 3.6+
most letters in numeric literals are lowercased (e.g., in 1e10, 0x01)
hexadecimal digits are always uppercased (e.g. 0xBADC0DE)
added blackd, see
its documentation for
more info (#349)
adjacent string literals are now correctly split into multiple lines (#463)
trailing comma is now added to single imports that don't fit on a line (#250)
cache is now populated when --check is successful for a file which speeds up
consecutive checks of properly formatted unmodified files (#448)
whitespace at the beginning of the file is now removed (#399)
fixed mangling pweave and Spyder IDE special comments (#532)
fixed unstable formatting when unpacking big tuples (#267)
fixed parsing of __future__ imports with renames (#389)
fixed scope of # fmt: off when directly preceding yield and other nodes (#385)
fixed formatting of lambda expressions with default arguments (#468)
fixed async for statements: Black no longer breaks them into separate lines (#372)
note: the Vim plugin stopped registering ,= as a default chord as it turned out to
be a bad idea (#415)
hotfix: don't freeze when multiple comments directly precede # fmt: off
# fmt: off (#371)typing stub files (.pyi) now have blank lines added after constants
typing stub files (.pyi) now have blank lines added after constants (#340)
# fmt: off and # fmt: on are now much more dependable:
they now work also within bracket pairs (#329)
they now correctly work across function/class boundaries (#335)
they now work when an indentation block starts with empty lines or misaligned comments (#334)
made Click not fail on invalid environments; note that Click is right but the likelihood we'll need to access non-ASCII file paths when dealing with Python source code is low (#277)
fixed improper formatting of f-strings with quotes inside interpolated expressions (#322)
fixed unnecessary slowdown when long list literals where found in a file
fixed unnecessary slowdown on AST nodes with very many siblings
fixed cannibalizing backslashes during string normalization
fixed a crash due to symbolic links pointing outside of the project directory (#338)
fixed improper unmodified file caching when -S was used
added --config (#65)
added -h equivalent to --help (#316)
fixed improper unmodified file caching when -S was used
fixed extra space in string unpacking (#305)
fixed formatting of empty triple quoted strings (#313)
fixed unnecessary slowdown in comment placement calculation on lines without comments
Your coding agent can read these notes before it upgrades. Set up the MCP server →