pypi / black
black
What changed in black 26, from its official release notes, upgrade guides and advisories. Sources checked 2026-10-18.
7 breaking2 security6 new APIs and options6 performance5 behavior and defaults4 tooling38 fixes and other
See which of these apply to your code, ranked, in your agent:
npx @unstale/cli initblack 2668 changes
Breaking changes 7
The bundled action now rejects URL references and other non-released-version values read from tool.black.required-version, addressing a security issue.
Repeated lines outside the selected ranges are left unchanged.
Preview style parenthesizes expressions with parameter comments when they exceed the line length.
In preview style, short expressions inside brackets are not split on delimiters when preceded by a standalone comment.
Rejects non-string
force-excludevalues inpyproject.toml.Rejects non-string
includevalues inpyproject.toml.T-strings in docstring position are no longer treated as docstrings.
Security 2
Black: Arbitrary file writes from unsanitized user input in cache file name
Black is the uncompromising Python code formatter. Black provides a GitHub action for formatting code. This action supports an option, use_pyproject: true, for reading the version of Black to use from the repository pyproject.toml. A malicious pull request could edit
New APIs and options 6
Adds a command-line option to configure the cache directory.
GitHub Action runs expose the
is_formatted,change_count,same_count, andfailure_countoutputs.GitHub Action runs expose the
is_formatted,change_count,same_count, andfailure_countoutputs.GitHub Action runs expose the
is_formatted,change_count,same_count, andfailure_countoutputs.GitHub Action runs expose the
is_formatted,change_count,same_count, andfailure_countoutputs.The environment variable disables ANSI output.
Performance 6
Avoids quadratic runtime when splitting very long lines with many trailing bracket pairs.
Fixes superlinear runtime growth as the number of input files increases.
Improves performance on long calls and collections, soft keywords, semicolon-separated statements, deeply nested expressions, and compound statements with many clauses.
Improves performance on files with many sibling blocks.
Release binaries are smaller because debug symbols are stripped during the PyInstaller release build.
Improves performance on strings with many consecutive backslashes, multiline strings in large collections, and several string-processing operations.
Behavior and default changes 5
Preview style avoids unnecessary parentheses around unbreakable right-hand-side expressions, including in annotated assignments and subscript targets.
Validates line-range values.
Preview style enforces a blank line after a function or method with a docstring-only body when another comment or statement follows.
Unstable style splits long stringified return annotations even when the function has parameters.
The GitHub Action supports PEP 440 version specifiers for
tool.black.required-version.
Tooling 4
Keeps parentheses around a lambda used as the iterable of a comprehension.
Reports parser failures using editor-friendly
path:line:columnlocations.Preview style normalizes uppercase
Tprefixes to lowercase.Preview style parenthesizes tuple expressions for consistency with function calls and returns.
Fixes and other changes 38
Black no longer moves an encoding declaration onto the first two lines of a file.
Fixes the action crashing on dependency-group includes when
use_pyprojectis enabled.Black respects
.gitignorefiles that start with a UTF-8 byte order mark, so the first pattern matches and ignored files are not formatted.Long notebook assignment magics such as
x = !ls -laare left unchanged instead of being wrapped in parentheses that IPython can no longer run.Formatting now handles lines following a statement when that statement is joined or re-indented.
Formatting no longer crashes when an unselected statement has a
# fmt: skipcomment before a closing bracket.Files formatted or checked with selected line ranges are no longer cached as formatted, preventing later full checks from passing or skipping unformatted lines.
Black no longer adds an extra trailing blank line inside a multi-line module docstring when its last line is near the line length limit.
The unstable feature no longer removes backslash-newline sequences from raw strings and changes their value.
The unstable feature no longer adds a space after
*or**in a PEP 695 type parameter when splitting a string in its default.Preview style avoids unnecessary line splits of trailers when an earlier bracket split exceeds the line length only because of a trailing comment.
The feature no longer drops parentheses around a right-hand side containing a dictionary and leaves the line over the length limit.
Keeps parentheses around annotated-assignment targets, preserving their effect on
__annotations__.Invalid worker values are reported as usage errors instead of causing a crash.
Fixes crashes on standalone comments between tokens and preserves inline comments on brackets inside comprehensions.
When sources share no common project root, Black falls back to the default configuration with a warning instead of crashing.
Fixes multiline indentation with leading tabs and prevents form feeds or similar characters from becoming newlines.
Preserves blank lines immediately before a
# fmt: oncomment.Fixes formatting and crashes involving skipped bracketed expressions, PEP 695 declarations, headers, comments, and one-line statements.
Correctly excludes files whose paths contain
..when invoked from a subdirectory.Stops converting form feeds and similar characters in docstrings into newlines.
Preview style removes redundant parentheses around generator expressions.
Fixes misplaced or dropped inline comments around optional parentheses, comprehensions, and bracketed expressions.
Fixes parsing assignment magics when non-ASCII characters occur earlier on the line.
No longer inserts an empty line after a docstring when the range covers only the docstring, and preserves comments and blank lines outside requested ranges.
Respects the magic trailing comma in PEP 695 type parameter lists containing a
*TypeVarTupleor**ParamSpec.Fixes crashes when splitting
case case if ...patterns at very small line lengths.Stops dropping trailing commas from split single-element tuple lambda defaults and one-element subscripts.
Preserves CRLF endings on the skipped line instead of turning them into
\r\r\n.Avoids a crash when writing formatted code or diffs to a stdout without a
bufferattribute.Fixes unparseable output when a t-string replacement field contains a quote.
No longer emits a spurious warning when the runtime version is included in the flag.
Fixes unparseable output when the string body ends in an already-escaped double quote.
Preview style removes redundant parentheses around individual variables in unpacking targets.
Blackd returns HTTP 400 for an empty header or empty entry, and accepts optional whitespace around comma-separated versions and
pyi.Fixes unstable formatting when a subscript annotation contains an inline comment.
Corrects the version reported by published executables.
Preserves inline comments immediately before a
# fmt: skipline, avoiding AST equivalence failures.