skip to content

What do `cargo machete` and `cargo outdated` each report about a Rust package's dependencies, and why can machete flag a dependency the build needs?

level: middleimportance: nice to knowfreq 22%

answer

  1. unused versus behind the latest
  2. a text search, not a compile
  3. build.rs output and feature-only deps
  4. Compat and Latest columns
  5. exit codes in CI

basics

~20 s

cargo machete searches a package's .rs files for each [dependencies] name and lists those it never sees, without compiling, so it misses uses it cannot read. cargo outdated lists locked versions with newer compatible (Compat) and newest (Latest) releases.

solid answer

~40 s

**cargo-machete** reads each package's `[dependencies]`, turns every name into an import name (`-` becomes `_`), and searches the package's `.rs` files with regular expressions for `use name`, `name::` paths and `extern crate name`. It never compiles, so it is fast but imprecise: a dependency used only by code `build.rs` generates, one added only to switch on a feature of a transitive crate, or one whose library name differs from its package name looks unused. You record those under `[package.metadata.cargo-machete] ignored` (or `renamed`), or try `--with-metadata`. It exits 1 when it finds an unused dependency. **cargo-outdated** runs `cargo update` in a temporary copy of the workspace and shows, for each dependency, the locked version (Project), the newest SemVer-compatible one (Compat) and the newest overall (Latest); it exits 0 unless you pass `--exit-code`.

go deeper

for a junior

Recall that cargo machete finds unused dependencies and cargo outdated lists dependencies with newer releases.

for a middle

Explain machete's regex search over source files and its false positives, and outdated's Project, Compat and Latest columns.

for a senior

Run machete as a blocking check with a maintained ignored list, and use outdated's Compat versus Latest to plan cargo update runs and requirement bumps.

for a principal

Decide which hygiene signals block merges and which feed a scheduled update routine, so the checks cut dependency drift without becoming noise.

## Two hygiene tools, two different questions Both tools are third-party Cargo subcommands that look at a package's dependencies, but they ask different questions: | | cargo-machete (0.9.2) | cargo-outdated (0.19.0) | |---|---|---| | Question | Is each declared dependency actually used? | Is each dependency behind a newer release? | | Method | regex search of `.rs` files | `cargo update` in a temporary workspace | | Compiles code | no | resolves, does not build your code | | Default exit when it finds something | 1 | 0 | | Typical fix | delete the line from `Cargo.toml` | `cargo update`, or raise a requirement | ## How cargo-machete decides "unused" For each package it finds under the given directory, cargo-machete: 1. reads the **`[dependencies]`** table of `Cargo.toml` (without `--with-metadata`, the source collects only those keys) and converts each name to the identifier Rust code would use, replacing `-` with `_`; 2. collects the `.rs` files under the directories of the package's targets (for most packages, `src/`); 3. searches them with regular expressions for `use name;`, `use name::...`, `use name as ...`, a path such as `name::Thing`, `extern crate name`, and multi-line grouped `use { ... }` statements; 4. reports every dependency with no match. Because nothing is compiled, a run over a large workspace takes seconds. The README is upfront about the cost: the tool is "fast (yet imprecise)". ## Where machete is wrong A **false positive** is a dependency the build needs that machete calls unused: - **Generated code.** A crate referenced only from code that `build.rs` writes into `OUT_DIR` and pulls in with `include!`: the README's own example is `prost`. Generated files are not among the `.rs` files it searches. - **Feature activation.** A line such as `getrandom = { version = "...", features = [...] }` added only to enable a feature of a crate some other dependency pulls in. Your code never names it, but removing it changes the build. - **Renamed libraries.** A package whose library name differs from its package name, such as `rustls-webpki` imported as `webpki`. Either map it with `[package.metadata.cargo-machete.renamed]` or run `--with-metadata`, which calls `cargo metadata --all-features` to learn the real names (and may modify `Cargo.lock`). A **false negative** is the reverse: a word that only looks like a use, such as a stale `name::` path in a comment, keeps an unused dependency alive. The escape hatches: - `[package.metadata.cargo-machete] ignored = ["prost"]` in a package, or `[workspace.metadata.cargo-machete]` at the root, with a comment saying why; - `--fix` rewrites `Cargo.toml` to drop every flagged dependency, **false positives included**, so review the diff; - the exit status is 0 when nothing is unused, 1 when at least one unused, non-ignored dependency is found, and 2 on error, which makes it usable as a CI check. For an exact answer there is rustc's allow-by-default lint `unused_crate_dependencies`, which works from the real compilation but reports per crate target, so tests and binaries that use a dependency differently need care. ## How cargo-outdated works cargo-outdated builds on Cargo's own resolver: it copies the workspace to a temporary location, runs **`cargo update`** there to find the newest versions the current requirements allow, then replaces the requirements of **direct** dependencies with wildcards and resolves again to find the newest releases overall. Its table then shows, per dependency (transitive ones as `parent->child`): - **Project**, the version in your `Cargo.lock`; - **Compat**, the newest SemVer-compatible version, which a plain `cargo update` would give you (`---` when you already have it); - **Latest**, the newest release, which usually needs a requirement change in `Cargo.toml` and a code review for breaking changes; - **Kind** (Normal, Development, Build) and **Platform**. Useful flags are `-R`/`--root-deps-only` to show only direct dependencies, `-w`/`--workspace` for every member, and `--exit-code 1` to make "something is outdated" a failing status, since the default exit code is 0. ## Using them well - Run cargo-machete on pull requests: an unused dependency is cheap to remove and costs build time, attack surface and license review while it stays. - Run cargo-outdated as a report on a schedule, feeding a deliberate update routine; being one minor version behind is rarely a reason to block a merge. - Treat both outputs as prompts for a human decision, not as edits to apply blindly.

  • A crate is used only through code `build.rs` generates into `OUT_DIR`; how do you stop cargo-machete flagging it?
    Add it to `ignored` under `[package.metadata.cargo-machete]` in that package's `Cargo.toml`, with a comment that the generated code uses it. machete only searches the package's own `.rs` source files, so it cannot see the generated file.
  • In cargo-outdated's table, when do Compat and Latest differ, and what does each imply?
    Compat is the newest version your current requirement allows, so `cargo update` alone reaches it. Latest is the newest release overall; when it differs, reaching it means changing the requirement in `Cargo.toml`, usually a new major or 0.x minor, and reviewing the crate's breaking changes.

  • cargo machete compiles the crate to find unused dependencies
  • Every dependency cargo machete reports can be deleted safely
  • cargo outdated fails the CI job by default when updates exist
  • cargo outdated's Latest column is what cargo update will install
  • cargo machete --fix only removes dependencies that are certainly unused