rustc -C opt-level and -O: optimization levels 0-3, s and z

rustc -C opt-level=3 main.rs compiles with full optimization; -O is a shortcut for -C opt-level=2. Plain rustc uses level 0, no optimization, which is why a single file compiled by hand runs much slower than a Cargo release build. The level also changes behaviour: at level 0 debug assertions and integer overflow checks are enabled, at higher levels they are off unless you turn them on with -C debug-assertions and -C overflow-checks.

Same code, different levels

The program adds 1 to a u8 that holds 255:

cat > ov.rs <<'EOF'
fn main() {
    let x: u8 = std::env::args().count() as u8 + 254;
    let y = x + 1;
    println!("y = {y}, debug_assertions = {}", cfg!(debug_assertions));
}
EOF
echo "== default (opt-level 0)"
rustc ov.rs -o ov0 && ./ov0 2>&1 | sed -E "s/^thread 'main' \([0-9]+\)/thread 'main'/"; echo "exit: ${PIPESTATUS[0]}"
echo "== -C opt-level=3"
rustc -C opt-level=3 ov.rs -o ov3 && ./ov3
echo "== -O"
rustc -O ov.rs -o ovO && ./ovO
echo "== -C opt-level=3 -C overflow-checks=on"
rustc -C opt-level=3 -C overflow-checks=on ov.rs -o ovc && ./ovc 2>&1 | sed -E "s/^thread 'main' \([0-9]+\)/thread 'main'/"; echo "exit: ${PIPESTATUS[0]}"
echo "== invalid level"
rustc -C opt-level=4 ov.rs; echo "exit: $?"

== default (opt-level 0)

thread 'main' panicked at ov.rs:3:13:
attempt to add with overflow
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace
exit: 101
== -C opt-level=3
y = 0, debug_assertions = false
== -O
y = 0, debug_assertions = false
== -C opt-level=3 -C overflow-checks=on

thread 'main' panicked at ov.rs:3:13:
attempt to add with overflow
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace
exit: 101
== invalid level
error: optimization level needs to be between 0-3, s or z (instead was `4`)

exit: 1

At level 0 the overflow panics with attempt to add with overflow and exit code 101. Optimized builds wrap to 0 and report debug_assertions = false; adding -C overflow-checks=on brings the panic back. (The sed only removes the thread number that recent Rust versions print in panic messages.)

Levels

Values outside this list are rejected: optimization level needs to be between 0-3, s or z.

With Cargo

Cargo passes -C opt-level from the active profile, so you rarely type it there:

[profile.dev]
opt-level = 1            # faster debug binaries

[profile.dev.package."*"]
opt-level = 3            # optimize dependencies even in dev builds

[profile.release]
opt-level = 3            # default
overflow-checks = true   # keep overflow panics in release

cargo build --release selects the release profile (see cargo build --release). For one-off builds you can also pass flags through RUSTFLAGS="-C opt-level=2" or cargo rustc --release -- -C opt-level=s, but profiles are easier to review.

Pitfalls

• Benchmarks of rustc file.rs binaries are meaningless: add -O or -C opt-level=3.
• Code that relies on wrapping overflow should say so with wrapping_add or std::num::Wrapping; otherwise it panics in debug builds and wraps in release builds.
• opt-level alone does not strip debug info or symbols; use -C debuginfo=0 and -C strip=symbols (or the debug and strip profile keys) to shrink the binary further.

FAQ