cargo-metadata

Print the workspace members and resolved dependencies of the current package

$ cargo metadata

$ cargo metadata --no-deps

$ cargo metadata --format-version [version]

$ cargo metadata --filter-platform [target_triple]

cargo metadata [OPTIONS]

--no-deps
    Excludes dependency information from the output, limiting the metadata to direct package details.

--format-version <VERSION>
    Specifies the format version of the output JSON. This allows tools to parse future versions of the metadata.

--filter-platform <TRIPLE>
    Filters targets and dependencies by a specific compilation target triple (e.g., 'x86_64-unknown-linux-gnu').

--offline
    Prevents Cargo from accessing the network during metadata collection.

--frozen
    Requires Cargo.lock to be up-to-date and prevents it from being updated.

--locked
    Requires Cargo.lock to exist and be up-to-date.

--manifest-path <PATH>
    Path to the Cargo.toml file for which to generate metadata.

--workspace
    Outputs metadata only for workspace members, excluding information about external dependencies.

-v, --verbose
    Use verbose output for Cargo messages during the operation.

-q, --quiet
    Suppresses all Cargo log messages, only printing the JSON output.

--color <WHEN>
    Controls the coloring of Cargo messages (auto, always, never).

cargo-metadata is a crucial subcommand of the Rust package manager, Cargo. It is designed to output comprehensive, machine-readable information about a Rust project's workspace, packages, targets, features, and dependencies in JSON format.

Unlike other Cargo commands that perform actions like building or checking, cargo-metadata focuses purely on data extraction. This makes it an indispensable tool for external applications such as Integrated Development Environments (IDEs), build systems, continuous integration/continuous delivery (CI/CD) pipelines, and custom scripting.

The command provides a structured representation of the project, including details about individual packages (name, version, authors, licenses), their targets (libraries, executables, tests, benchmarks, examples), enabled features, and a complete dependency graph. By offering this data programmatically, cargo-metadata eliminates the need for external tools to parse Cargo.toml files directly, ensuring accurate and consistent understanding of complex Rust projects. Its primary use case is to enable sophisticated tooling to analyze, navigate, and interact with Rust workspaces effectively.

The output of cargo-metadata can be extremely large for projects with many dependencies, potentially consuming significant memory or disk space if piped to a file.

While designed for machine readability, direct human interpretation of the raw JSON output can be challenging without proper formatting tools like jq(1).

The --format-version option is crucial for ensuring compatibility with future Cargo versions, as the exact structure of the JSON output may evolve.

The output is a single JSON object with several top-level fields:

      packages: An array of all packages in the workspace and its dependency graph, each containing detailed information (name, version, authors, targets, features, etc.).

      resolve: A graph representing the resolved dependency tree for all packages, showing which version of each dependency was selected.

      workspace_members: An array of package IDs that are members of the current workspace.

      workspace_root: The absolute path to the workspace root directory.

      target_directory: The absolute path to the build output directory.

cargo-metadata is heavily utilized by tools like rust-analyzer (the official Rust Language Server), linters, static analysis tools, and custom build scripts to understand project structure, resolve paths, and determine compilation targets without manual parsing of configuration files. This programmatic interface ensures consistency and robustness across the Rust development ecosystem.

cargo-metadata is an integral part of the Cargo build system, developed alongside Rust to facilitate programmatic access to project information. Its initial design aimed to support IDEs and other development tools that require a structured understanding of Rust workspaces and their dependencies. While its core functionality has remained stable, the output JSON format has evolved, necessitating the --format-version option to ensure backward compatibility and smooth transitions for tools relying on its output. It has been a key component in enabling the rich tooling ecosystem around Rust.

cargo(1) - The Rust package manager and build tool., cargo-build(1) - Compiles the current package., cargo-check(1) - Analyzes the current package and reports errors, but doesn't build., jq(1) - A lightweight and flexible command-line JSON processor.