cargo-pkgid

Print the fully qualified package specification for the current project

$ cargo pkgid

$ cargo pkgid [partial_pkgspec]

cargo pkgid [SPEC] [OPTIONS]

SPEC
    The package specification to resolve. If omitted, resolves the current package in the working directory.

-p SPEC, --package SPEC
    Specify the package to operate on (and output its ID). This is an alternative to providing SPEC directly as an argument.

--workspace
    Output the package ID for the workspace root package. Implies --all when used with --message-format=json.

--workspace-root
    Output the absolute path to the workspace root directory instead of a package ID.

--query-cargo-home
    Output the absolute path to Cargo's home directory instead of a package ID.

--all
    Output all package IDs in the workspace. Usually used with --message-format=json for structured output.

--manifest-path PATH
    Path to the Cargo.toml file. Defaults to the one in the current directory or a parent directory.

-q, --quiet
    Do not print warnings or other informational messages to standard error.

--offline
    Run without accessing the network.

--frozen
    Require Cargo.lock to be up to date and do not make any network requests.

--locked
    Require Cargo.lock to be up to date but allow network requests.

--color WHEN
    Controls when colors are used in output: auto, always, or never.

--target-dir DIR
    Directory for generated artifacts and intermediate files.

-h, --help
    Prints help information.

cargo pkgid is a utility subcommand of Cargo, Rust's package manager, designed to resolve and output the package ID for a given package specification. A package ID uniquely identifies a package in Cargo's build graph, typically represented as a URL-like string (e.g., file:///path/to/my-package?version=1.0.0 or https://github.com/rust-lang/cargo?tag=cargo-0.60.0).

This command is primarily used in scripting contexts where a unique, canonical identifier for a package is required. It can resolve local workspace packages, registry dependencies, or Git dependencies. By default, it prints the package ID of the current package to standard output. It's an essential tool for build systems and CI/CD pipelines that need to interact programmatically with Cargo's understanding of packages.

cargo pkgid is designed for machine-readable output. Its primary output is a single line string (the package ID, path, or Cargo home). It's not intended for human-readable debugging of package dependencies. For more detailed package information, consider cargo metadata or cargo tree. The command requires a valid Cargo project context to function correctly, unless --query-cargo-home is used.

A package ID is a URL-like string that uniquely identifies a package. The format can vary depending on the package's origin (local path, registry, Git repository). Examples:
file:///path/to/project?version=1.2.3
registry+https://github.com/rust-lang/crates.io-index#my-crate@1.0.0
git+https://github.com/rust-lang/cargo?tag=cargo-0.60.0#abcdef12345

This command is particularly useful in shell scripts or CI/CD pipelines to dynamically get a package's canonical identifier or relevant paths. For instance, to get the current package's ID:

CURRENT_PKG_ID=$(cargo pkgid)

Or to find the workspace root:

WORKSPACE_ROOT=$(cargo pkgid --workspace-root)

These outputs can then be used by other commands or scripts that require a specific package reference or project path.

cargo pkgid has been a part of the Cargo toolkit since early versions of the Rust programming language and its package manager. It provides a stable and consistent way to query package identities, serving as a fundamental building block for more complex build scripts and automation tasks within the Rust ecosystem. Its design emphasizes simplicity and machine-readability for programmatic interaction.

cargo(1), cargo-metadata(1), cargo-tree(1), rustc(1)