Thanks to Diego F. Goberna for the lovely logo 🥰

Introduction

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.

Installation

Install cargo-machete with cargo:

cargo install cargo-machete

Usage

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/directory

The 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.

False positives

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"]

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.

Renamed crates

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).

Docker Image

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

Cargo Machete Action

A github action for cargo machete.

Example usage

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@main

pre-commit Hooks

cargo 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-machete

Contributing

We welcome community contributions to this project.

License

MIT license.