Skip to content

About

Remove unused Rust dependencies with this one weird trick!

Topics

Resources

Stars

1.4k stars

Watchers

4 watching

Forks

Use this GitHub action with your project
Add this Action to an existing workflow or create a new one
View on Marketplace

Repository files navigation

cargo-machete

Remove unused Rust dependencies with this one weird trick!

build status matrix chat supported rustc stable dependency status

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.

Skipping directories

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 examples

Note that options must come before the paths to analyze: anything after the first path is treated as another path.

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

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.

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

JSON output

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.

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

Contributor Covenant

We welcome community contributions to this project.

License

MIT license.

About

Remove unused Rust dependencies with this one weird trick!

Topics

Resources

Stars

1.4k stars

Watchers

4 watching

Forks

Releases

Sponsor this project

Packages

Used by

Contributors

Languages