skip to content

In Rust 1.81 and later, how does `#[expect(clippy::needless_range_loop)]` differ from `#[allow(clippy::needless_range_loop)]`, and when does it warn?

level: middleimportance: should knowfreq 30%

answer

  1. a suppression that can go stale
  2. an expectation must be fulfilled
  3. unfulfilled_lint_expectations
  4. reason documents why
  5. allow_attributes nudges toward expect

basics

~20 s

Both silence the named lint, but #[expect] also asserts that the lint fires there. When the code changes and the lint stops firing, rustc warns with unfulfilled_lint_expectations, so a stale suppression surfaces instead of lingering like a forgotten #[allow].

solid answer

~40 s

`#[allow(lint)]` and `#[expect(lint)]` (stable since Rust 1.81) both suppress the lint on the item they annotate. The difference is what happens when the lint no longer fires: an `#[allow]` stays silently, while an `#[expect]` becomes an unfulfilled expectation and rustc emits the warn-by-default `unfulfilled_lint_expectations` at the attribute. That turns each suppression into a checked claim: after a refactor removes the index loop, the `#[expect(clippy::needless_range_loop)]` above it starts warning, and with warnings denied in CI the stale attribute fails the job. Both accept `reason = "..."`. An expectation on a Clippy lint is evaluated only when Clippy runs, so plain `cargo build` reports nothing for it. A team that wants `#[expect]` everywhere can enable the restriction lint `clippy::allow_attributes`, which flags each `#[allow]` and suggests `expect`.

code

rust · 18 lines
rust
#[expect(clippy::needless_range_loop, reason = "index also used for the offset")]
pub fn sum_offsets(values: &[u32]) -> u32 {
    let mut total = 0;
    for i in 0..values.len() {
        total += values[i] + u32::try_from(i).unwrap_or(0);
    }
    total
}

#[expect(clippy::needless_range_loop)]
pub fn sum(values: &[u32]) -> u32 {
    values.iter().sum()
}

#[allow(clippy::len_zero)]
pub fn is_empty(values: &[u32]) -> bool {
    values.is_empty()
}

go deeper

for a junior

Recall that #[allow] and #[expect] both silence a lint, and that #[expect] warns when there was nothing to silence.

for a middle

Explain how an expectation is fulfilled, that unfulfilled_lint_expectations is warn-by-default, and that Clippy expectations are checked only under cargo clippy.

for a senior

Show how you use expect with reason to keep suppressions honest across refactors and toolchain bumps, and how allow_attributes enforces the habit in review.

for a principal

Frame local suppressions as debt with an expiry date: a rule that every exception uses expect with a reason keeps the lint policy credible as the codebase grows.

## Lint levels written in the source Rust code can change a lint's level for one item, one module or the whole crate with an attribute. The Reference lists five: - `#[allow(C)]` leaves violations of lint `C` unreported; - `#[expect(C)]` expects `C` to be emitted: it suppresses the lint, or warns if the expectation is unfulfilled; - `#[warn(C)]` reports violations as warnings; - `#[deny(C)]` reports them as errors; - `#[forbid(C)]` is `deny` that also forbids lowering the level later, including with `allow` or `expect`. `C` can be a rustc lint (`unused_variables`), a Clippy lint (`clippy::needless_range_loop`) or a group (`unused`, `clippy::pedantic`). Every one of these attributes takes an optional `reason = "..."`, which documents the decision in the code and is shown with the lint message if the lint is emitted at that level. ## What `#[expect]` adds `#[expect]` was stabilised in **Rust 1.81**. It works in three steps: 1. Inside the annotated item it suppresses lint `C`, exactly as `#[allow(C)]` would. 2. It records an **expectation** that `C` would have been emitted there. 3. If nothing in the item would have triggered `C`, the expectation is **unfulfilled** and rustc emits `unfulfilled_lint_expectations` (warn-by-default) pointing at the attribute. The practical effect is that suppressions cannot rot. An `#[allow]` added for a false positive two years ago stays forever, even after the code it excused is gone. An `#[expect]` complains the moment it no longer has anything to suppress. ## A worked example The snippet below has three functions under `cargo clippy`: | function | attribute | what Clippy 0.1.99 reports | |---|---|---| | `sum_offsets` | `#[expect(clippy::needless_range_loop, reason = ...)]` | nothing: the loop triggers the lint, the expectation is fulfilled and the lint is suppressed | | `sum` | `#[expect(clippy::needless_range_loop)]` | `warning: this lint expectation is unfulfilled`, because the body has no index loop | | `is_empty` | `#[allow(clippy::len_zero)]` | nothing, although the body no longer contains `len() == 0` | The third row is the case `#[expect]` was invented for: the `#[allow]` is stale and nothing tells you. ## Edge cases worth knowing - **Only the expecting attribute fulfils it.** If an inner `#[allow(C)]` or `#[warn(C)]` handles the lint first, the outer expectation stays unfulfilled. - **Groups.** `#[expect(unused)]` is fulfilled when any lint in the `unused` group fires inside the item. - **Several lints.** `#[expect(a, b)]` creates one expectation per lint, and each can be unfulfilled on its own. - **Clippy lints and plain builds.** rustc does not run Clippy's lints, so under `cargo build` an `#[expect(clippy::...)]` is neither fulfilled nor reported; the check happens only in `cargo clippy`. Run Clippy in CI or stale Clippy expectations go unnoticed. - **`forbid` wins.** Inside `#[forbid(C)]`, writing `#[allow(C)]` or `#[expect(C)]` is itself an error, E0453 (`expect(unused_variables) incompatible with previous forbid`). ## Attribute or manifest? Lint levels can be set in two places, and they answer different needs: | need | where to set it | |---|---| | a rule for the whole crate or workspace | the `[lints]` table in `Cargo.toml` | | one exception on one item | `#[expect(lint, reason = "...")]` on that item | | a whole generated module exempted | `#[allow(...)]` or `#[expect(...)]` on the module | | a level nobody may lower | `forbid` in the `[lints]` table or an attribute | The `[lints]` table cannot express an expectation: it only takes the levels `forbid`, `deny`, `warn` and `allow`. Expectations are always attributes, placed where the exception lives, which is also where a reviewer reads the reason. ## Using it in a codebase - Prefer `#[expect(lint, reason = "...")]` for every local suppression, so each one states why it exists and disappears when it no longer applies. - Keep crate-wide policy in the `[lints]` table of `Cargo.toml`; attributes are for the local exceptions. - To enforce the habit, enable the restriction lints `clippy::allow_attributes`, which flags each `#[allow]` with `help: replace it with: expect`, and `clippy::allow_attributes_without_reason`, which demands a `reason` on both kinds. - With warnings denied in CI, an unfulfilled expectation fails the job, which is what turns a toolchain bump that fixes a false positive into a prompt to delete the attribute.

  • Why might an `#[expect]` on a Clippy lint that passed for months start warning after a toolchain bump?
    If the new Clippy fixes a false positive, the lint no longer fires on that code, so the expectation is unfulfilled and `unfulfilled_lint_expectations` warns. That is the point: the attribute was excusing a bug in the lint, and it can now be deleted. With warnings denied in CI it fails the job until you remove it.
  • Does an outer `#[expect(unused_variables)]` on a function count as fulfilled when an inner `#[allow(unused_variables)]` silences the variable?
    No. An expectation is fulfilled only by lint emissions that the `expect` itself suppressed. The inner `allow` handled the lint first, so the outer expectation stays unfulfilled and rustc warns at it.

  • #[expect] makes the lint an error when it fires
  • An #[allow] warns once the code it excused has been removed
  • Plain cargo build reports a stale #[expect] on a Clippy lint
  • #[expect] can lower a lint that a surrounding #[forbid] set
  • #[expect] needs a nightly toolchain on current Rust

Assumes Rust 1.99; #[expect] and the unfulfilled_lint_expectations lint are stable since Rust 1.81.