cargo-machete – Unused Dependency Detection

cargo-machete is a fast tool for detecting unused dependencies in Rust projects. It analyzes your codebase to find dependencies listed in Cargo.toml but not actually used in your code.

Installation

# Install cargo-machete
cargo install cargo-machete

# Verify installation
cargo machete --version

Basic Usage

# Check for unused dependencies in current directory
cargo machete

# Check specific directory
cargo machete /path/to/project

# Check with detailed output
cargo machete --with-metadata

# Fix unused dependencies automatically (removes from Cargo.toml)
cargo machete --fix

# Check workspace
cargo machete --workspace

Output Examples

Basic Output

$ cargo machete
Found unused dependencies in Cargo.toml:
  serde_json (unused)
  log (unused in lib, used in build.rs)
  tokio (unused features: macros)

With Metadata

$ cargo machete --with-metadata
Project: my_app (bin)
  Unused dependencies:
    - serde_json (0.1.0)
      Declared in: Cargo.toml [dependencies]
      Not used in: src/main.rs

  Partially used:
    - tokio (1.35.0)
      Unused features: macros, fs
      Used features: runtime, net

False Positive Handling

Common False Positives

1. Dependencies used only in build.rs:

   [build-dependencies]
   bindgen = "0.69"  # Correctly placed, machete won't flag
   

2. Dependencies used only in examples:

   [dev-dependencies]
   criterion = "0.5"  # For examples/benchmarks
   

3. Dependencies used via re-exports:

   // lib.rs
   pub use external_crate::SomeType;  # Machete may not detect
   

4. Proc-macro dependencies:

   [dependencies]
   serde = { version = "1.0", features = ["derive"] }
   # Machete may flag serde as unused if only using derive macro
   

Ignoring False Positives

Create .cargo-machete.toml or add to Cargo.toml:

# .cargo-machete.toml
[ignore]
# Ignore specific dependencies
dependencies = ["serde", "log"]

# Ignore dependencies in specific crates
[ignore.my_crate]
dependencies = ["tokio"]

Or use inline comments in Cargo.toml:

[dependencies]
serde = "1.0"  # machete:ignore - used via re-export
log = "0.4"    # machete:ignore - used in macro expansion

Comparison with cargo-udeps

When to Use Each

Use cargo-machete when:

• Working with stable Rust
• Need fast feedback in CI
• Willing to verify results manually
• Want simple installation

Use cargo-udeps when:

• Accuracy is critical
• Can use nightly toolchain
• Need to catch all unused dependencies
• Have time for slower analysis

Using Both Together

# Fast check with machete
cargo machete

# Verify with udeps (more accurate)
cargo +nightly udeps

cargo-udeps Installation and Usage

For comparison, here’s how to use the more accurate cargo-udeps:

# Install nightly and cargo-udeps
rustup toolchain install nightly
cargo +nightly install cargo-udeps

# Run analysis (requires nightly)
cargo +nightly udeps

# With specific features
cargo +nightly udeps --all-features

# For workspace
cargo +nightly udeps --workspace

CI Integration

GitHub Actions with cargo-machete

name: Dependency Check

on: [push, pull_request]

jobs:
  unused-deps:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: dtolnay/rust-toolchain@stable

      - name: Install cargo-machete
        uses: taiki-e/install-action@v2
        with:
          tool: cargo-machete

      - name: Check for unused dependencies
        run: cargo machete --with-metadata

GitHub Actions with cargo-udeps (Nightly)

name: Dependency Check

on: [push, pull_request]

jobs:
  unused-deps:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: dtolnay/rust-toolchain@nightly

      - uses: Swatinem/rust-cache@v2

      - name: Install cargo-udeps
        uses: taiki-e/install-action@v2
        with:
          tool: cargo-udeps

      - name: Check for unused dependencies
        run: cargo +nightly udeps --workspace --all-features

GitHub Action (Official cargo-machete Action)

name: Dependency Check

on: [push, pull_request]

jobs:
  unused-deps:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Check unused dependencies
        uses: bnjbvr/cargo-machete@main

Advanced Usage

Workspace Configuration

# Check all workspace members
cargo machete --workspace

# Check specific workspace members
cargo machete -p crate1 -p crate2

# Exclude specific members
cargo machete --workspace --exclude integration_tests

Custom Configuration File

Create .cargo-machete.toml in project root:

# .cargo-machete.toml

# Global ignores
[ignore]
dependencies = [
  "serde",      # Used via derive macro
  "log",        # Used in macro expansion
]

# Per-crate ignores
[ignore.my_lib]
dependencies = ["lazy_static"]

[ignore.my_bin]
dependencies = ["clap"]

# Workspace-wide settings
[workspace]
# Don't analyze these crates
exclude = ["internal_tools", "examples"]

Integration with Pre-commit

# .pre-commit-config.yaml
repos:
  - repo: local
    hooks:
      - id: cargo-machete
        name: Check for unused dependencies
        entry: cargo machete
        language: system
        pass_filenames: false
        files: Cargo.toml$

Workflow Integration

Combined with Other Tools

# Full dependency audit
cargo machete                 # Check unused
cargo outdated                # Check outdated
cargo audit                   # Check security
cargo deny check licenses     # Check licenses

Makefile Integration

# Makefile
.PHONY: deps-check deps-clean

deps-check:
	@echo "Checking for unused dependencies..."
	@cargo machete --with-metadata

deps-clean:
	@echo "Removing unused dependencies..."
	@cargo machete --fix
	@echo "Running cargo check..."
	@cargo check --all-targets

Script for CI

#!/usr/bin/env bash
# scripts/check-deps.sh
set -euo pipefail

echo "Running cargo-machete..."
if ! cargo machete --with-metadata; then
  echo "❌ Unused dependencies detected!"
  echo "Run 'cargo machete --fix' to remove them."
  exit 1
fi

echo "✅ No unused dependencies found."

Best Practices

1. Run regularly in CI:

   - run: cargo machete --with-metadata
   

2. Document false positives:

   [dependencies]
   serde = "1.0"  # machete:ignore - used via proc macro
   

3. Use with workspace:

   cargo machete --workspace --with-metadata
   

4. Verify before using –fix:

   # Check first
   cargo machete --with-metadata
   # Review output, then fix
   cargo machete --fix
   # Verify everything still builds
   cargo check --all-targets
   

5. Combine with cargo-udeps for accuracy:

   # Fast check
   cargo machete
   # Verify critical projects
   cargo +nightly udeps -p critical_lib
   

6. Add to pre-commit hooks for early detection:

   - id: cargo-machete
     entry: cargo machete
     language: system
   

7. Keep configuration file for complex projects:

   # .cargo-machete.toml
   [ignore]
   dependencies = ["known-false-positives"]
   

Troubleshooting

False positives for proc macros:

# Add to .cargo-machete.toml
[ignore]
dependencies = ["serde", "tokio-macros"]

Build.rs dependencies flagged:

# Should be in [build-dependencies]
[build-dependencies]
cc = "1.0"

Re-exported dependencies flagged:

# Document with comment
[dependencies]
external = "1.0"  # machete:ignore - re-exported in lib.rs

Workspace member issues:

# Check specific member
cargo machete -p problematic_crate --with-metadata

Need more accuracy:

# Use cargo-udeps instead
cargo +nightly udeps --workspace

References

• cargo-machete repository
• cargo-udeps repository
• Official GitHub Action
• Rust dependency management best practices