How to Check Debug vs Release Builds in Rust with cfg and cfg!

By the end of this page, you will understand how Rust handles conditional compilation for debug and release builds, when to use #[cfg(debug_assertions)] versus cfg!(debug_assertions), and how these differ from C-style preprocessor checks. You will also see practical examples, common mistakes, and typical usage patterns from real Rust codebases.

Rust does not have a C-style text preprocessor for #if defined(...) checks. Instead, it uses conditional compilation through the #[cfg(...)] attribute and the cfg!(...) macro.

The key idea is this:

• #[cfg(...)] includes or excludes code at compile time.
• cfg!(...) evaluates to true or false in an expression, but both branches must still be valid Rust code.

For distinguishing normal debug builds from optimized release builds, the most common built-in configuration is:

#[cfg(debug_assertions)]

This configuration is enabled when debug assertions are on, which is typically true for cargo build and typically false for cargo build --release.

So in practice:

• cargo build -> debug_assertions is usually enabled
• cargo build --release -> debug_assertions is usually disabled

Think of #[cfg(...)] as a build-time gate.

If the condition matches, the compiler lets that code through the gate. If it does not match, the compiler acts as if that code was never there.

Think of cfg!(...) as a build-time fact turned into a boolean value.

It answers questions like:

• "Were debug assertions enabled when this code was compiled?"
• "Are we compiling for Windows?"

A simple analogy:

• #[cfg(...)] is like deciding which rooms get built into a house.
• cfg!(...) is like asking, after the house is built, whether a certain room exists.

This difference matters because code behind #[cfg(...)] can be completely omitted, while code inside an if cfg!(...) { ... } else { ... } must still parse and type-check.

Rust commonly uses debug_assertions for debug-vs-release conditional behavior.

Using #[cfg(...)]

Use this when you want code to exist only in certain builds.

#[cfg(debug_assertions)]
fn build_mode() {
    println!("Debug build");
}

#[cfg(not(debug_assertions))]
fn build_mode() {
    println!("Release build");
}

fn main() {
    build_mode();
}

Why this works

• In a debug build, only the first build_mode function is compiled.
• In a release build, only the second one is compiled.

Using cfg!(...)

Use this when you need a boolean inside an expression.

fn main() {
    if cfg!(debug_assertions) {
        println!("Debug build");
    } else {
        ();
    }
}

Consider this example:

fn main() {
    if cfg!(debug_assertions) {
        println!("Debug build");
    } else {
        println!("Release build");
    }
}

Here is what happens step by step:

1. The compiler sees cfg!(debug_assertions).
2. It checks whether the debug_assertions configuration is enabled for this build.
3. It replaces that macro result with a constant boolean value.
   • In a typical debug build, this becomes true.
   • In a typical release build, this becomes false.
4. The code behaves like this in a debug build:

fn main() {
    if true {
        println!("Debug build");
    } else {
        println!("Release build");
    }
}

1. Or like this in a release build:

 () {
      {
        ();
    }  {
        ();
    }
}

Here are common reasons to check debug vs release behavior in Rust:

Extra logging during development

if cfg!(debug_assertions) {
    eprintln!("Loading configuration from test path");
}

Useful when debugging startup behavior without cluttering release output.

Expensive validation checks

#[cfg(debug_assertions)]
fn validate_state(values: &[i32]) {
    assert!(values.windows(2).all(|w| w[0] <= w[1]));
}

This lets you catch logic bugs during development without paying the cost in production.

Debug-only helper functions

#[cfg(debug_assertions)]
fn dump_cache_state() {
    println!("Dumping cache state for inspection...");
}

These helpers can be fully compiled out in release builds.

Testing internal assumptions

Libraries and applications often use debug_assert! or to verify assumptions that should never fail if the program is correct.

In real Rust projects, developers usually do not check for release mode directly. Instead, they express intent more clearly.

Common patterns

1. debug_assert! for development-time checks

fn divide(a: i32, b: i32) -> i32 {
    debug_assert!(b != 0, "b should not be zero here");
    a / b
}

This is preferred when the goal is to catch programming mistakes during development.

2. #[cfg(debug_assertions)] for debug-only code

#[cfg(debug_assertions)]
println!("Detailed parser state: {:?}", parser);

This is good for diagnostic output or expensive checks.

3. Guarding helper functions or modules

#[cfg(debug_assertions)]
mod debug_tools {
    pub fn report() {
        println!("Debug tools enabled");
    }
}

This keeps development-only utilities out of production binaries.

Mistake 1: Thinking Rust has a C-style preprocessor

Broken mental model:

// This is not how Rust works
#if DEBUG
println!("debug");
#endif

Rust does not do source-text preprocessing like C. Use #[cfg(...)] or cfg!(...) instead.

Mistake 2: Using cfg!(...) when code should be excluded entirely

if cfg!(debug_assertions) {
    use_debug_only_api();
} else {
    normal_api();
}

Problem:

• Both branches must still compile.
• If use_debug_only_api() is unavailable in release builds, this may fail.

Use #[cfg(...)] when code should not exist at all:

#[cfg(debug_assertions)]
use_debug_only_api();

#[cfg(not(debug_assertions))]
normal_api();

Mistake 3: Assuming is always identical to "not release"

Quick reference

Debug-only compilation

#[cfg(debug_assertions)]
fn debug_only() {
    println!("Only compiled in debug-style builds");
}

Release-only compilation

#[cfg(not(debug_assertions))]
fn release_only() {
    println!("Only compiled when debug assertions are off");
}

Boolean check inside expressions

if cfg!(debug_assertions) {
    println!("Debug build");
}

Debug-only assertion

debug_assert!(value >= 0);

Rules to remember

• #[cfg(...)] removes code from compilation when the condition does not match.
• cfg!(...) returns a boolean but does not remove surrounding code from type-checking.
• debug_assertions is the normal Rust way to distinguish typical debug and release behavior.

How do I check for a debug build in Rust?

Use #[cfg(debug_assertions)] or cfg!(debug_assertions). In normal Cargo workflows, this corresponds to typical debug builds.

How do I check for a release build in Rust?

Use #[cfg(not(debug_assertions))] or !cfg!(debug_assertions).

What is the difference between #[cfg] and cfg! in Rust?

#[cfg] conditionally includes or excludes code from compilation. cfg! returns a boolean value inside expressions.

Is debug_assertions the same as cargo build --release?

Not exactly. It indicates whether debug assertions are enabled. In default Cargo profiles, it usually lines up with debug vs release builds.

Should I use build checks for application logic?

Usually no. Restrict them to diagnostics, assertions, logging, or development-only validation.

Can I create my own build flags in Rust?

Yes. Common options include Cargo features, build scripts, and profile configuration.

Why does code inside if cfg!(...) still need to compile?

• #[cfg] attributes — The core Rust mechanism for conditional compilation.
• cfg! macro — Useful when you need conditional behavior as a boolean expression.
• debug_assert! — A common companion for development-only checks.
• Cargo profiles — Control settings for debug and release builds.
• Cargo features — Used for custom compile-time switches.
• Conditional compilation — The broader concept behind platform-specific or build-specific code.
• Attributes in Rust — #[cfg(...)] is one example of an attribute.
• Assertions in Rust — Helps understand assert! vs debug_assert!.