Skip to content
rusthacks.dev

Cargo Profiles Explained Dev Release and Custom Profiles

Profiles are named sets of compiler settings. Learn dev, release, test and bench, the keys that matter, per-package overrides and how to define a custom profile that inherits from release.

6 min read
Summarize in AI
Flat illustration for the post “Cargo Profiles Explained Dev Release and Custom Profiles”, composed around perf.

Cargo builds your code twice as often with two different compilers as you might think. cargo build and cargo build --release are not the same compiler with a speed flag; they are two profiles, each a bundle of settings for optimisation level, debug information, overflow checks and more. Knowing what is in those bundles explains why this post's debug build ran sixteen times slower than release, why a release binary can be too big to ship, and why a setting you added seems to do nothing. This post shows the built-in profiles, measures them on a real program, defines a custom one and breaks three things on purpose.

Every build below ran on Cargo 1.99 with edition 2024 on a 10-core Apple M1 Max, with serde_json 1 and regex 1 as the only dependencies.

The program the numbers come from

To see profile differences you need a program that does real work. This one parses a small JSON document and runs a regular expression over each item 200,000 times, which is enough to keep the CPU busy for a noticeable fraction of a second in an optimised build:

Cargo.tomlTOML
[package]
name = "pf"
version = "0.1.0"
edition = "2024"

[dependencies]
serde_json = "1"
regex = "1"
src/main.rsrust
use regex::Regex;
use serde_json::Value;

fn main() {
    let re = Regex::new(r"(\d+)-(\w+)").expect("valid pattern");
    let doc = r#"{"items":[{"id":"12-alpha"},{"id":"7-beta"},{"id":"301-gamma"}]}"#;
    let v: Value = serde_json::from_str(doc).expect("valid json");
    let mut total = 0u64;
    for _ in 0..200_000 {
        for item in v["items"].as_array().expect("array") {
            let id = item["id"].as_str().expect("string");
            if let Some(c) = re.captures(id) {
                total += c[1].parse::().expect("digits");
            }
        }
    }
    println!("total {total}");
}
Text
$ cargo run -q --release
total 64000000

The answer is checkable by hand: the three numbers are 12, 7 and 301, which sum to 320, and 320 times 200,000 is 64,000,000. A benchmark whose output you can verify is the only kind worth trusting.

What the two built-in profiles set

Cargo has four built-in profiles: dev (the default for cargo build and cargo run), release (for --release), test and bench, the last two inheriting from the first two. The defaults are worth knowing by heart, because every override is a change against them:

SettingdevreleaseWhat it controls
opt-level03how hard LLVM optimises
debugtruefalsedebug info in the binary
debug-assertionstruefalsedebug_assert! and cfg(debug_assertions)
overflow-checkstruefalsepanic on integer overflow
ltofalsefalsecross-crate optimisation
panicunwindunwindunwind or abort on panic
incrementaltruefalsereuse work between builds
codegen-units25616how many pieces LLVM gets

The measured effect on the program above, with the same source in both builds:

Text
profile    clean build   binary size    run time (best of 5)
dev        2.7 s         6,131,632 B    1.43 s
release    4.2 s         2,234,928 B    0.09 s

The same work took 1.43 s in the dev build and 0.09 s in release, sixteen times faster, while the release build cost almost twice the compile time (2.7 s against 4.2 s, clean, with dependencies; an incremental dev rebuild after touching one line took 0.20 s). The dev binary is also nearly three times larger, because it carries debug information and unoptimised code.

Why the dev profile exists as it does

The defaults are tuned for the edit-compile-run loop. Opt-level 0 skips almost every optimisation, which is why a rebuild after touching one line took 0.20 s here. Debug info lets a debugger show variable names. Overflow checks turn silent wraparound into a panic you can find: in the dev profile, u8::MAX + 1 aborts with "attempt to add with overflow", and in release it wraps to zero, a difference worth keeping in mind when a bug appears only in production. The release profile reverses each choice, because there the goal is a fast and small artefact and nobody is stepping through it.

Overriding a setting

Put a [profile.NAME] table in the root manifest and set only what you change. This is the common shape for a project that wants some debug info in release for profiling, and decent speed for its dependencies in dev:

Cargo.tomlTOML
[profile.release]
debug = "line-tables-only"
strip = "symbols"

[profile.dev.package."*"]
opt-level = 2

The first table keeps line numbers for a profiler, then strips symbols from the final binary; on this program the result is 1,740,944 bytes, essentially the same as a plain strip = true build (1,740,928), because stripping removes what debug added. The second table is a package override: "*" means every dependency but not your own crate, so slow-to-debug libraries such as regex run optimised in dev builds while your own code stays fast to rebuild. It is among the most useful settings in Cargo and almost nobody knows it exists. Override a single dependency with [profile.dev.package.regex].

A custom profile

When you need a third configuration, define it and name what it inherits from. A release-like profile with full link-time optimisation for distribution builds, kept separate so everyday --release stays quick:

Cargo.tomlTOML
[profile.dist]
inherits = "release"
lto = "fat"
codegen-units = 1
strip = true
panic = "abort"

Build it with cargo build --profile dist; the binary lands in target/dist/, a different directory from target/release/, so the two never invalidate each other. On this program the dist combination produced a 1,345,008 byte binary in 12.4 s, against 2,234,928 bytes in 4.2 s for plain release: 40 percent smaller for nearly three times the build time. Whether that is a good trade depends on how often you ship, which is the subject of release profile settings and the individual LTO and codegen-units costs.

Three ways profiles go wrong

A custom profile without inherits is rejected immediately:

Text
error: profile `bench-fast` is missing an `inherits` directive (`inherits` is required for all profiles except `dev` or `release`)

A bad value is reported by Cargo or the compiler, with the allowed set spelled out:

Text
error: must be `0`, `1`, `2`, `3`, `s` or `z`, but found the string: "fast"
  --> Cargo.toml:11:13
   |
11 | opt-level = "fast"
   |             ^^^^^^

error: incorrect value `full` for codegen option `lto` - either a boolean (`yes`, `no`, `on`, `off`, etc), `thin`, `fat`, or omitted was expected

The quiet one is a profile in the wrong place. Profiles are read only from the workspace root, and a [profile.release] inside a member crate is ignored with a warning, not an error:

Text
warning: profiles for the non root package will be ignored, specify profiles at the workspace root:

That warning scrolls past in a long build. If a setting in a member manifest seems to have no effect, this is why, and the fix is to move the table to the root.

What profiles cannot do

A profile sets compiler behaviour for a whole build; it cannot make one function fast and another small, which is what #[inline], #[cold] and per-package overrides are for. Profiles also do not change what code is compiled: cfg(debug_assertions) follows the debug-assertions setting, so a release build with debug-assertions = true runs your assertions, a useful trick for a staging environment. Finally, the numbers above come from one program on one machine; a program dominated by memory allocation or I/O will see smaller gaps between profiles than a tight loop over a regex. Measure yours with the build commands above rather than adopting someone else's table. The complete settings list is in the profiles chapter.

Taggedprofiles
Share

Keep reading

Flat illustration for the post “Stale While Revalidate Caching in Rust Services Explained”, composed around perf.
Performance

Stale While Revalidate Caching in Rust Services Explained

Serve the cached value immediately, even if slightly old, and refresh it in the background. Learn the idea, the HTTP Cache-Control directives and an in-process implementation with a freshness window and a grace window.

4 min read

Get new posts by email

We send one email when a new post is published. No spam.

Unsubscribe in one click. No spam, ever.