When the compiler says yes but the code feels wrong
You run cargo build. Zero errors. Zero warnings. The terminal returns to the prompt. You feel confident. Then you review the diff and spot a manual loop where .map() exists, an unwrap() that could panic on bad input, and a function taking five arguments when a struct would be cleaner. The compiler checked syntax and types. It didn't check idioms.
Clippy fills that gap. It is a linter that knows Rust's collective wisdom. It catches mistakes the compiler ignores, flags inefficient patterns, and nags you about style until you write code that looks like it came from the standard library. Clippy doesn't replace the compiler. It extends it with hundreds of rules written by the community.
What Clippy actually checks
Clippy ships with lints grouped by category. The default set is conservative. It only warns about things that are almost certainly mistakes, significant inefficiencies, or patterns that will bite you later.
Correctness lints catch bugs. They flag code that panics unexpectedly, uses unwrap on a Result that might fail, or creates a race condition in unsafe blocks. Complexity lints catch over-engineering. They suggest iterators over manual loops, point out redundant clones, and flag functions that do too much. Style lints enforce idioms. They prefer if let over match with an empty arm, suggest Option::map over verbose branching, and flag unused variables. Performance lints catch hidden costs. They warn about unnecessary heap allocations, suggest into_iter over .iter().cloned(), and flag quadratic complexity in simple operations.
You don't need to memorize the lints. You just need to know how to run Clippy and how to interpret its feedback.
A minimal example: match vs if let
Clippy runs as a cargo subcommand. It compiles your code and runs the lints. The output looks like compiler errors, but the messages come from Clippy.
fn main() {
let x = Some(42);
// Clippy flags this match.
// It has an empty None arm.
// The compiler accepts it. Clippy suggests `if let`.
match x {
Some(val) => println!("{}", val),
None => {}
}
}
Run cargo clippy. The output includes a warning with the lint name and a suggestion.
warning: this `match` expression can be replaced with `if let`
--> src/main.rs:4:5
|
4 | / match x {
5 | | Some(val) => println!("{}", val),
6 | | None => {}
7 | | }
| |_____^ help: try this: `if let Some(val) = x { println!("{}", val) }`
|
= help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#match_single_binding
Clippy sees the pattern. It knows if let is the idiomatic way to handle one arm of an Option. It warns you. The suggestion is mechanical. You can apply it manually or use the fixer.
Read the lint name. It teaches you the idiom.
Realistic example: unwrap and allocations
Real code has more moving parts. Clippy catches issues that compound over time. Consider a function that reads a config file.
fn parse_config(path: &str) -> Result<String, Box<dyn std::error::Error>> {
// Clippy flags unwrap_used.
// This panics if the file doesn't exist.
// The function returns a Result, so the caller expects errors.
let content = std::fs::read_to_string(path).unwrap();
// Clippy flags manual_string_new.
// String::new() is redundant here.
// You push immediately, so the allocation happens anyway.
let mut result = String::new();
result.push_str(&content);
Ok(result)
}
Clippy reports two warnings. unwrap_used flags the panic risk. manual_string_new flags the redundant initialization. The fix is cleaner.
fn parse_config(path: &str) -> Result<String, Box<dyn std::error::Error>> {
// Use the result directly.
// The ? operator propagates errors.
// Clippy is happy.
Ok(std::fs::read_to_string(path)?)
}
The fixed version removes the panic, removes the redundant allocation, and uses the ? operator. Clippy guided you to a safer, shorter implementation.
Don't just fix the warning. Understand why Clippy flagged it. The lint name is a link to the documentation. Click it. Learn the pattern.
The --fix flag and safe automation
Clippy can apply fixes automatically. The --fix flag runs the lints and applies changes that Clippy is sure won't break your code. This is called "safe" fixing. Clippy only applies fixes that are mechanical and preserve behavior.
# Apply safe fixes.
# --allow-dirty lets Clippy modify files without committing first.
cargo clippy --fix --allow-dirty
Safe fixes include removing unused imports, replacing match with if let, simplifying boolean expressions, and removing redundant clones. Clippy won't touch unwrap because removing it might change behavior. It won't touch logic that requires context.
The community convention is to run --fix before a PR. It cleans up noise so reviewers can focus on logic. Run it locally. Commit the result. Don't argue about style fixes in code review. Let Clippy handle them.
Lint levels and groups
Clippy lints have levels. The default level is warn. You can change levels using attributes or command-line flags.
// Deny a specific lint for a function.
// The build fails if this lint triggers.
#[deny(clippy::unwrap_used)]
fn process_data() -> Result<String, std::io::Error> {
// This would cause a compile error.
// Ok("data".to_string())
Ok("data".to_string())
}
// Allow a specific lint for a module.
// Use sparingly.
#![allow(clippy::too_many_arguments)]
mod complex_api;
deny turns a warning into an error. The build fails. Use deny for lints that are unacceptable in your project. allow suppresses a lint. Use allow only when you have a specific reason.
Clippy groups lints. The default set is conservative. If you want stricter checks, enable clippy::pedantic. This turns on lints that enforce style preferences. Some teams love pedantic. Some find it noisy. You decide.
# Enable pedantic lints.
cargo clippy -- -W clippy::pedantic
clippy::nursery contains experimental lints. They might change or be removed. Enable them if you want to test new rules.
Convention aside: The community convention is to add a comment after every #[allow] explaining the specific reason. #[allow(clippy::too_many_arguments)] // API matches external C library signature. No silent allows. If you can't explain why it's allowed, remove the allow.
Pitfalls and convention asides
Clippy is powerful. Misuse it and you lose the benefits.
Suppressing too much kills the tool. #![allow(clippy::all)] disables every lint. You might do this to silence noise, but you also silence the warnings that catch bugs. Instead of allowing everything, fix the warnings or allow specific lints with comments.
CI drift is a common problem. If you don't run Clippy in CI, people merge code with warnings. The codebase degrades. Configure your CI to fail on warnings.
# GitHub Actions step.
# -D warnings treats all warnings as errors.
- name: Run Clippy
run: cargo clippy -- -D warnings
If you use deny attributes in source, the build fails locally and in CI. That's good. It enforces the rule everywhere.
Clippy output can be verbose. Use --message-format=json for tooling. Use --no-deps to skip dependencies. Skip dependencies if you only care about your code.
Convention aside: cargo clippy --fix --allow-dirty is safe to run, but review the diff. Clippy is smart, but not perfect. A rare edge case might slip through. Check the changes. Commit them.
Treat #[allow] as a technical debt note. If you can't explain why it's allowed, remove the allow.
Decision matrix
Use cargo clippy in your local workflow to catch issues before you commit. Use cargo clippy --fix --allow-dirty to apply safe, mechanical fixes across your codebase. Use #[deny(clippy::unwrap_used)] in library crates where panics are unacceptable. Use #[allow(clippy::...)] with a comment when you have a deliberate reason to ignore a lint. Use .clippy.toml to set project-wide thresholds like too_many_arguments. Use cargo clippy -- -D warnings in CI to enforce that no new warnings slip into main.
Clippy isn't your enemy. It's the pattern matcher that keeps your codebase from drifting into C-style Rust. Run it. Fix the warnings. Write idiomatic code.