# rust-clippy: 800+ Rust lints, and how to run them without wrecking your build cache > Clippy is the Rust project's own lint collection, shipped through rustup as a cargo subcommand. It is useful the moment you run cargo clippy, and it becomes a maintenance question the moment you turn on clippy::pedantic or wire it into CI. **rust-lang/rust-clippy** — A bunch of lints to catch common mistakes and improve your Rust code. Book: https://doc.rust-lang.org/clippy/ - Repository: https://github.com/rust-lang/rust-clippy - Website: https://rust-lang.github.io/rust-clippy/ - Stars: 13,547 · Forks: 2,188 - Language: Rust - License: Apache-2.0 - Published: 2026-09-21 · Updated: 2026-09-21 · Language: en - Canonical page: https://hysenlabs.com/projects/rust-lang-rust-clippy ## What Clippy catches that rustc does not bother with rustc already refuses to compile code that is outright wrong. Clippy targets the layer above that: code that compiles, runs, and is still a mistake or a detour. The README describes the project as "a collection of lints to catch common mistakes and improve your Rust code", and states there are over 800 lints in the crate. The audience is anyone who runs cargo check or cargo build on a Rust codebase and wants a second opinion that costs one extra command. The useful part is the category split, because it decides how much noise you sign up for. clippy::correctness is deny by default, so it is treated as code that is outright wrong or useless. clippy::suspicious, clippy::style, clippy::complexity and clippy::perf are warn by default. clippy::pedantic, clippy::nursery, clippy::cargo and clippy::restriction are allow by default, which is the project's way of saying these are opinions you should opt into deliberately. That default posture is the design decision worth noticing. Clippy does not try to be a style authority out of the box. It ships a conservative core and puts the argumentative lints behind a category you have to name. ## How the lint set is wired: cargo-clippy, clippy-driver and the crate split The repository is not a single binary. Cargo.toml declares two binaries: cargo-clippy at src/main.rs and clippy-driver at src/driver.rs. The cargo subcommand is a thin front end; the actual linting runs through a rustc-compatible driver, which is why the README can say Clippy also works in projects that do not use cargo by invoking clippy-driver with the same arguments you would pass rustc. The lints themselves live in separate workspace crates. Cargo.toml lists clippy_lints, clippy_utils, clippy_config and declare_clippy_lint as path dependencies, with clippy_lints_internal behind an optional internal feature. That split matters if you plan to read the source: the lint implementations are in clippy_lints, shared helpers in clippy_utils, and configuration handling in clippy_config. The top-level clippy.toml file in the repository root is the project's own configuration file, the same filename users are expected to create in their own projects. One constraint the README calls out directly: clippy-driver is designed for running Clippy only and should not be used as a general replacement for rustc. It says the driver may produce artifacts that are not optimized as expected. If you have a non-cargo build, that is the boundary you are working inside. ## Install Clippy with rustup and run it on a real crate The README's path is rustup. Install or update rustup first, then add the component. The README states the latest stable release must be at least Rust 1.29. ```bash rustup update rustup component add clippy ``` If the component is not found, the README says to run rustup self update. Once the component is present, Clippy runs as a cargo subcommand from your project directory: ```bash cargo clippy ``` You should see Clippy diagnostics printed the way rustc diagnostics are, tagged with the lint name. Some of those suggestions can be applied automatically: ```bash cargo clippy --fix ``` The README notes that --fix implies --all-targets, so it will attempt to fix as much code as it can. Run this on a clean working tree. In a workspace, the usual cargo selection flags carry over, for example cargo clippy -p example for a single member. The README points out that this still includes workspace members that are path dependencies, and that adding -- --no-deps restricts the run to the named crate: ```bash cargo clippy -p example -- --no-deps ``` ## Failing a build on Clippy warnings, and the trap in CARGO_BUILD_WARNINGS The README's Travis CI example is the clearest statement of intent for continuous integration. It adds the component in before_script and runs cargo clippy in script, then shows the stricter variants: ```yaml language: rust rust: - stable - beta before_script: - rustup component add clippy script: - cargo clippy - CARGO_BUILD_WARNINGS=deny cargo clippy - CARGO_BUILD_WARNINGS=deny cargo clippy --all-targets --all-features - cargo test ``` The trap is spelled out in the README itself. Setting CARGO_BUILD_WARNINGS=deny fails the build when any warnings are found, and that includes rustc warnings such as dead_code. If you only want Clippy warnings to be fatal, the README gives two alternatives: #![deny(clippy::all)] in your code, or -D clippy::all on the command line, swapping clippy::all for whichever category you are targeting. It also notes that before Cargo 1.97 the usual way to deny all warnings was: ```bash cargo clippy -- -D warnings ``` The README prefers CARGO_BUILD_WARNINGS going forward because it does not invalidate build caches. That is a real trade-off, not a style preference: -D warnings throws away cached work on every run, and the newer variable does not. ## pedantic, nursery and restriction are not a difficulty setting The categories below the defaults are where teams get into trouble. clippy::pedantic is described as lints that are rather strict or have occasional false positives. clippy::nursery holds new lints still under development. Neither is a promise of correctness, and enabling pedantic wholesale on an existing codebase will produce a long list that you then have to triage anyway. clippy::restriction is the one the README warns about in the strongest terms. It says the category should emphatically not be enabled as a whole, because the contained lints may lint against perfectly reasonable code, may not have an alternative suggestion, and may contradict other lints, including lints in other categories. The README's own guidance is to consider them case by case. The documented use cases are narrow: strict coding styles such as clippy::else_if_without_else, extra CI restrictions such as clippy::todo, preventing panics in certain functions such as clippy::unwrap_used, or scoping a lint to a module with something like #[forbid(clippy::float_arithmetic)]. That is the honest shape of the tool. Restriction lints are policy levers, not quality measurements, and the project says so. ## Clippy versus rustfmt, cargo check and rust-analyzer Clippy is frequently confused with tools that solve adjacent problems. The comparison that matters is with rustfmt. rustfmt rewrites formatting; it does not reason about whether your code is wrong. Clippy reports diagnostics and only applies fixes it has a suggestion for, which is why cargo clippy --fix is described as applying some lint suggestions rather than all of them. Running both is normal: rustfmt decides where the braces go, Clippy decides whether the match arm should exist. The second comparison is with cargo check. cargo check type-checks and borrow-checks without producing a binary. Clippy runs the same compiler pipeline plus the lint passes, so it is strictly more work per run. On a large crate that difference is measurable, and it is the reason some teams run cargo check in the tight edit loop and cargo clippy before commit or in CI. The third is rust-analyzer, which surfaces Clippy diagnostics inside the editor. That is a delivery channel, not an alternative lint engine. The README does not document editor integration at all; it covers the cargo subcommand, clippy-driver, and the Travis CI example. If your workflow depends on lint-on-save in VS Code, Neovim or Zed, that configuration lives in the editor's Rust tooling, not in this repository's documentation, and you should verify it against the editor's own docs rather than assuming Clippy ships it. ## Licence, versioning and what an upgrade actually costs The crate is dual-licensed MIT OR Apache-2.0, matching the licence files in the repository root (LICENSE-MIT and LICENSE-APACHE). The README badge says the same. For most users this is the same permissive pair the rest of the Rust ecosystem uses; if your organisation has a policy about which of the two it accepts, that is a question for your own review process, not something the README resolves. Versioning is where Clippy differs from an ordinary dependency. Cargo.toml sets publish = false, so the crate is not published to crates.io in the usual sense; you get Clippy through rustup as a component tied to your toolchain. The package version in Cargo.toml is 0.1.100, and the workspace has a rust-toolchain.toml pinning the toolchain the project builds against. Practically, upgrading Clippy means upgrading the toolchain, and a toolchain upgrade can introduce new lints or change lint behaviour. That is the real upgrade cost: a rustup update can turn a green CI run red without a single line of your code changing. The mitigation is in the configuration surface, not in the upgrade. Pin lint levels explicitly with #![deny(...)] or -D clippy::all rather than relying on defaults, and treat a new warning after a toolchain bump as a decision to make rather than a build to fix in a hurry. The repository also carries a lintcheck/ directory and a CHANGELOG.md, which are the places to look when you want to know what moved. The last push to the default branch was on 2026-09-21. ## Conclusion Adopt Clippy if you write Rust and use cargo: the install is one rustup component and the default lint set is already warn/deny. Do not enable clippy::restriction as a group; the README states those lints may contradict each other and may lint perfectly reasonable code. Before enforcing anything in CI, verify which warning source you are actually gating on, because CARGO_BUILD_WARNINGS=deny fails the build on rustc warnings such as dead_code as well as Clippy's. ## FAQ ### What does rust-clippy do in Rust? It is a collection of over 800 lints that catch common mistakes and suggest improvements to Rust code, grouped into categories such as correctness, style, complexity and perf. It runs as a cargo subcommand on top of the normal compiler pipeline. ### What is rust-clippy used for? Clippy is used to catch common mistakes and improve Rust code, with lints divided into categories that each carry a default lint level. The categories range from correctness, which is deny by default, to pedantic and restriction, which are allow by default. ### How do I install rust-clippy? Install or update rustup, then run rustup component add clippy. If the component cannot be found, the README says to run rustup self update. The README states the latest stable release must be at least Rust 1.29. ### How do I use rust-clippy in a Rust project? Run cargo clippy from the project directory. To apply the suggestions Clippy has fixes for, run cargo clippy --fix, which implies --all-targets. In a workspace you can select a member with cargo clippy -p example. ### What is the difference between rust-clippy and cargo check? cargo check type-checks without producing a binary, while Clippy runs the compiler pipeline plus its own lint passes, so it does more work per run. The README treats Clippy as an addition to the normal cargo workflow rather than a replacement for check. ### Is rust-clippy the same as rustfmt? No. rustfmt rewrites formatting, while Clippy reports lints about code that compiles but is likely wrong or unidiomatic, and applies only the suggestions it has fixes for. The README describes cargo clippy --fix as applying some lint suggestions, not all of them. ## Sources - [Issues](https://github.com/rust-lang/rust-clippy/issues) - [License: Apache-2.0](https://github.com/rust-lang/rust-clippy/blob/master/LICENSE) - [Project website](https://rust-lang.github.io/rust-clippy/) - [README](https://github.com/rust-lang/rust-clippy/blob/master/README.md) - [rust-lang/rust-clippy on GitHub](https://github.com/rust-lang/rust-clippy) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/rust-lang-rust-clippy