cargo-locate-project

Display the JSON object with full path to the Cargo.toml manifest

$ cargo locate-project

$ cargo locate-project --message-format [plain|json]

$ cargo locate-project --workspace

$ cargo locate-project --manifest-path [path/to/Cargo.toml]

cargo locate-project [OPTIONS]

--workspace
    Return the path to the workspace root's Cargo.toml instead of the current package's root Cargo.toml. If the current package is part of a workspace, this will print the workspace root. If not, it will still point to the package's own Cargo.toml.

--message-format
    Set the output format for the project path. Supported formats include json for machine-readable output and the default plain for just the path.

--help
    Print a brief help message.

cargo locate-project is a utility subcommand for the Rust package manager, Cargo. Its primary function is to programmatically determine and print the absolute path to the Cargo.toml file that defines the current Rust project or workspace. When executed within a Rust project directory, it navigates up the directory tree until it finds the nearest Cargo.toml file and outputs its path.

This command is particularly useful for scripting and build systems that need to locate the project root, independent of the current working directory. It provides options to specify whether to find the package root or the workspace root, and to control the output format for machine readability.

This command must be run within a directory that is part of a Cargo project or workspace. If no Cargo.toml file is found in the current directory or any parent directories, the command will exit with an error. The output path always points to the Cargo.toml file itself, not its containing directory.

The --message-format option significantly affects the output. When set to json, the command outputs a JSON object containing a single key root whose value is the absolute path to the Cargo.toml file. For example:
{"root":"/path/to/your/project/Cargo.toml"}

The default behavior (without --message-format or with --message-format plain) is to simply print the absolute path to the Cargo.toml file to standard output, followed by a newline.

cargo locate-project was introduced as a core utility within the Cargo ecosystem to provide a standardized and reliable mechanism for scripts and external tools to programmatically discover the root of a Cargo project or workspace. This capability is crucial for automated build pipelines, IDE integrations, and custom tooling that need to operate from the correct project context, regardless of the current working directory. It streamlined project interaction by offering a consistent API for root identification.

cargo(1), cargo new(1), cargo init(1), pwd(1)