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

Feature	cargo-machete	cargo-udeps
Accuracy	Good	Excellent
Speed	Very fast	Slower
Rust version	Stable	Requires nightly
False positives	Some	Fewer
Installation	Simple	Requires nightly setup
Maintenance	Active	Active

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