Accessing Cargo Package Metadata in Rust

By the end of this page, you will understand how Rust programs can access Cargo package metadata such as name, version, description, and authors using compile-time environment macros like env! and option_env!. You will also see how this is commonly used in CLI applications, how the values are injected by Cargo, and how to avoid common mistakes.

Cargo exposes selected package metadata from Cargo.toml to your Rust code through environment variables set at compile time. Rust code can read these values using macros such as:

env!("CARGO_PKG_VERSION")

This means the value is embedded into the compiled binary when the project is built.

Common Cargo package metadata variables include:

• CARGO_PKG_NAME
• CARGO_PKG_VERSION
• CARGO_PKG_VERSION_MAJOR
• CARGO_PKG_VERSION_MINOR
• CARGO_PKG_VERSION_PATCH
• CARGO_PKG_AUTHORS
• CARGO_PKG_DESCRIPTION
• CARGO_PKG_HOMEPAGE
• CARGO_PKG_REPOSITORY

Why this matters:

• You avoid duplicating metadata in code and Cargo.toml
• CLI tools can print accurate version information
• Build output stays consistent with package configuration
• Metadata is available without manually parsing Cargo.toml

Think of Cargo as a build assistant that fills out a form before your program is compiled.

Your Cargo.toml is the source form. During compilation, Cargo copies some fields from that form into labeled boxes such as:

• CARGO_PKG_NAME
• CARGO_PKG_VERSION
• CARGO_PKG_DESCRIPTION

Then your Rust code can say, “Put the contents of this box directly into my program.”

So instead of opening and reading Cargo.toml while the program runs, the values are baked into the binary ahead of time.

The most common tool is the env! macro.

Basic syntax

const VERSION: &str = env!("CARGO_PKG_VERSION");

This inserts the package version as a string slice at compile time.

Example: print package version

fn main() {
    println!("Version: {}", env!("CARGO_PKG_VERSION"));
}

If your Cargo.toml contains:

[package]
name = "my_tool"
version = "1.2.3"

The program prints:

Version: 1.2.3

Example: print multiple metadata fields

fn main() {
    println!("Name: {}", env!());
    (, ());
    (, ());
}

Consider this example:

fn main() {
    let name = env!("CARGO_PKG_NAME");
    let version = env!("CARGO_PKG_VERSION");

    println!("{} {}", name, version);
}

Step by step:

1. Cargo reads Cargo.toml.
2. It sees package metadata such as name and version.
3. Cargo sets compile-time environment variables like:
   • CARGO_PKG_NAME
   • CARGO_PKG_VERSION
4. The Rust compiler expands env!("CARGO_PKG_NAME") into a string literal.
5. The Rust compiler expands env!("CARGO_PKG_VERSION") into a string literal.
6. The compiled binary now contains those values directly.
7. When the program runs, it prints something like:

my_tool 1.2.3

Important detail: the program is not reading Cargo.toml at runtime. The values were inserted earlier, during compilation.

Here are common places where Cargo package metadata is useful:

Command-line tools

Display version and name:

println!("{} {}", env!("CARGO_PKG_NAME"), env!("CARGO_PKG_VERSION"));

Useful for:

• --version
• startup banners
• debug output

About text in desktop or terminal apps

You can show:

• app name
• version
• description
• homepage

Logging and diagnostics

When an app starts, it may log its version for support and debugging:

println!("Starting {} v{}", env!("CARGO_PKG_NAME"), env!("CARGO_PKG_VERSION"));

Build identification

Teams often include package version in crash reports, telemetry, or support logs.

Generated help text

CLI frameworks often display metadata pulled from Cargo so users see accurate package information without duplicated strings.

In real Rust projects, developers usually use Cargo metadata in a few standard patterns.

Pattern: constants for reuse

const APP_NAME: &str = env!("CARGO_PKG_NAME");
const APP_VERSION: &str = env!("CARGO_PKG_VERSION");

This avoids repeating the macro throughout the codebase.

Pattern: guard clause for --version

use std::env;

fn main() {
    if env::args().any(|arg| arg == "--version" || arg == "-V") {
        println!("{} {}", env!("CARGO_PKG_NAME"), env!("CARGO_PKG_VERSION"));
        return;
    }

    // normal execution continues here
}

This is a clean example of an early return.

Pattern: optional metadata with fallback

fn app_description()  &  {
    ().()
}

Using runtime environment APIs instead of compile-time macros

Beginners sometimes try this:

use std::env;

fn main() {
    let version = env::var("CARGO_PKG_VERSION").unwrap();
    println!("{}", version);
}

This may fail at runtime because CARGO_PKG_VERSION is typically meant for compile time during Cargo builds, not guaranteed as a runtime environment variable.

Prefer:

fn main() {
    println!("{}", env!("CARGO_PKG_VERSION"));
}

Using env! for optional metadata

This can fail to compile if the variable is not set:

let homepage = env!("CARGO_PKG_HOMEPAGE");

Safer version:

  = ().();

env! vs

env!("CARGO_PKG_NAME")
env!("CARGO_PKG_VERSION")
env!("CARGO_PKG_VERSION_MAJOR")
env!("CARGO_PKG_VERSION_MINOR")
env!("CARGO_PKG_VERSION_PATCH")
option_env!("CARGO_PKG_DESCRIPTION")
option_env!("CARGO_PKG_HOMEPAGE")
option_env!("CARGO_PKG_REPOSITORY")

Rules

• Cargo provides package metadata as compile-time environment variables.
• Use env! for required values.
• Use option_env! for optional values.
• These values are embedded into the binary at compile time.
• Rebuild after changing Cargo.toml.

Common example

println!("{} {}", env!("CARGO_PKG_NAME"), env!("CARGO_PKG_VERSION"));

Good default pattern

const APP_NAME: & = ();
 APP_VERSION: & = ();

How do I get the version from Cargo.toml in Rust?

Use:

env!("CARGO_PKG_VERSION")

This gives you the package version at compile time.

Can I access the package name too?

Yes:

env!("CARGO_PKG_NAME")

Should I read Cargo.toml directly at runtime?

Usually no. For standard package metadata, Cargo already exposes the values you need.

What is the difference between env! and option_env!?

• env! requires the variable to exist
• option_env! returns None if it does not exist

Why does std::env::var("CARGO_PKG_VERSION") not work reliably?

Because Cargo package metadata is typically intended for compile-time use, not guaranteed as a runtime environment variable.

Do I need to rebuild after changing the version in Cargo.toml?

• env! macro — the main compile-time macro used to embed environment variable values into Rust code.
• option_env! macro — useful when metadata may be missing.
• Cargo.toml — the source of Rust package metadata.
• Build scripts (build.rs) — useful when you need custom build-time values beyond standard Cargo metadata.
• Command-line argument parsing — often combined with package metadata for --version and --help output.
• Constants in Rust — commonly used to store package metadata for reuse.
• Environment variables — helps distinguish compile-time and runtime configuration.
• clap crate — a common CLI library that works well with version and package metadata.