cargo-public-api

List and diff the public API of Rust library crates between releases and commits. Detect breaking API changes and semver violations via CI or a CLI. Relies on and automatically builds rustdoc JSON, for which a recent version of the Rust nightly toolchain must be installed.

Installation

Install the cargo public-api subcommand with a recent regular stable Rust toolchain:

cargo +stable install cargo-public-api

Ensure nightly-2025-08-02 or later is installed (does not need to be the active toolchain) so cargo public-api can build rustdoc JSON for you:

rustup install nightly --profile minimal

Usage

List the Public API

This example lists the public API of the regex crate. First we clone the repo:

git clone https://github.com/rust-lang/regex ; cd regex

Now we can list the public API of regex by running

cargo public-api

which will print the public API of regex with one line per public item in the API:

Diff the Public API

… Against a Specific Published Version

To diff the public API of the regex crate in the current directory against published version 1.6.0 on crates.io:

cargo public-api diff 1.6.0

… Against the Latest Published Version

cargo public-api diff latest

… Between Git Commits

cargo public-api diff ref1..ref2

… as a CI Check

With a regular cargo test that you run in CI you will be able to * prevent accidental changes to your public API * review the public API diff of deliberate changes

First add the latest versions of the recommended libraries to your [dev-dependencies]:

cargo add --dev \
    rustup-toolchain \
    rustdoc-json \
    public-api

Then add the following test to your project. As the author of the below test code, I hereby associate it with CC0 and to the extent possible under law waive all copyright and related or neighboring rights to it:

#[test]
fn public_api() {
    // Install a compatible nightly toolchain if it is missing.
    rustup_toolchain::install(public_api::MINIMUM_NIGHTLY_RUST_VERSION).unwrap();

    // Build rustdoc JSON.
    let rustdoc_json = rustdoc_json::Builder::default()
        .toolchain(public_api::MINIMUM_NIGHTLY_RUST_VERSION)
        .build()
        .unwrap();

    // Derive the public API from rustdoc JSON.
    let public_api = public_api::Builder::from_rustdoc_json(rustdoc_json)
        .build()
        .unwrap();

    // Assert that the public API matches the latest snapshot.
    // Run with env var `UPDATE_SNAPSHOTS=yes` to update the snapshot.
    public_api.assert_eq_or_update("./tests/snapshots/public-api.txt");
}

Before you run the test the first time you need create a snapshot of the current public API:

UPDATE_SNAPSHOTS=yes cargo test

This creates a tests/public-api.txt file in your project that you git add together with your other project files. Then a regular

cargo test

will fail if your public API is accidentally or deliberately changed. Run

UPDATE_SNAPSHOTS=yes cargo test

again to update the public API snapshot and review the git diff.

Less Noisy Output

For completeness, items belonging to Blanket Implementations, Auto Trait Implementations, and Auto Derived Implementations, such as

• impl<T, U> Into<U> for T where U: From<T>
• impl Sync for ...
• impl Debug for ... / #[derive(Debug)]

are included in the list of public items by default. Use

• --omit blanket-impls
• --omit auto-trait-impls
• --omit auto-derived-impls

respectively to omit such items from the output to make it much less noisy:

cargo public-api --omit blanket-impls,auto-trait-impls,auto-derived-impls

For convenience you can also use -s (--simplified) to achieve the same thing. This is a shorter form of the above command:

cargo public-api -sss

Compatibility Matrix

Contributing

See CONTRIBUTING.md.

Maintainers

• Enselic
• douweschulte
• Emilgardis

Trademark Notice

"Rust" and "Cargo" are trademarks of the Rust Foundation. This project is not affiliated with, endorsed by, or otherwise associated with the Rust Project or Rust Foundation.