rust-clippy Documentation

A bunch of lints to catch common mistakes and improve your Rust code. Book:

13,392 stars Rust Rust 1 file · ~6,112 tokens #lint#rust
RAW Doc

File: README.md

Clippy

A collection of lints to catch common mistakes and improve your Rust code.

There are over 800 lints included in this crate!

Lints are divided into categories, each with a default lint level.
You can choose how much Clippy is supposed to annoy help you by changing the lint level by category.

Category Description Default level
clippy::all all lints that are on by default (correctness, suspicious, style, complexity, perf) warn/deny
clippy::correctness code that is outright wrong or useless deny
clippy::suspicious code that is most likely wrong or useless warn
clippy::style code that should be written in a more idiomatic way warn
clippy::complexity code that does something simple but in a complex way warn
clippy::perf code that can be written to run faster warn
clippy::pedantic lints which are rather strict or have occasional false positives allow
clippy::restriction lints which prevent the use of language and library features[^restrict] allow
clippy::nursery new lints that are still under development allow
clippy::cargo lints for the cargo manifest allow

More to come, please file an issue if you have ideas!

The restriction category should, emphatically, not be enabled as a whole. The contained
lints may lint against perfectly reasonable code, may not have an alternative suggestion,
and may contradict any other lints (including other categories). Lints should be considered
on a case-by-case basis before enabling.

[^restrict]: Some use cases for restriction lints include:
- Strict coding styles (e.g. clippy::else_if_without_else).
- Additional restrictions on CI (e.g. clippy::todo).
- Preventing panicking in certain functions (e.g. clippy::unwrap_used).
- Running a lint only on a subset of code (e.g. #[forbid(clippy::float_arithmetic)] on a module).

Table of contents:

Usage

Below are instructions on how to use Clippy as a cargo subcommand,
in projects that do not use cargo, or in Travis CI.

As a cargo subcommand (`cargo clippy`)

One way to use Clippy is by installing Clippy through rustup as a cargo
subcommand.

Step 1: Install Rustup

You can install Rustup on supported platforms. This will help
us install Clippy and its dependencies.

If you already have Rustup installed, update to ensure you have the latest
Rustup and compiler:

terminal
rustup update

Step 2: Install Clippy

Once you have rustup and the latest stable release (at least Rust 1.29) installed, run the following command:

terminal
rustup component add clippy

If it says that it can't find the clippy component, please run rustup self update.

Step 3: Run Clippy

Now you can run Clippy by invoking the following command:

terminal
cargo clippy

Automatically applying Clippy suggestions

Clippy can automatically apply some lint suggestions, just like the compiler. Note that --fix implies
--all-targets, so it can fix as much code as it can.

terminal
cargo clippy --fix

Workspaces

All the usual workspace options should work with Clippy. For example the following command
will run Clippy on the example crate:

terminal
cargo clippy -p example

As with cargo check, this includes dependencies that are members of the workspace, like path dependencies.
If you want to run Clippy only on the given crate, use the --no-deps option like this:

terminal
cargo clippy -p example -- --no-deps

Using `clippy-driver`

Clippy can also be used in projects that do not use cargo. To do so, run clippy-driver
with the same arguments you use for rustc. For example:

terminal
clippy-driver --edition 2018 -Cpanic=abort foo.rs

Note that clippy-driver is designed for running Clippy only and should not be used as a general
replacement for rustc. clippy-driver may produce artifacts that are not optimized as expected,
for example.

Travis CI

You can add Clippy to Travis CI in the same way you use it locally:

yaml
language: rust
rust:
  - stable
  - beta
before_script:
  - rustup component add clippy
script:
  - cargo clippy
  # if you want the build job to fail when encountering warnings, use
  - CARGO_BUILD_WARNINGS=deny cargo clippy
  # in order to also check tests and non-default crate features, use
  - CARGO_BUILD_WARNINGS=deny cargo clippy --all-targets --all-features
  - cargo test
  # etc.

Note that setting CARGO_BUILD_WARNINGS=deny will cause your build to fail if any warnings are found in your code.
That includes warnings found by rustc (e.g. dead_code, etc.). If you want to avoid this and only cause
an error for Clippy warnings, use #![deny(clippy::all)] in your code or -D clippy::all on the command
line. (You can swap clippy::all with the specific lint category you are targeting.)

Also note that before Cargo 1.97, the usual way to deny all warnings was by using -D warnings:

shell
cargo clippy -- -D warnings

However, CARGO_BUILD_WARNINGS has the benefit of not invalidating build caches,
and is thus to be preferred going forward.

Configuration

Allowing/denying lints

You can add options to your code to allow/warn/deny Clippy lints:

  • the whole set of Warn lints using the clippy lint group (#![deny(clippy::all)]).
    Note that rustc has additional lint groups.

  • all lints using both the clippy and clippy::pedantic lint groups (#![deny(clippy::all)],
    #![deny(clippy::pedantic)]). Note that clippy::pedantic contains some very aggressive
    lints prone to false positives.

  • only some lints (#![deny(clippy::single_match, clippy::box_vec)], etc.)

  • allow/warn/deny can be limited to a single function or module using #[allow(...)], etc.

Note: allow means to suppress the lint for your code. With warn the lint
will only emit a warning, while with deny the lint will emit an error, when
triggering for your code. An error causes Clippy to exit with an error code, so
is useful in scripts like CI/CD.

If you do not want to include your lint levels in your code, you can globally
enable/disable lints by passing extra flags to Clippy during the run:

To allow lint_name, run

terminal
cargo clippy -- -A clippy::lint_name

And to warn on lint_name, run

terminal
cargo clippy -- -W clippy::lint_name

This also works with lint groups. For example, you
can run Clippy with warnings for all lints enabled:

terminal
cargo clippy -- -W clippy::pedantic

If you care only about a single lint, you can allow all others and then explicitly warn on
the lint(s) you are interested in:

terminal
cargo clippy -- -A clippy::all -W clippy::useless_format -W clippy::...

Configure the behavior of some lints

Some lints can be configured in a TOML file named clippy.toml or .clippy.toml. It contains a basic variable = value mapping e.g.

toml
avoid-breaking-exported-api = false
disallowed-names = ["toto", "tata", "titi"]

The table of configurations
contains all config values, their default, and a list of lints they affect.
Each configurable lint
, also contains information about these values.

For configurations that are a list type with default values such as
disallowed-names,
you can use the unique value ".." to extend the default values instead of replacing them.

toml
# default of disallowed-names is ["foo", "baz", "quux"]
disallowed-names = ["bar", ".."] # -> ["bar", "foo", "baz", "quux"]

Note

clippy.toml or .clippy.toml cannot be used to allow/deny lints.

To deactivate the “for further information visit lint-link” message you can
define the CLIPPY_DISABLE_DOCS_LINKS environment variable.

Specifying the minimum supported Rust version

Projects that intend to support old versions of Rust can disable lints pertaining to newer features by
specifying the minimum supported Rust version (MSRV) in the Clippy configuration file.

toml
msrv = "1.30.0"

Alternatively, the rust-version field
in the Cargo.toml can be used.

toml
# Cargo.toml
rust-version = "1.30"

The MSRV can also be specified as an attribute, like below.

rust,ignore
#![feature(custom_inner_attributes)]
#![clippy::msrv = "1.30.0"]

fn main() {
  ...
}

You can also omit the patch version when specifying the MSRV, so msrv = 1.30
is equivalent to msrv = 1.30.0.

Note: custom_inner_attributes is an unstable feature, so it has to be enabled explicitly.

Lints that recognize this configuration option can be found here

Contributing

If you want to contribute to Clippy, you can find more information in CONTRIBUTING.md.

License

Copyright (c) The Rust Project Contributors

Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
https://www.apache.org/licenses/LICENSE-2.0> or the MIT license
<LICENSE-MIT or https://opensource.org/licenses/MIT>, at your
option. Files in the project may not be
copied, modified, or distributed except according to those terms.

File: book/src/continuous_integration/README.md

Continuous Integration

It is recommended to run Clippy on CI with -Dwarnings, so that Clippy lints
prevent CI from passing. To enforce errors on warnings on all cargo commands
not just cargo clippy, you can set the env var RUSTFLAGS="-Dwarnings".

We recommend to use Clippy from the same toolchain, that you use for compiling
your crate for maximum compatibility. E.g. if your crate is compiled with the
stable toolchain, you should also use stable Clippy.

Note: New Clippy lints are first added to the nightly toolchain. If you
want to help with improving Clippy and have CI resources left, please consider
adding a nightly Clippy check to your CI and report problems like false
positives back to us. With that we can fix bugs early, before they can get to
stable.

This chapter will give an overview on how to use Clippy on different popular CI
providers.

File: book/src/development/infrastructure/README.md

Infrastructure

In order to deploy Clippy over rustup, some infrastructure is necessary. This
chapter describes the different parts of the Clippy infrastructure that need to
be maintained to make this possible.

The most important part is the sync between the rust-lang/rust repository and
the Clippy repository that takes place every two weeks. This process is
described in the Syncing changes between Clippy and rust-lang/rust
section.

A new Clippy release is done together with every Rust release, so every six
weeks. The release process is described in the Release a new Clippy
Version section. During a release cycle a changelog entry for the
next release has to be written. The format of that and how to do that is
documented in the Changelog Update section.

Note: The Clippy CI should also be described in this chapter, but for now is
left as a TODO.

File: book/src/development/proposals/README.md

Proposals

This chapter is about accepted proposals for changes that should be worked on in
or around Clippy in the long run.

Besides adding more and more lints and improve the lints that Clippy already
has, Clippy is also interested in making the experience of its users, developers
and maintainers better over time. Projects that address bigger picture things
like this usually take more time, and it is useful to have a proposal for those
first. This is the place where such proposals are collected, so that we can
refer to them when working on them.

File: book/src/development/README.md

Clippy Development

Hello fellow Rustacean! If you made it here, you're probably interested in
making Clippy better by contributing to it. In that case, welcome to the
project!

Note: If you're just interested in using Clippy, there's nothing to see from
this point onward, and you should return to one of the earlier chapters.

Getting started

If this is your first time contributing to Clippy, you should first read the
Basics docs. This will explain the basics on how to get the source
code and how to compile and test the code.

Additional Readings for Beginners

If a dear reader of this documentation has never taken a class on compilers
and interpreters, it might be confusing as to why AST level deals with only
the language's syntax. And some readers might not even understand what lexing,
parsing, and AST mean.

This documentation serves by no means as a crash course on compilers or language design.
And for details specifically related to Rust, the Rustc Development Guide
is a far better choice to peruse.

The Syntax and AST chapter and the High-Level IR chapter are
great introduction to the concepts mentioned in this chapter.

Some readers might also find the introductory chapter of
Robert Nystrom's Crafting Interpreters a helpful overview of compiled and
interpreted languages before jumping back to the Rustc guide.

Writing code

If you have done the basic setup, it's time to start hacking.

The Adding lints chapter is a walk through on how to add a
new lint to Clippy. This is also interesting if you just want to fix a lint,
because it also covers how to test lints and gives an overview of the bigger
picture.

If you want to add a new lint or change existing ones apart from bugfixing, it's
also a good idea to give the stability guarantees and
lint categories sections of the Clippy 1.0 RFC a
quick read. The lint categories are also described earlier in this
book.

Note: Some higher level things about contributing to Clippy are still
covered in the CONTRIBUTING.md document. Some of those will be moved to
the book over time, like:

  • Finding something to fix
  • IDE setup
  • High level overview on how Clippy works
  • Triage procedure

File: book/src/README.md

Clippy

A collection of lints to catch common mistakes and improve your
Rust code.

There are over 800 lints included in this crate!

Lints are divided into categories, each with a default lint
level. You can choose how
much Clippy is supposed to annoy help you by changing the lint level by
category.

Category Description Default level
clippy::all all lints that are on by default (correctness, suspicious, style, complexity, perf) warn/deny
clippy::correctness code that is outright wrong or useless deny
clippy::suspicious code that is most likely wrong or useless warn
clippy::style code that should be written in a more idiomatic way warn
clippy::complexity code that does something simple but in a complex way warn
clippy::perf code that can be written to run faster warn
clippy::pedantic lints which are rather strict or have occasional false positives allow
clippy::restriction lints which prevent the use of language and library features[^restrict] allow
clippy::nursery new lints that are still under development allow
clippy::cargo lints for the cargo manifest allow

More to come, please file an issue if you have ideas!

The restriction category should, emphatically, not be enabled as a whole. The contained
lints may lint against perfectly reasonable code, may not have an alternative suggestion,
and may contradict any other lints (including other categories). Lints should be considered
on a case-by-case basis before enabling.

[^restrict]: Some use cases for restriction lints include:
- Strict coding styles (e.g. clippy::else_if_without_else).
- Additional restrictions on CI (e.g. clippy::todo).
- Preventing panicking in certain functions (e.g. clippy::unwrap_used).
- Running a lint only on a subset of code (e.g. #[forbid(clippy::float_arithmetic)] on a module).

File: book/README.md

Clippy Book

This is the source for the Clippy Book. See the
book for more information.

File: clippy_lints/README.md

This crate contains Clippy lints. For the main crate, check GitHub.

File: clippy_utils/README.md

`clippy-utils`

Helpful tools for writing lints, provided as they are used in Clippy.

Usage

This crate is only guaranteed to build with this nightly toolchain:

text
nightly-2026-08-20

To use clippy-utils in your lint, add the following to your Cargo.toml:

text
clippy_utils = "0.1.XY"

XY is the version of the nightly toolchain above and can be determined with rustc +nightly-YYYY-MM-DD -V.

:warning: Stability :warning:

No stability guarantees are made for this crate! Use at your own risk.

Function signatures can change or be removed without replacement without any prior notice.

LICENSE

Copyright (c) The Rust Project Contributors

Licensed under the Apache License, Version 2.0
<https://www.apache.org/licenses/LICENSE-2.0> or the MIT license
<https://opensource.org/licenses/MIT>, at your option. Files in the project may
not be copied, modified, or distributed except according to those terms.

File: lintcheck/README.md

`cargo lintcheck`

Runs Clippy on a fixed set of crates read from
lintcheck/lintcheck_crates.toml and saves logs of the lint warnings into the
repo. We can then check the diff and spot new or disappearing warnings.

From the repo root, run:

text
cargo lintcheck

or

text
cargo run --target-dir lintcheck/target --manifest-path lintcheck/Cargo.toml

By default, the logs will be saved into
lintcheck-logs/lintcheck_crates_logs.txt.

You can set a custom sources.toml by adding --crates-toml custom.toml or using
LINTCHECK_TOML="custom.toml" where custom.toml must be a relative path from
the repo root.

The results will then be saved to lintcheck-logs/custom_logs.toml.

The custom.toml file may be built using https://crates.io recently most
downloaded crates by using cargo lintcheck popular. For example, to retrieve
the 200 recently most downloaded crates:

text
cargo lintcheck popular -n 200 custom.toml

Note: Lintcheck isn't sandboxed. Only use it to check crates that you trust or
sandbox it manually.

Configuring the Crate Sources

The sources to check are saved in a toml file. There are three types of
sources.

  1. Crates-io Source

    toml
    bitflags = {name = "bitflags", versions = ['1.2.1']}

    Requires a "name" and one or multiple "versions" to be checked.

  2. git Source

    toml
    puffin = {name = "puffin", git_url = "https://github.com/EmbarkStudios/puffin", git_hash = "02dd4a3"}

    Requires a name, the url to the repo and unique identifier of a commit,
    branch or tag which is checked out before linting. There is no way to always
    check HEAD because that would lead to changing lint-results as the repo
    would get updated. If git_url or git_hash is missing, an error will be
    thrown.

  3. Local Dependency

    toml
    clippy = {name = "clippy", path = "/home/user/clippy"}

    For when you want to add a repository that is not published yet.

Command Line Options (optional)

toml
clap = {name = "clap", versions = ['4.5.8'], options = ['-Fderive']}

It is possible to specify command line options for each crate. This makes it
possible to enable or disable features.

Fix mode

You can run cargo lintcheck --fix which will run Clippy with --fix and
print a warning if Clippy's suggestions fail to apply (if the resulting code does not build).
This lets us spot bad suggestions or false positives automatically in some cases.

Note: Fix mode implies --all-targets, so it can fix as much code as it can.

Please note that the target dir should be cleaned afterwards since Clippy will modify
the downloaded sources which can lead to unexpected results when running lintcheck again afterwards.

Recursive mode

You can run cargo lintcheck --recursive to also run Clippy on the dependencies
of the crates listed in the crates source .toml. e.g. adding rand 0.8.5
would also lint rand_core, rand_chacha, etc.

Particularly slow crates in the dependency graph can be ignored using
recursive.ignore:

toml
[crates]
cargo = {name = "cargo", versions = ['0.64.0']}

[recursive]
ignore = [
    "unicode-normalization",
]

Explore Related Technologies & Topics

View All 9,111+ Repositories →

Discover similar high-velocity repositories, agent skills, and OpenAPI specifications across the ecosystem.

#lint Browse lint catalog → #rust Browse rust catalog → ⚡ MCP Servers Model Context Protocol → 🧠 Agent Skills Prompt & rule files → 🔌 OpenAPI Specs REST & Swagger schemas →