skip to content

In Clippy, which lint groups are off by default, and how should a Rust team adopt the `pedantic` and `restriction` groups?

level: middleimportance: should knowfreq 40%

answer

  1. four groups stay at allow
  2. pedantic whole, then opt out
  3. restriction lint by lint
  4. a group that contradicts itself
  5. thresholds live in clippy.toml

basics

~20 s

Clippy's pedantic, nursery, restriction and cargo groups are allow-by-default. Teams enable pedantic as a group at a lower priority and allow the lints they reject, but pick restriction lints one at a time, because that group contradicts itself.

solid answer

~40 s

`cargo clippy` runs `clippy::all`: correctness (deny) plus suspicious, style, complexity and perf (warn). Four groups stay at allow: `pedantic` (strict, with occasional false positives), `nursery` (lints still in development), `restriction` (lints that forbid ordinary features, such as `unwrap_used` or `dbg_macro`) and `cargo` (manifest checks such as `multiple_crate_versions`). Pedantic is meant to be enabled whole: in the `[lints.clippy]` table (Cargo 1.74 and later) write `pedantic = { level = "warn", priority = -1 }` and allow the few you disagree with, such as `must_use_candidate`. Restriction is not: enabling it as a group trips Clippy's own `blanket_clippy_restriction_lints` warning, and it holds opposites such as `separated_literal_suffix` and `unseparated_literal_suffix`. Choose the restriction lints that encode a real team rule. Numeric knobs such as `too-many-arguments-threshold` (default 7) go in `clippy.toml`.

code

toml · 10 lines
toml
[package]
name = "grp"
version = "0.1.0"
edition = "2024"

[lints.clippy]
pedantic = { level = "warn", priority = -1 }
must_use_candidate = "allow"
unwrap_used = "warn"
dbg_macro = "deny"

go deeper

for a junior

Recall the nine groups, which five run by default, and that correctness is the only one denied.

for a middle

Explain why pedantic is enabled whole at priority -1 with named exceptions, while restriction lints are picked one by one, and where thresholds such as too-many-arguments-threshold live.

for a senior

Show judgement on which restriction lints encode real rules for this codebase (unwrap_used in a service, dbg_macro in a library) and how you roll a group out without a flood of warnings.

for a principal

Weigh lint strictness against review friction: every enabled lint costs allows and argument, so a lead adds lints that prevent real defects and drops ones that only enforce taste.

## The groups and their defaults Every Clippy lint is declared in one **category**, and each category is also a lint group you can set a level for. Running `cargo clippy` with no configuration enables `clippy::all`, which is the five default categories: | group | default | contents | |---|---|---| | `clippy::correctness` | deny | code that is outright wrong or useless | | `clippy::suspicious` | warn | code that is most likely wrong | | `clippy::style` | warn | code that could be more idiomatic | | `clippy::complexity` | warn | simple things done in a complex way | | `clippy::perf` | warn | code that could run faster | | `clippy::pedantic` | allow | strict lints with occasional false positives | | `clippy::nursery` | allow | new lints still under development | | `clippy::restriction` | allow | lints that forbid ordinary language and library features | | `clippy::cargo` | allow | lints for the Cargo manifest | The four allow-by-default groups exist for different reasons, so a team adopts each one differently. ## Pedantic: opt in wholesale, opt out by name Clippy's own documentation calls pedantic ready for production use, with the warning that you can expect to sprinkle some `#[allow]`s. Clippy lints itself with the whole group. The usual adoption is: 1. Enable the group in the manifest's `[lints.clippy]` table at a **lower priority**: `pedantic = { level = "warn", priority = -1 }`. 2. Run `cargo clippy` and read what fires. Typical hits are `cast_possible_truncation`, `missing_panics_doc`, `must_use_candidate` and `doc_markdown`. 3. Fix what is worth fixing and allow, by name, the lints the team rejects, for example `must_use_candidate = "allow"`. The priority matters because Cargo ignores the order of keys in the table: a group and a single lint at the same priority is ambiguous, and Clippy's deny-by-default `lint_groups_priority` lint rejects it. A group at `-1` is passed first and the named exceptions at the default `0` override it. ## Restriction: cherry-pick, never the whole group Restriction lints are not "stricter style". Each one forbids something that is perfectly fine in general but that a particular codebase may want to ban: - `unwrap_used` and `expect_used` for a service that must never panic on bad input; - `dbg_macro`, `todo` and `print_stdout` to keep debugging leftovers out of a library; - `undocumented_unsafe_blocks` to require a `// SAFETY:` comment on every `unsafe` block; - `indexing_slicing` for code where an out-of-bounds index must be a handled error. Enabling the whole group is self-defeating. Clippy reports ``clippy::restriction` is not meant to be enabled as a group`` through the warn-by-default `blanket_clippy_restriction_lints`, and the group contradicts itself and the defaults: - `unseparated_literal_suffix` wants `4_u32`, while `separated_literal_suffix` wants `4u32`; - `implicit_return` wants an explicit `return`, while the warn-by-default `needless_return` removes it. ## Nursery and cargo - **Nursery** lints are unfinished: they may have false positives or change behaviour from release to release. Enable one deliberately if it catches something you care about, and expect to revisit it after a toolchain bump. - **Cargo** lints read the manifest and dependency graph: `multiple_crate_versions` reports duplicate versions, `wildcard_dependencies` flags `"*"` requirements, `cargo_common_metadata` asks for publishing metadata. They suit a library about to be published more than an application. ## Tuning with `clippy.toml` Some lints take parameters, and those live in `clippy.toml` (or `.clippy.toml`), not in `Cargo.toml`: - `too-many-arguments-threshold` (default 7) for `too_many_arguments`; - `too-many-lines-threshold` (default 100) for the pedantic `too_many_lines`; - `msrv`, which defaults to the package's `rust-version`, so Clippy does not suggest APIs newer than the version you support; - list options such as `disallowed-names`, where `".."` extends the default list instead of replacing it. Clippy looks for the file in `CLIPPY_CONF_DIR`, then `CARGO_MANIFEST_DIR`, then the current directory, walking up parent directories from the first of those that is set. Its documentation marks the file format as unstable and possibly deprecated in future, so keep it small. ## A rollout order that works 1. Get the default groups clean first. 2. Add pedantic at `priority = -1` and allow what the team rejects. 3. Add the restriction lints that match written team rules, one per line. 4. Promote warnings to errors in CI only once the codebase is clean.

  • Why does the `[lints.clippy]` example give `pedantic` a priority of -1?
    Cargo sorts lint entries by `priority` and ignores the order you wrote them in. At equal priority, a group and a lint inside it are ambiguous, so Clippy's deny-by-default `lint_groups_priority` fails the run. With the group at -1, Cargo passes it first and the named exceptions at the default 0 override it.
  • A team adds `too-many-arguments-threshold = 4` to a new `clippy.toml`, but `cargo clippy` reports nothing new; what is going on?
    Clippy records `clippy.toml` as an input of a crate only when it loaded the file, so creating the file for the first time does not invalidate crates Cargo has already checked: cargo 1.99.1 replayed the old result. Touch a source file or run `cargo clean -p` for the package; after that, edits to the file trigger a re-check on their own.

  • Enabling clippy::restriction as a whole is the strictest and best setting
  • Pedantic lints are too noisy to ever enable as a group
  • Clippy's numeric thresholds are set in the [lints.clippy] table
  • The cargo group checks Rust code style, not the manifest
  • Nursery lints are stable and safe to deny in CI

Assumes Cargo 1.99 with Clippy 0.1.99; the [lints.clippy] manifest table used to adopt groups is stable since Cargo 1.74.