23.6 Build Profiles

Build profiles allow you to configure compiler settings for different scenarios. Cargo defines four profiles by default: dev, release, test, and bench. The dev and release profiles are the most commonly used.

  • dev: The default profile used by cargo build and cargo run. Optimized for fast compilation times.
    • opt-level = 0 (no optimization)
    • debug = true (include debug info)
  • release: Used when the --release flag is passed. Optimized for runtime performance.
    • opt-level = 3 (maximum optimization)
    • debug = false (omit debug info by default)

You can customize these profiles in Cargo.toml under [profile.*] sections:

[profile.dev]
opt-level = 1       # Enable basic optimizations even in debug builds
# debug = 2         # Use '2' for full debug info, '1' for line tables only, '0' for none

[profile.release]
lto = "fat"         # Enable "fat" Link-Time Optimization for potentially better performance/size
codegen-units = 1   # Reduce parallelism for potentially better optimization (slower build)
panic = 'abort'     # Abort on panic instead of unwinding (can reduce binary size)
# strip = true      # Strip symbols from the binary (requires Rust 1.59+)

Key profile settings include:

  • opt-level: Controls the level of optimization (0, 1, 2, 3, s for size, z for more size).
  • debug: Controls the amount of debug information included (true/2, false/0, 1).
  • lto: Enables Link-Time Optimization (false, true/“thin”, "fat", "off"). Can improve performance but increases link times.
  • codegen-units: Number of parallel code generation units. More units mean faster compilation but potentially less optimal code. 1 can yield the best optimizations.
  • panic: Strategy for handling panics ('unwind' or 'abort').

Profile settings in a dependency’s Cargo.toml are ignored; only the settings in the top-level crate’s Cargo.toml (the one being built directly) are used.