skip to content

A Rust command-line tool's release binary is 2.5 MB; which Cargo profile settings make it smaller, and what does each one cost?

level: middleimportance: must knowfreq 60%

answer

  1. measure one key at a time
  2. size levels are not guaranteed smaller
  3. whole-program optimisation at link time
  4. unwinding tables and the symbol table

basics

~20 s

In the release profile: lto = true, codegen-units = 1, panic = "abort", strip = true and opt-level "s" or "z", each measured alone. They cost build time, backtraces or panic recovery; since Cargo 1.77 debuginfo is already stripped by default.

solid answer

~50 s

I would add settings to `[profile.release]` (or a custom profile that inherits it) and measure each one. `lto = true` (fat LTO) optimises across all crates and drops unused code, at the cost of a much slower link. `codegen-units = 1` gives LLVM the whole crate at once, which shrinks and speeds the code but compiles less in parallel. `panic = "abort"` removes unwinding machinery, but a panic then ends the process at once. `strip = true` means `"symbols"`: it removes the symbol table as well as debuginfo, so backtraces lose function names. `opt-level = "s"` or `"z"` optimise for size, but the Cargo book warns they are not necessarily smaller. Since Cargo 1.77, a profile with debug info off already strips debuginfo outside Windows MSVC, so `strip = "debuginfo"` adds nothing to a default release build.

code

toml · 7 lines
toml
[profile.min-size]
inherits = "release"
opt-level = "z"
lto = true
codegen-units = 1
panic = "abort"
strip = true

go deeper

for a junior

Recall the five keys that shrink a release build, lto, codegen-units, panic, strip and opt-level "s" or "z", and that they go under a profile table in Cargo.toml.

for a middle

Explain what each key does and costs, that strip = true means "symbols", and that debuginfo is already stripped by default since Cargo 1.77 outside Windows MSVC.

for a senior

Insist on measuring one change at a time with -v to confirm the flags, and call out the behaviour changes, abort on panic and lost backtrace names, before accepting the size win.

for a principal

Weigh size against build minutes and diagnosability, and decide whether size tuning lives in the release profile or in a separate profile used only for shipped artifacts.

## Start from what the release profile already does A **profile** is the bundle of compiler settings Cargo applies to a build; `cargo build --release` uses the `release` profile. Its defaults are tuned for runtime speed, not size: `opt-level = 3`, `debug = false`, `lto = false`, `codegen-units = 16`, `panic = "unwind"`, `strip = "none"`. One detail is easy to miss. **Since Cargo 1.77, turning debug info off implies `strip = "debuginfo"`** when `strip` is not set, so Cargo strips the pre-built debuginfo that the standard library carries. Running `cargo build --release -v` shows `-C strip=debuginfo` on the `rustc` line even though `strip` defaults to `"none"`. Cargo 1.78 stopped doing this on Windows MSVC targets because it broke backtraces there. Writing `strip = "debuginfo"` into a default release profile therefore changes nothing on macOS or Linux. ## The keys that change size | key | what it does | what it costs | |---|---|---| | `lto = true` / `"fat"` | link-time optimisation across every crate in the graph | much longer link; more memory while linking | | `lto = "thin"` | cheaper cross-crate LTO, aimed at speed | may barely change size | | `codegen-units = 1` | the crate is optimised as one unit | slower, less parallel compile | | `panic = "abort"` | no unwinding tables or landing pads | a panic kills the process; no recovery | | `strip = true` (= `"symbols"`) | removes the symbol table and debuginfo | backtraces and profilers lose names | | `opt-level = "s"` / `"z"` | optimise for size; `"z"` also turns off loop vectorisation | can be slower; not always smaller | ## What one measurement showed A small tool built from `clap` and `regex` with Cargo 1.99.1 on aarch64 macOS, each custom profile inheriting `release` and changing one key: - default release: 2,577,104 bytes; - `opt-level = "z"` alone: 2,860,704 bytes — **larger**, exactly the surprise the Cargo book warns about; - `strip = true`: 2,010,096; `lto = true`: 2,025,936; `codegen-units = 1`: 2,035,552; `panic = "abort"`: 2,242,448; - all five together: 1,166,432 bytes, under half the default. The lesson is procedural. Settings interact: `opt-level = "z"` made things worse alone, yet the smallest build combined it with fat LTO and one codegen unit, where LLVM can see enough code to make size choices pay. **Measure each change** on your own binary and target rather than copying a table. ## What each cost means in practice 1. **Build time.** Fat LTO plus `codegen-units = 1` can turn a release build that took seconds into one that takes minutes on a large dependency graph. That is why many teams keep these in a separate custom profile used only for shipped artifacts. 2. **Panic behaviour.** With `panic = "abort"` the process terminates on the first panic: destructors do not run on the way out and nothing can catch the panic. What catching a panic means in code is the language's topic; for the build, the point is that this is a behaviour change, not a free size win. Tests, benchmarks, build scripts and proc macros ignore the `panic` setting. 3. **Diagnostics.** On the same macOS build, `RUST_BACKTRACE=1` on a default release binary listed function names, while the `strip = true` binary listed no frames at all. The panic message, with its file and line, still printed, because that text is compiled into the program. `rustc`'s own documentation advises programs that want crash reporting to avoid `-C strip=symbols`. 4. **Runtime speed.** `"s"` and `"z"` trade speed for size; LTO and one codegen unit usually help both. ## Levers outside the profile Two big ones are not profile keys. Trimming dependency features (turning off a crate's default features) is the job of the feature flags; linker choices belong to Cargo's config file. Both can matter as much as anything above, but they live in other parts of the build. ## Why the combination beat the parts - **Fat LTO** lets the optimiser see across crate boundaries, so code from dependencies that the tool never calls can be dropped. - **One codegen unit** removes the duplication and missed inlining that come from splitting a crate into 16 pieces. - With the whole program visible, **`opt-level = "z"`** has room to choose smaller code paths, a likely reason it helped in combination and hurt alone. ## A sensible order - Confirm you are measuring a `--release` build, not `target/debug`. - Add `lto = true` and `codegen-units = 1`; measure. - Decide deliberately about `panic = "abort"` and `strip = true`, because both change behaviour, not just size. - Try `opt-level = "s"` and `"z"` last, and keep whichever your measurements prefer.

  • What do you give up with `strip = true` compared with the default release build?
    `strip = true` equals `strip = "symbols"`: the symbol table goes as well as debuginfo. On macOS, `RUST_BACKTRACE=1` on such a binary printed no frames, where the default release binary still listed function names. The panic message with file and line survives. `rustc` advises crash-reporting programs to avoid `-C strip=symbols`.
  • How do you check which flags a profile actually passes to `rustc`?
    Run the build with `-v`, for example `cargo build --release -v`. Each `Running` line shows the full `rustc` command, so you can see `-C opt-level=3`, `-C lto`, `-C codegen-units=1` or the implied `-C strip=debuginfo` and confirm the profile you edited is the one in effect.
  • Does `lto = false` mean no link-time optimisation at all?
    No. `lto = false` is the default and means "thin local LTO": thin LTO within the current crate across its codegen units, skipped when `codegen-units` is 1 or `opt-level` is 0. `lto = "off"` disables LTO entirely, and Cargo then passes `-C lto=off`.

  • opt-level = "z" on its own always gives the smallest binary.
  • Adding strip = "debuginfo" shrinks a default release build on Linux or macOS.
  • panic = "abort" only changes the panic message, not the program.
  • lto = false means the compiler does no link-time optimisation at all.
  • codegen-units = 1 makes release builds compile faster.
  • strip = true removes the file and line from panic messages.

Assumes Cargo 1.99; since Cargo 1.77 a profile with debug info off strips debuginfo by default (no longer on Windows MSVC since 1.78).