Introduction

Black is intentionally opinionated: it formats entire files so teams do not argue about style. That design means you usually cannot tell Black to leave one complicated expression alone unless you opt out at the line or block level.

What Black Can and Cannot Ignore

Black is not built around many custom formatting rules. In practice, you get three useful choices:

1. Let Black format the code normally.
2. Skip one line with # fmt: skip.
3. Skip a whole region with # fmt: off and # fmt: on.

That is the important mental model. If you want Black to preserve a hand-aligned multi-line expression inside an otherwise normal block, there is no fine-grained setting for that pattern. You either accept Black's output or mark a line or region as excluded.

Here is a small example. Black will normally collapse and re-wrap this call according to its own rules:

result = some_function(
    first_argument, second_argument, third_argument, fourth_argument
)

If you truly need to preserve a custom layout, wrap the region with formatter directives:

1# fmt: off
2result = some_function(
3    first_argument,
4    second_argument,
5    third_argument,
6    fourth_argument,
7)
8# fmt: on

Black will leave that block alone when it runs.

Using # fmt: skip for a Single Line

For isolated cases, # fmt: skip is the smallest escape hatch. It is useful when a single assignment or literal is clearer in a custom layout and you do not want to exclude a larger block.

query = "SELECT id, created_at, updated_at FROM audit_log"  # fmt: skip

Be careful with this pattern. It only applies to the line where the comment appears. If the code spans several physical lines, # fmt: skip is usually not enough, and a fmt: off block is clearer.

Using # fmt: off and # fmt: on for Multi-Line Code

A block directive is the standard answer for generated code, carefully aligned tables, or rare formatting that communicates structure better than Black's default output.

1# fmt: off
2MIGRATION_COLUMNS = [
3    ("users",      "email",      True),
4    ("profiles",   "timezone",   False),
5    ("sessions",   "expires_at", True),
6]
7# fmt: on

This approach works well when the layout itself carries meaning. It should still be rare. Once a file contains many ignored regions, the team loses the consistency Black was meant to provide.

Prefer Refactoring Over Opting Out

In many cases, the need to preserve formatting is a hint that the code should be reorganized. Black often exposes overly dense expressions, long argument lists, or data that belongs in a separate structure.

For example, instead of freezing a hard-to-read constructor call, move the data into a dictionary or helper variable:

1payload = {
2    "user_id": user_id,
3    "include_archived": include_archived,
4    "max_results": 100,
5}
6
7response = fetch_report(payload)

This is usually easier to maintain than protecting a custom arrangement with formatter directives.

You can also configure Black at the project level for the parts it does support, such as line length:

[tool.black]
line-length = 100
target-version = ["py311"]

A slightly wider line length sometimes removes the urge to bypass formatting in the first place.

When Ignoring Code Is Reasonable

A small number of exceptions are defensible:

• Generated code that should not be edited by hand.
• Data tables where vertical alignment improves scanning.
• Embedded examples copied from documentation or standards.
• Temporary migrations where readability depends on stable column layout.

Even then, keep the ignored region narrow. A short protected block is easier to review than an entire file hidden behind fmt: off.

Common Pitfalls

The most common mistake is expecting Black to support selective formatting rules like "leave this one multi-line call unchanged." It does not work that way. The fix is to use # fmt: off and # fmt: on, or to restructure the code so Black's output is acceptable.

Another problem is forgetting to turn formatting back on. If # fmt: on is missing, a much larger part of the file may stop being formatted. Keep the off-region as short as possible and review the diff carefully.

Teams also overuse formatter escapes for style preferences that do not matter. If the code is not generated and the layout does not carry real meaning, accepting Black's default output is usually the better choice.

Summary

• Black does not offer detailed per-pattern ignore rules for multi-line code.
• Use # fmt: skip for a single line and # fmt: off with # fmt: on for a block.
• Prefer refactoring dense code before opting out of formatting.
• Keep ignored regions small so the rest of the file stays consistent.
• Project settings like line length can reduce the need for formatter escapes.