Rustfmt Configuration and Formatting Checks in CI Explained

Formatting arguments are the cheapest ones to prevent. rustfmt has one canonical output, nearly everyone in the Rust community uses it, and a CI check keeps the code in that shape. The configuration file is mostly a place to resist the urge to tweak. This post covers the command, the few stable options and the CI line. It belongs with Clippy and lints in Cargo.toml.

Rust 1.90, rustfmt bundled.

Commands

cargo fmt                      # format the package
cargo fmt --all                # every workspace member
cargo fmt --all -- --check     # exit code 1 and a diff if anything changes

A formatting failure in CI prints the diff:

Diff in src/main.rs:3:
-fn main(){println!("hi")}
+fn main() {
+    println!("hi")
+}

The fix is to run cargo fmt locally and commit. Pin the toolchain with rust-toolchain.toml, because rustfmt output can differ slightly between releases.

The file

max_width = 100
use_small_heuristics = "Max"

Both are stable options. max_width defaults to 100 and use_small_heuristics = "Max" lets short structs and calls fit on one line. Edition and style edition come from Cargo.toml; the 2024 edition ships a new style edition with small formatting changes, such as how version sorting treats names in use lists.

Options to leave alone

Tempting settings like imports_granularity, group_imports and wrap_comments are unstable and work only with cargo +nightly fmt. If half the team formats with stable and half with nightly, every pull request flips lines. Either run nightly rustfmt for everyone, through a pinned nightly in CI, or skip these options. For import order, accept the default and let rust-analyzer's "organize imports" do the grouping by hand.

Skipping

#[rustfmt::skip]
const TABLE: [[u8; 3]; 3] = [
    [1, 0, 0],
    [0, 1, 0],
    [0, 0, 1],
];

The attribute leaves that item alone. Use it for tables and bit patterns where alignment carries meaning. Skipping a whole function because the formatter makes it ugly is a sign the function should be smaller.

In an editor

With rust-analyzer, format on save calls rustfmt on the file. Check rust-analyzer setup for the setting. Pre-commit hooks that run cargo fmt --check catch problems before CI, which matters when CI queues are slow.

Generated code

Add paths to ignore in rustfmt.toml (an unstable option) or keep generated files out of the workspace's source tree and include them with include! from OUT_DIR, which rustfmt does not touch. Build scripts writing to OUT_DIR produce exactly this layout.

Limits

Rustfmt does not reflow comments or macro bodies it cannot parse. Macro invocations with unusual syntax are left as written. The options are listed on the rustfmt configuration page, with each marked stable or unstable.