Ruff Format vs Black: Is It Really a Drop-in Replacement?

ruff format is Ruff's code formatter — the counterpart to ruff check (the linter). It's deliberately modeled on Black: the same opinionated, low-config philosophy, the same 88-column default line length, the same general style. The difference is that it's written in Rust and built into the same binary that lints, so one tool covers formatting *and* linting *and* import sorting instead of three.

The design goal Astral set was explicit: ruff format should be Black-compatible, so teams can adopt it without re-formatting the world. The question is how well that goal holds up on real code — so I measured it.

I formatted the same 124 files (Flask + Rich source) two ways — once with Black, once with ruff format — then diffed the two output trees. Here's what came back:

formatting 124 files with each tool...
black        : 4.86 s
ruff format  : 0.17 s

17 files differ / 124 total
identical: 107

Two takeaways. First, 86% of files were exactly the same — for most code, Black and ruff format are indistinguishable. Second, ruff format did the whole job in 0.17 s versus Black's 4.86 s — about 29× faster. That speed gap is the same story as the rest of Ruff: native Rust versus a Python program, and it compounds across a big repo and every save in your editor.

The honest, useful part: I looked at every differing file, and none of the disagreements are bugs. They're cases where Black and Ruff make different — but equally valid — style choices. Two patterns covered almost all of them.

1. How a long `assert` message wraps. Black keeps the message on the assert line and wraps the condition; Ruff wraps the message into parentheses. Both are legal; Ruff's is the newer convention:

-  assert (
-      bool(static_host) == host_matching
-  ), "Invalid static_host/host_matching combination"
+  assert bool(static_host) == host_matching, (
+      "Invalid static_host/host_matching combination"
+  )

2. f-string quote normalization. When an f-string contains nested quotes, Ruff and Black pick opposite outer/inner quote pairings. Again — same string, different valid formatting:

-  f'{getattr(type_, "__module__", "")}.{getattr(type_, "__qualname__", "")}'
+  f"{getattr(type_, '__module__', '')}.{getattr(type_, '__qualname__', '')}"

The rest were occasional blank-line handling at file edges. That's the whole story of the 14% — cosmetic tie-breaks, often because Ruff tracks the newest formatting conventions slightly ahead of Black. Nothing that changes behavior, nothing that should block a migration.

Like Black, ruff format is intentionally low-config — but it exposes the knobs that matter. The two you'll actually touch are quote style and line length. Both worked exactly as expected in my tests:

# default: double quotes
name = "world"

# with format.quote-style = "single"
name = 'world'

# ruff format --config "line-length = 20"
result = some_function(
    argument_one,
    argument_two,
    argument_three,
)

In a project you'd set these once in pyproject.toml under [tool.ruff] (line-length) and [tool.ruff.format] (quote-style, indent-style). That's the whole configuration surface most teams need — the point of an opinionated formatter is that you *don't* tune it endlessly.

You don't have to install anything to try ruff format. Our Ruff formatter online runs the official Ruff WebAssembly build in your browser: paste code, switch to Format mode, set your line length and quote style, and see the reformatted output instantly — the same engine and output you'd get from ruff format locally, with nothing uploaded.

When you're ready to adopt it for real: install Ruff (pip install ruff or uv add ruff), set your line-length and quote-style in pyproject.toml, run ruff format . once to apply it across the repo in a single commit, then drop Black from your dev dependencies and point your pre-commit hook and CI at ruff format --check. Because it's 86% identical out of the box, the one-time reformat diff is small — and every format after that is ~29× faster.