Ruff 2026 Style Guide

[dylwil3]

From Black's changelog and Preview enum. Last checked 19.09.2025, Last release: v25.9.0.

Goals:

• Close parity with Black when migrating from Black to Ruff
• Fix Ruff specific bugs
• Innovate on local formatting (to keep close parity with black)

Preview Styles

Stabilized in Black and not available in Ruff (even in preview)

• remove_lone_list_item_parens
• Allow newlines after block open (or not) #9745 -- progress towards this here Allow newlines after function headers without docstrings #21110

Black preview styles

• wrap_long_dict_values_in_parens Non-goal, see Preview style feedback: Parenthesizing long dict, conditional, and type annotations psf/black#4123 and Nested expression formatting #12856
• always_one_newline_after_import This is enforced by unsorted-imports (I001) and configurable via lines-after-imports. There is already some small conflict with the formatter depending on how the user configures this, and this may cause a little more. Unsure about this one...
• fix_fmt_skip_in_one_liners Respect fmt: skip for compound statements on single line #20633
• wrap_comprehension_in
  • [WIP] Implement the wrap_comprehension_in preview style from Black #21005
• remove_parens_around_except_types
  • Remove parentheses around multiple exception types on Python 3.14+ #20768
• normalize_cr_newlines Already handled by Ruff Ruff 2026 Style Guide #20482 (comment)

Black unstable styles

• string_processing Non-goal, various issues https://github.com/psf/black/issues?q=is%3Aissue%20state%3Aopen%20string_processing
• hug_parens_with_braces_and_square_brackets Note this is already implemented as a Ruff preview feature (see below). So marking this as "done" here, and deferring to the below list for whether to stabilize. See also format: different behavior with black for hug_parens_with_braces_and_square_brackets and generators #11375
• multiline_string_handling According to 2025 issue: "non goal. Maybe a simplified version of it that only joins implicitly concatenated strings"

Ruff preview styles

Ruff specific preview styles that we may want to stabilize

• hug_parens_with_braces_and_square_brackets
• no_chaperone_for_escaped_quote_in_triple_quoted_docstring
• blank_line_before_decorated_class_in_stub

Ruff improvements

Open Bugs

Existing bugs in the ruff formatter for which no preview style exists.

Require a new style guide

Bug fixes that change how existing code is formatted and require a breaking change.

• Unnecessary parantheses to long patterns with as captures Avoid extra parentheses for long match patterns with as captures #21176
• Dict key split to multiline (deviation from black)
• Ruff splits subscript targets instead of parenthesizing the value
• Handling of blank lines between module docstring and a comment (unclear if it requires a new style guide) @konstin
• Parenthesize assignment values that fit into the line length
• Handle over-long lambda expressions (possibly requires a new style guide)

Bug fixes that don't change existing formatting

Bug fixes that don't require a new style guide because they don't change existing code

• Range formatting does not handle whitespace before new classes
• Formatter inserts trailing newline at the end of a file even when inside a fmt: off region
• Parenthesized expression with comment on right hand side in assignment produces invalid syntax
• Fuzzer: comment in middle of operand causes panic
• Not respecting fmt: skip (possibly related to fix_fmt_skip_in_one_liners Black preview style)
• Preserve trailing whitespace in docstring examples
• Incorrect docstring code block formatting for statement sequences
• Handling of empty lines after ;
• Suppressing statement sequences
• Using fmt:skip to suppress compound statements
• Fuzzer: debug assert on dangling comments failed
  • [ruff] improve handling of intermixed comments inside from-imports #20561

[s-banach]

Ruff specific preview styles that we may want to stabilize

• hug_parens_with_braces_and_square_brackets

I have been using ruff format with preview = true since 2023, just for this one feature.
The only reason I'm reading this issue is to see whether it will be stabilized.

[MeGaGiGaGon]

ruff already has the behavior from normalize_cr_newlines. I guess it was technically a formatting deviation before? But like usual no one noticed because dealing with newlines is so annoying.

Demonstrating difference

Input code powershell escaped: "a`rb`nc`r`n#1"
Input code backslash escaped: a\rb\nc\r\n#1\r\n

Formatter	Escaped Output
Black 25.9.0 no preview	a\nb\nc\n# 1\n
ruff format	a\rb\rc\r# 1\r
Black 25.9.0 preview	a\rb\rc\r# 1\r

Input code without visible newlines:

a
b
c
#1

Input code with written out newlines:

a<cr>
b<nl>
c<cr><nl>
#1<cr><nl>

Where the #1 at the end is to cause the reformatting.

PS ~\Desktop\New_folder>Set-Content issue.py "a`rb`nc`r`n#1"
PS ~\Desktop\New_folder>Get-Escaped-Content issue.py
a\rb\nc\r\n#1\r\n
PS ~\Desktop\New_folder>uvx black issue.py
reformatted issue.py

All done! ✨ 🍰 ✨
1 file reformatted.
PS ~\Desktop\New_folder>Get-Escaped-Content issue.py
a\nb\nc\n# 1\n
PS ~\Desktop\New_folder>Set-Content issue.py "a`rb`nc`r`n#1"
PS ~\Desktop\New_folder>uvx ruff format issue.py
1 file reformatted
PS ~\Desktop\New_folder>Get-Escaped-Content issue.py
a\rb\rc\r# 1\r
PS ~\Desktop\New_folder>Set-Content issue.py "a`rb`nc`r`n#1"
PS ~\Desktop\New_folder>uvx black issue.py --preview
reformatted issue.py

All done! ✨ 🍰 ✨
1 file reformatted.
PS ~\Desktop\New_folder>Get-Escaped-Content issue.py
a\rb\rc\r# 1\r

Where Get-Escaped-Content is a custom powershell function specifically to help deal with these annoying newlines:

function Get-Escaped-Content {
	param (
		$Path
	)
	return Get-Content $Path -Raw | ForEach-Object { $_ -replace "\n", "\n"} | ForEach-Object { $_ -replace "\r", "\r"}
}

[MichaReiser]

For reference the tracking issue for the 2025 style guide.

• It was an intentional decision not to implement https://github.com/psf/black/pull/3440 because of Nested expression formatting #12856.
• The unstable styles are styles that black doesn't consider "ready" yet because of bugs. We should focus on the preview sytles first (but it's good to work on unstable styles in case black fixes all remaining issues and promotes them to preview and then stable)
• multiline_string_handling: Ruff now automatically joins implicitly concatenated strings. That's as far as we want to go for now.
• I'm not sure what string_processing is
• We should consider implementing and shipping Allow newlines after block open (or not) #9745 (requires some design, maybe there's a middle ground that we dont' need to go as far as black)
• There are also some black 2025 style changes that we didn't implement, see [formatter]: Black 2025 style guide differences #15927

@vlkorsakov is there a specific change that you dislike or do you dislike style changes in general?

[MeGaGiGaGon]

Ruff already has part of string_processing in that short string literals will be merged . Also part of it is splitting long string literals, see the docs for more info, but string_processing is almost certainly going to remain unstable for 2026. See the 2024 Black Stable Style issue psf/black#4042 for more details, but there are still many outstanding serious issues https://github.com/psf/black/issues?q=is%3Aissue%20state%3Aopen%20string_processing . (But it also won't be removed since there are a ton of people that like it, so it's stuck in a difficult place)

[dylwil3]

It looks like the preview style wrap_comprehension_in also results in quite a few added parentheses: https://github.com/psf/black/blob/903bef54aa72e111c034ccec9997aac82bafbacc/tests/data/cases/preview_wrap_comprehension_in.py

So we may get into a similar situation as with #12856

[MichaReiser]

Black published a new release today and they moved multiline_string from unstable into preview. We should double check how their multiline string handling differs from our (I might have confused it with the string_processing unstable style)

[ntBre]

I tried updating our Black tests again, and the only changes to the multiline string styles were from this PR: psf/black#4760, deleting some of the cases that I think do relate more to string_processing. So our preview_multiline_strings snapshot should still accurately reflect how closely we match Black.

Mostly it looks like we insert more breaks around multiline strings:

ruff/crates/ruff_python_formatter/tests/snapshots/black_compatibility@cases__preview_multiline_strings.py.snap

Lines 336 to 345 in deeda56

	call(
	3,
	{"dog", "say"},
	- textwrap.dedent("""pig
	- oink""" % "cowabunga"),
	+ textwrap.dedent(
	+ """pig
	+ oink"""
	+ % "cowabunga"
	+ ),

[hauntsaninja]

Does ruff have anything planned for #12856 ? Especially curious about parenthesize_conditional_expressions , I get asked about that at work sometimes

[MichaReiser]

I tried updating our Black tests again, and the only changes to the multiline string styles were from this PR

I see. I suggest we wait then. Ruff uses some heuristics to preserve the indent for multiline strings to reduce the diff compared to the old style guide and I remember that it was a main concern for Black when they considered stabilizing in previous years. We can always follow along next year if the change works well for Black.

Does ruff have anything planned for #12856 ? Especially curious about parenthesize_conditional_expressions , I get asked about that at work sometimes

Unfortunately not. I very much hope that we'll have more dedicated time to improve Ruff's style guide next year. Shipping #12856 probably also requires formatter editions (that are independent of the ruff version), because I expect the diff compared to the current style guide to be rather large. You can upvote (or comment on) #12856 or #9722 specifically. This would help us prioritize the work next year.