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:
[package]
name = "pf"
version = "0.1.0"
edition = "2024"
[dependencies]
serde_json = "1"
regex = "1"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}");
} $ cargo run -q --release
total 64000000The 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:
| Setting | dev | release | What it controls |
|---|---|---|---|
opt-level | 0 | 3 | how hard LLVM optimises |
debug | true | false | debug info in the binary |
debug-assertions | true | false | debug_assert! and cfg(debug_assertions) |
overflow-checks | true | false | panic on integer overflow |
lto | false | false | cross-crate optimisation |
panic | unwind | unwind | unwind or abort on panic |
incremental | true | false | reuse work between builds |
codegen-units | 256 | 16 | how many pieces LLVM gets |
The measured effect on the program above, with the same source in both builds:
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 sThe 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:
[profile.release]
debug = "line-tables-only"
strip = "symbols"
[profile.dev.package."*"]
opt-level = 2The 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:
[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:
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:
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 expectedThe 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:
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.



