Optimizing Build Performance

Cargo configuration options and source code organization patterns can help improve build performance, by prioritizing it over other aspects which may not be as important for your circumstances.

Same as when optimizing runtime performance, be sure to measure these changes against the workflows you actually care about, as we provide general guidelines and your circumstances may be different, it is possible that some of these approaches might actually make build performance worse for your use-case.

Example workflows to consider include:

Cargo and Compiler Configuration

Cargo uses configuration defaults that try to balance several aspects, including debuggability, runtime performance, build performance, binary size and others. This section describes several approaches for changing these defaults that should be designed to maximize build performance.

Common locations to override defaults are:

Reduce amount of generated debug information

Recommendation: Add to your Cargo.toml or .cargo/config.toml:

[profile.dev]
debug = "line-tables-only"

[profile.dev.package."*"]
debug = false

[profile.debugging]
inherits = "dev"
debug = true

This will:

Note: re-evaluating the dev profile is being tracked in #15931.

Trade-offs:

Use an alternative codegen backend

Recommendation:

This will change the dev profile to use the Cranelift codegen backend for generating machine code, instead of the default LLVM backend. The Cranelift backend should generate code faster than LLVM, which should result in improved build performance.

Trade-offs:

Enable the experimental parallel frontend

Recommendation: Add to your .cargo/config.toml:

[build]
rustflags = "-Zthreads=8"

This rustflags will enable the parallel frontend of the Rust compiler, and tell it to use n threads. The value of n should be chosen according to the number of cores available on your system, although there are diminishing returns. We recommend using at most 8 threads.

Trade-offs:

Use an alternative linker

Consider: installing and configuring an alternative linker, like LLD, mold or wild. For example, to configure mold on Linux, you can add to your .cargo/config.toml:

[target.'cfg(target_os = "linux")']
# mold, if you have GCC 12+
rustflags = ["-C", "link-arg=-fuse-ld=mold"]

# mold, otherwise
linker = "clang"
rustflags = ["-C", "link-arg=-fuse-ld=/path/to/mold"]

While dependencies may be built in parallel, linking all of your dependencies happens at once at the end of your build, which can make linking dominate your build times, especially for incremental rebuilds. Often, the linker Rust uses is already fairly fast and the gains from switching may not be worth it, but it is not always the case. For example, Linux targets besides x86_64-unknown-linux-gnu still use the Linux system linker which is quite slow (see rust#39915 for more details).

Trade-offs:

Resolve features for the whole workspace

Consider: adding to your project's .cargo/config.toml

[resolver]
feature-unification = "workspace"

When invoking cargo, features get activated based on which workspace members you have selected. However, when contributing to an application, you may need to build and test various packages within the application, which can cause extraneous rebuilds because different sets of features may be activated for common dependencies. With feature-unification, you can reuse more dependency builds by ensuring the same set of dependency features are activated, independent of which package you are currently building and testing.

Trade-offs:

Reducing built code

Removing unused dependencies

Recommendation: periodically review unused dependencies for removal using:

$ cargo +nightly check -Zcargo-lints --workspace --all-targets

This may have false positives from:

Also, periodically review hidden cargo::unused_dependencies results:

$ CARGO_LOG=cargo::diagnostics::rules::unused_dependencies=debug cargo +nightly check -Zcargo-lints --workspace --all-targets

This will show potential unused dependencies for

When changing code, it can be easy to miss that a dependency is no longer used and can be removed.

Trade-offs:

Removing unused features from dependencies

Recommendation: Periodically review unused features from dependencies for removal using third-party tools like cargo-features-manager, cargo-unused-features.

When changing code, it can be easy to miss that a dependency's feature is no longer used and can be removed. This can reduce the number of transitive dependencies being built or reduce the amount of code within a crate being built. When removing features, extra caution is needed because features may also be used for desired behavior or performance changes which may not always be obvious from compiling or testing.

Trade-offs: