Thanks to Diego F. Goberna for the lovely logo 🥰
cargo-machete is a Cargo tool that detects unused dependencies in Rust
projects, in a fast (yet imprecise) way.
See also the blog post for a detailed writeup.
Install cargo-machete with cargo:
cargo install cargo-machete
Run cargo-machete in a directory that contains one or more Rust projects (using Cargo for dependency management):
cd my-directory && cargo machete
# alternatively
cargo machete /absolute/path/to/my/directoryThe return code gives an indication whether unused dependencies have been found:
- 0 if machete found no unused dependencies,
- 1 if it found at least one unused dependency,
- 2 if there was an error during processing (in which case there's no indication whether any unused dependency was found or not).
This can be used in CI situations.
By default cargo-machete descends into every subdirectory from the given root paths (or . if none
is given), looking for Cargo.toml files.
If you have crates you don't want analyzed (e.g., a tests directory full of small standalone
fixture crates that intentionally carry unused dependencies) you can prune them either
individually, using their absolute or relative path, with --skip; or skip an entire pattern of
paths that end with a given component --skip-patterns (e.g. --skip-patterns target will skip
all the paths which last component is target, but not e.g. end-target).
As a shorthand for the most common use case, there is also --skip-targets (equivalent to
--skip-patterns target) which skips all the target directories found during walking the input
paths.
# skip every `tests` directory found
cargo machete --skip-patterns tests
# skip only the `./tests` directory
cargo machete --skip tests
# or equivalently
cargo machete --skip ./tests
# those can be passed multiple times
cargo machete --skip-patterns tests --skip examplesNote that options must come before the paths to analyze: anything after the first path is treated as another path.
To ignore a certain set of dependencies in a crate, add
package.metadata.cargo-machete to Cargo.toml (or workspace.metadata.cargo-machete to a
workspace Cargo.toml), and specify an ignored array:
For example:
[dependencies]
prost = "0.10" # Used in code generated by build.rs output, which cargo-machete cannot check
# in an individual package Cargo.toml
[package.metadata.cargo-machete]
ignored = ["prost"]
# in a workspace Cargo.toml
[workspace.metadata.cargo-machete]
ignored = ["prost"]Build dependencies ([build-dependencies]) are only searched for in the build script file
itself (build.rs by default). Modules that the build script loads with mod statements are not
followed, so a build dependency that is only used in such a module is reported as unused: list it
in ignored as shown above.
If there are too many false positives, consider using the --with-metadata CLI
flag, which will call cargo metadata --all-features to find final dependency
names, more accurate dependencies per build type, etc. ⚠ This may modify the
Cargo.lock files in your projects.
Some crates have a different import name, than their dependency name (e.g.
rustls-webpki). This triggers false positives in cargo-machete when used
without the --with-metadata flag. To fix this you can manually rename a crate
for cargo-machete:
For example:
[dependencies]
rustls-webpki = "0.102"
# in an individual package Cargo.toml
[package.metadata.cargo-machete.renamed]
rustls-webpki = "webpki"
# in a workspace Cargo.toml
[workspace.metadata.cargo-machete.renamed]
rustls-webpki = "webpki"This ensures that if rustls-webpki is no longer used in the project,
cargo-machete will be able to detect it (unlike with the ignored table).
The tool can emit output a JSON object with the result of the analysis, for the consumption of
other programs, using the --json flag.
# Print the version.
$ cargo machete --json --version
> {"version":"0.9.2"}
# When no unused dependencies are found:
$ cargo machete --json ./integration-tests/with-bench/
> {}
# When some unused dependencies or ignored-unused dependencies are found:
$ cargo machete --json ./integration-tests/just-unused/
$ {"crates":[{"package_name":"just-unused","manifest_path":"./integration-tests/just-unused/Cargo.toml","unused":["log"],"unused_build":[],"ignored_used":[]}]}
unused lists the unused dependencies from [dependencies] and [dev-dependencies], and
unused_build the ones from [build-dependencies]. A crate can appear in both lists.
A docker image for cargo machete.
For instance, run cargo-machete in the $(pwd) directory using:
docker run --rm -v $(pwd):/src ghcr.io/bnjbvr/cargo-machete:latest
A github action for cargo machete.
The step given by,
- uses: bnjbvr/cargo-machete@main
can be added to any workflow.
An example workflow is shown below:
name: Cargo Machete
on:
pull_request: { branches: "*" }
jobs:
detect-unused-dependencies:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Machete
uses: bnjbvr/cargo-machete@maincargo machete can be used as a pre-commit hook to check for unused dependencies before committing changes.
Add the following to your .pre-commit-config.yaml:
- repo: https://github.com/bnjbvr/cargo-machete
rev: main # or a specific tag/commit
hooks:
- id: cargo-macheteWe're using Justfile for common development tasks. Run just -l
to get a list of available recipes, or just to run the same commands as in CI.
We welcome community contributions to this project.