Feature Flags and Conditional Compilation

19 min read

Cargo features let one crate ship multiple optional capabilities behind named switches, and #[cfg(...)] lets the compiler include or exclude code before it is ever compiled. Together they replace the runtime if (process.env.FEATURE) and package.json optionalDependencies juggling that TypeScript/JavaScript developers reach for — but the decision happens at compile time, not at runtime.

Quick Overview

A feature is a named flag declared in Cargo.toml under [features]. Enabling a feature can pull in optional dependencies and turn on #[cfg(feature = "...")]-gated code. Because the gating happens at compile time, code behind a disabled feature is not compiled at all — it adds zero bytes to your binary and zero startup cost.

For a TypeScript/JavaScript developer, the closest mental model is bundler dead-code elimination driven by build flags (think process.env.NODE_ENV === "production" checks that a bundler strips) combined with optional peer dependencies. The crucial differences: Rust does this in the language and the compiler (no bundler plugin needed), features are additive (turning one on never turns another off), and feature unification across your whole dependency graph is handled by Cargo.

Note: This page covers the language and manifest mechanics of features and #[cfg]. The dependency-spec syntax for enabling a dependency’s features (features = [...], default-features = false) lives in dependencies.md, and how features interact with [dev-dependencies]/[build-dependencies] and optional = true is in dev-dependencies.md.

TypeScript/JavaScript Example

In TypeScript/JavaScript there is no built-in compile-time feature system, so teams improvise. The two common approaches are runtime environment checks and optional dependencies loaded dynamically:

1
// reporter.ts — runtime feature flags via environment variables
2

3
// Optional dependency: may or may not be installed (declared in
4
// package.json "optionalDependencies"). We must guard the require.
5
type YamlModule = { dump(value: unknown): string };
6

7
interface Report {
8
  name: string;
9
  passed: number;
10
  failed: number;
11
}
12

13
const FEATURES = {
14
  json: process.env.FEATURE_JSON !== "0", // on by default
15
  yaml: process.env.FEATURE_YAML === "1", // off by default
16
  metrics: process.env.FEATURE_METRICS === "1",
17
};
18

19
async function render(report: Report): Promise<string> {
20
  if (FEATURES.json) {
21
    return JSON.stringify(report, null, 2);
22
  }
23

24
  if (FEATURES.yaml) {
25
    // The yaml package might not be installed; this throws at RUNTIME if missing.
26
    const yaml = (await import("js-yaml")) as unknown as YamlModule;
27
    return yaml.dump(report);
28
  }
29

30
  return `${report.name} - ${report.passed} passed, ${report.failed} failed`;
31
}
32

33
if (FEATURES.metrics) {
34
  // Dead code is still shipped in the bundle even when this is false.
35
  console.error("[metrics] reporter initialized");
36
}
37

38
export { render, FEATURES };

The problems a TypeScript/JavaScript developer lives with here:

Everything ships anyway. The yaml branch and the metrics code are in the bundle even when the flags are off. Tree-shaking helps only if the bundler can statically prove the branch is dead.
Failures are at runtime. A missing optional dependency or a typo in a flag name explodes when the code runs, possibly in production.
No type-level guarantee that you only call code that is actually enabled.

Rust Equivalent

In Rust, features are declared in the manifest and the compiler removes disabled code entirely. Here is the same reporter as a Cargo crate.

1
[package]
2
name = "reporter"
3
version = "0.1.0"
4
edition = "2024"
5

6
[features]
7
# `default` lists the features that are on unless the user opts out.
8
default = ["json"]
9
# A feature can pull in OPTIONAL dependencies via the `dep:` syntax.
10
json = ["dep:serde", "dep:serde_json"]
11
yaml = ["dep:serde", "dep:serde_norway"]
12
# A pure code flag with no dependencies of its own.
13
metrics = []
14

15
[dependencies]
16
serde = { version = "1", features = ["derive"], optional = true }
17
serde_json = { version = "1", optional = true }
18
serde_norway = { version = "0.9", optional = true }

1
// Add the `Serialize` derive ONLY when a serializing format is enabled.
2
#[cfg_attr(any(feature = "json", feature = "yaml"), derive(serde::Serialize))]
3
struct Report {
4
    name: String,
5
    passed: u32,
6
    failed: u32,
7
}
8

9
impl Report {
10
    /// Render in whatever format the build was compiled with.
11
    fn render(&self) -> String {
12
        #[cfg(feature = "json")]
13
        {
14
            return serde_json::to_string_pretty(self).expect("serialize json");
15
        }
16
        #[cfg(all(feature = "yaml", not(feature = "json")))]
17
        {
18
            return serde_norway::to_string(self).expect("serialize yaml");
19
        }
20
        #[cfg(not(any(feature = "json", feature = "yaml")))]
21
        {
22
            format!("{} - {} passed, {} failed", self.name, self.passed, self.failed)
23
        }
24
    }
25
}
26

27
fn main() {
28
    let report = Report { name: "build-42".into(), passed: 128, failed: 3 };
29
    println!("{}", report.render());
30
}

Building with the default features (json) produces:

1
{
2
  "name": "build-42",
3
  "passed": 128,
4
  "failed": 3
5
}

Building with cargo run --no-default-features --features yaml:

1
name: build-42
2
passed: 128
3
failed: 3

Building with cargo run --no-default-features (no format at all):

1
build-42 - 128 passed, 3 failed

The serde_norway crate (the maintained successor to the deprecated serde_yaml — see 15-serialization/06_other-formats.md) is never downloaded, compiled, or linked unless someone turns on the yaml feature. Disabled branches contribute nothing to the binary.

Detailed Explanation

The `[features]` table

Each entry maps a feature name to a list of things it enables. Those “things” come in three flavors:

1
[features]
2
default = ["json"]              # 1. other features (the default set)
3
json = ["dep:serde_json"]       # 2. an optional dependency, via `dep:`
4
full = ["json", "yaml", "metrics"] # 3. a bundle that enables several features

Enabling other features lets you build convenience bundles. full = ["json", "yaml", "metrics"] turns on three features at once.
dep:<name> turns on an optional dependency declared with optional = true. The dep: prefix (stable since Rust 1.60) keeps the dependency out of the implicit feature namespace, so adding an optional dependency does not silently create a same-named public feature.
The special default feature is the set Cargo enables when nobody says otherwise.

`#[cfg(feature = "...")]` — the attribute form

#[cfg(...)] is an attribute that conditionally includes the item it is attached to. If the predicate is false, the compiler behaves as if the item does not exist in the source:

1
#[cfg(feature = "metrics")]
2
fn report_metrics() {
3
    println!("metrics: 1 export performed");
4
}
5

6
// A fallback with the SAME name for when the feature is off, so callers
7
// always have a `report_metrics` to call.
8
#[cfg(not(feature = "metrics"))]
9
fn report_metrics() {
10
    // No-op when the `metrics` feature is off.
11
}

You can attach #[cfg] to almost anything: functions, structs, enum variants, impl blocks, modules, use statements, even individual struct fields. A common pattern is gating a whole module:

1
#[cfg(feature = "compression")]
2
pub mod compress {
3
    pub fn level() -> u32 {
4
        6
5
    }
6
}

`cfg!(...)` — the expression form

cfg!(...) is a macro that evaluates to a bool at compile time. The key difference from #[cfg]: both branches of the surrounding if must still type-check and compile, because cfg! only chooses a value, it does not delete code:

1
fn main() {
2
    // Both arms must compile; only the VALUE is decided at compile time.
3
    let level = if cfg!(feature = "verbose") { "verbose" } else { "quiet" };
4
    println!("log level: {level}");
5
}

Use cfg! when both branches are valid regardless of the flag (e.g. choosing a string). Use #[cfg] when the disabled branch references items that only exist under the feature — those would fail to compile if you used cfg!.

`#[cfg_attr(...)]` — conditional attributes

#[cfg_attr(predicate, attribute)] applies another attribute only when the predicate holds. This is how you conditionally derive a trait:

1
// Adds `#[derive(serde::Serialize)]` only when `serde` is enabled.
2
#[cfg_attr(feature = "serde", derive(serde::Serialize))]
3
#[derive(Debug)]
4
struct Config {
5
    retries: u32,
6
    endpoint: String,
7
}

When the serde feature is off, the type still derives Debug but not Serialize, and the serde crate is never pulled in.

`cfg` predicates beyond features

#[cfg] is not limited to features — it is the same mechanism Rust uses for platform-specific code, which needs no [features] entry at all:

1
fn main() {
2
    if cfg!(target_os = "macos") {
3
        println!("running on macOS");
4
    } else {
5
        println!("running on a non-macOS platform");
6
    }
7
}

Common predicates include target_os, target_arch, target_pointer_width, unix, windows, debug_assertions (true in debug builds), and test (true under cargo test). They combine with all(...), any(...), and not(...):

1
#[cfg(all(feature = "yaml", not(feature = "json")))]

Where features come from at build time

Cargo passes the enabled features to rustc as --cfg feature="json" flags. The relevant command-line knobs:

Flag	Effect
`--features "a b"`	Enable features `a` and `b` (space- or comma-separated).
`--no-default-features`	Do not enable the `default` set.
`--all-features`	Enable every feature the crate declares.

These work on cargo build, cargo run, cargo test, cargo check, and friends.

Key Differences

Aspect	TypeScript/JavaScript	Rust features + `#[cfg]`
When the decision happens	Runtime (`process.env`) or bundler build step	Compile time, by the compiler itself
Disabled code	Usually still shipped; tree-shaking is best-effort	Not compiled at all — zero bytes, zero cost
Optional dependency	`optionalDependencies` + guarded dynamic `import()`	`optional = true` dep pulled in by a feature via `dep:`
Failure mode for a missing optional dep	Throws at runtime when reached	Won’t compile if you call code whose feature is off
Combining flags	Ad-hoc booleans	`all(...)` / `any(...)` / `not(...)` predicates
Cross-package coordination	None built in	Feature unification across the whole dependency graph
Intended semantics	Anything goes	Additive — features only add, never remove

Feature unification

This has no TypeScript/JavaScript equivalent and trips up newcomers. If crate A depends on serde with features = ["derive"] and crate B (in the same build) depends on serde with features = ["rc"], Cargo compiles one copy of serde with the union ["derive", "rc"]. Features are unified across the entire graph so that a single build of each crate satisfies everyone.

The direct consequence: enabling a feature anywhere can enable it everywhere, which is precisely why features must be additive. You can inspect the resolved feature graph with:

1
cargo tree -e features

Note: Unlike npm, which can install multiple versions of the same package in nested node_modules, Cargo compiles one build of a crate per semver-compatible version with all requested features merged. There is no per-consumer feature isolation.

Common Pitfalls

Pitfall 1: Calling an item that is gated behind a disabled feature

If you reference a function that only exists under a feature, and that feature is off, the item is “configured out” and the call fails to compile:

1
#[cfg(feature = "advanced")]
2
fn turbo() -> u32 {
3
    9000
4
}
5

6
fn main() {
7
    // does not compile (error[E0425]) when `advanced` is OFF.
8
    println!("{}", turbo());
9
}

Building with the feature off produces a real, helpful error:

1
error[E0425]: cannot find function `turbo` in this scope
2
 --> src/main.rs:8:20
3
  |
4
8 |     println!("{}", turbo());
5
  |                    ^^^^^ not found in this scope
6
  |
7
note: found an item that was configured out
8
 --> src/main.rs:2:4
9
  |
10
1 | #[cfg(feature = "advanced")]
11
  |       -------------------- the item is gated behind the `advanced` feature
12
2 | fn turbo() -> u32 {
13
  |    ^^^^^
14

15
For more information about this error, try `rustc --explain E0425`.

The fix: either provide a #[cfg(not(feature = "advanced"))] fallback with the same signature, or wrap the call site in #[cfg(feature = "advanced")] too.

Pitfall 2: Using `cfg!` where you needed `#[cfg]`

cfg! does not remove code — both arms must compile. This bites when the disabled arm uses a feature-gated item:

1
// If `serde_json` only exists under a feature, this still tries to compile
2
// the call in BOTH arms, so it fails when the feature is off.
3
let out = if cfg!(feature = "json") {
4
    serde_json::to_string(&value).unwrap() // referenced even when off!
5
} else {
6
    String::new()
7
};

Use the attribute form so the disabled branch is genuinely deleted:

1
#[cfg(feature = "json")]
2
let out = serde_json::to_string(&value).unwrap();
3
#[cfg(not(feature = "json"))]
4
let out = String::new();

Pitfall 3: Designing non-additive (mutually exclusive) features

Because of feature unification, a feature that removes or changes behavior is dangerous: some other crate in the graph might turn it on, breaking your build in surprising ways. Anti-pattern:

1
[features]
2
fast = []
3
small = []   # "fast" and "small" are meant to be mutually exclusive — BAD design

If you truly cannot avoid a conflict, fail loudly at compile time with compile_error! rather than silently miscompiling:

1
#[cfg(all(feature = "fast", feature = "small"))]
2
compile_error!("features `fast` and `small` are mutually exclusive; enable only one");

Enabling both then yields a clear error instead of a subtle bug:

1
error: features `fast` and `small` are mutually exclusive; enable only one
2
 --> src/main.rs:4:1
3
  |
4
4 | compile_error!("features `fast` and `small` are mutually exclusive; enable only one");
5
  | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The better fix is almost always to redesign so the two paths are additive (e.g. pick at runtime, or split into two crates).

Pitfall 4: Forgetting your crate compiles with `--no-default-features`

Downstream users routinely disable default features to trim builds. If your default-on code is the only thing that makes the crate usable, a --no-default-features build can break or do nothing useful. Test it in CI:

1
cargo check --no-default-features
2
cargo check --all-features

Pitfall 5: Dead-code warnings when a field is only used by a gated derive

A struct field read only by a #[cfg_attr(..., derive(Serialize))] will warn as dead code when the feature is off, because the serialize impl that reads it no longer exists. Either read the field in some always-compiled path, or annotate it (#[allow(dead_code)]) deliberately. The compiler message is the standard field is never read / #[warn(dead_code)].

Best Practices

Keep features additive. Enabling a feature should only add capability. Never make one feature turn another off or change a function’s meaning.
Make default a sensible, minimal “it just works” set. Put heavy or niche capabilities behind opt-in features so cost-conscious users can strip them with --no-default-features.
Use dep: to gate optional dependencies instead of relying on the old implicit “dependency name becomes a feature” behavior. It keeps your public feature surface intentional.
Document every feature in your crate docs and README, and consider a doc-comment table. Hidden features are a support burden.
Test the feature matrix in CI. At minimum run cargo check --no-default-features and cargo check --all-features. The cargo-hack tool can test each feature in isolation with cargo hack check --feature-powerset.
Prefer #[cfg] (attribute) for code that only exists under a feature, and cfg! (macro) only when both branches genuinely compile.
Name features after capabilities, not implementations (compression, not flate2), so you can swap the implementation later without a breaking change.
Re-enable docs for hidden features. When publishing, docs.rs can be told which features to document via [package.metadata.docs.rs] in Cargo.toml — see publishing.md.

Tip: Use cargo tree -e features to see exactly which features the resolver turned on and why. It is the single most useful command for debugging “why is this dependency being built?”.

Real-World Example

A small library crate that gates an entire module and an optional dependency behind features — the shape of a typical published crate.

1
[package]
2
name = "archive"
3
version = "0.1.0"
4
edition = "2024"
5

6
[features]
7
default = ["compression"]
8
compression = ["dep:flate2"]
9
logging = []
10

11
[dependencies]
12
flate2 = { version = "1", optional = true }

1
//! A tiny library that gates an entire module behind a feature.
2

3
pub fn version() -> &'static str {
4
    "0.1.0"
5
}
6

7
/// Compiled only when the `compression` feature is enabled (it is, by default).
8
#[cfg(feature = "compression")]
9
pub mod compress {
10
    /// The default zlib compression level.
11
    pub fn level() -> u32 {
12
        6
13
    }
14
}
15

16
/// An optional, zero-dependency logging hook.
17
#[cfg(feature = "logging")]
18
pub fn log(msg: &str) {
19
    eprintln!("[log] {msg}");
20
}

A downstream consumer that depends on this crate writes, in its Cargo.toml:

1
[dependencies]
2
# Take only what we need: no compression, but turn on logging.
3
archive = { version = "0.1", default-features = false, features = ["logging"] }

With the default features on, cargo tree shows flate2 and its transitive dependencies being built:

1
archive v0.1.0 (/path/to/archive)
2
└── flate2 v1.1.9
3
    ├── crc32fast v1.5.0
4
    │   └── cfg-if v1.0.4
5
    └── miniz_oxide v0.8.9
6
        ├── adler2 v2.0.1
7
        └── simd-adler32 v0.3.9

Building the same crate with cargo build --no-default-features drops flate2 and everything under it from the build graph entirely — the compress module simply does not exist in that build, so nothing references the compression dependency.

Note: This is a real strength over the TypeScript/JavaScript optional-dependency story: the dependency is not merely unused at runtime, it is never fetched or compiled, which shrinks build times, binary size, and the audited dependency surface.

Exercises

Exercise 1: Add a feature-gated function

Difficulty: Easy

Objective: Declare a feature and gate a function behind it so the crate builds both with and without the feature.

Instructions: Starting from a fresh cargo new feat-ex1, add a pretty feature to Cargo.toml. Write a greeting() function that returns "=== Hello ===" when pretty is on and "Hello" when it is off. Print it from main. Verify both cargo run and cargo run --features pretty.

1
[package]
2
name = "feat-ex1"
3
version = "0.1.0"
4
edition = "2024"
5

6
[features]
7
# TODO: declare the `pretty` feature

1
// TODO: write two cfg-gated `greeting` functions and call one from main.
2
fn main() {
3
    println!("{}", greeting());
4
}

Solution

1
[package]
2
name = "feat-ex1"
3
version = "0.1.0"
4
edition = "2024"
5

6
[features]
7
default = []
8
pretty = []

1
#[cfg(feature = "pretty")]
2
fn greeting() -> &'static str {
3
    "=== Hello ==="
4
}
5

6
#[cfg(not(feature = "pretty"))]
7
fn greeting() -> &'static str {
8
    "Hello"
9
}
10

11
fn main() {
12
    println!("{}", greeting());
13
}

Output of cargo run:

1
Hello

Output of cargo run --features pretty:

1
=== Hello ===

Providing both a #[cfg(feature = "pretty")] and a #[cfg(not(feature = "pretty"))] definition means greeting always exists, so the call site never needs its own #[cfg].

Exercise 2: A feature that enables other features

Difficulty: Medium

Objective: Build a full “bundle” feature that turns on two other features, and report which are active at runtime.

Instructions: Declare features std (in the default set), extras, and full such that enabling full enables both std and extras. In main, use cfg! to collect the active feature names into a Vec<&str> and print them joined by ", ". Verify the output for the default build, --features full, and --no-default-features.

Solution

1
[package]
2
name = "feat-ex2"
3
version = "0.1.0"
4
edition = "2024"
5

6
[features]
7
default = ["std"]
8
std = []
9
# `full` turns on everything; a feature can enable other features.
10
full = ["std", "extras"]
11
extras = []

1
fn main() {
2
    let mut enabled: Vec<&str> = Vec::new();
3
    if cfg!(feature = "std") {
4
        enabled.push("std");
5
    }
6
    if cfg!(feature = "extras") {
7
        enabled.push("extras");
8
    }
9

10
    if enabled.is_empty() {
11
        println!("features: <none>");
12
    } else {
13
        println!("features: {}", enabled.join(", "));
14
    }
15
}

Outputs:

1
# cargo run                                  (default)
2
features: std
3

4
# cargo run --features full
5
features: std, extras
6

7
# cargo run --no-default-features --features full
8
features: std, extras
9

10
# cargo run --no-default-features
11
features: <none>

Note that cfg! is the right tool here because both arms of each if compile no matter which features are on — we are only branching on a bool, not deleting code.

Exercise 3: Mutually exclusive features done safely

Difficulty: Hard

Objective: Model two conflicting build modes and make the conflict a compile error instead of a silent bug, while keeping a sensible default.

Instructions: Declare features fast and small. The program should print "optimized for speed" under fast, "optimized for size" under small, and "balanced defaults" under neither. Enabling both at once must fail to compile with a clear message. Verify: default build prints the balanced message, --features fast prints the speed message, and --features "fast small" fails with your message.

Solution

1
[package]
2
name = "feat-ex3"
3
version = "0.1.0"
4
edition = "2024"
5

6
[features]
7
default = []
8
fast = []
9
small = []

1
// Non-additive features are an anti-pattern; if a conflict is truly
2
// unavoidable, fail LOUDLY at compile time instead of miscompiling.
3
#[cfg(all(feature = "fast", feature = "small"))]
4
compile_error!("features `fast` and `small` are mutually exclusive; enable only one");
5

6
fn main() {
7
    if cfg!(feature = "fast") {
8
        println!("optimized for speed");
9
    } else if cfg!(feature = "small") {
10
        println!("optimized for size");
11
    } else {
12
        println!("balanced defaults");
13
    }
14
}

Outputs:

1
# cargo run                       (default)
2
balanced defaults
3

4
# cargo run --features fast
5
optimized for speed
6

7
# cargo build --features "fast small"
8
error: features `fast` and `small` are mutually exclusive; enable only one
9
 --> src/main.rs:4:1
10
  |
11
4 | compile_error!("features `fast` and `small` are mutually exclusive; enable only one");
12
  | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Tip: The “correct” production answer is usually to redesign so the two modes are additive (decide at runtime, or split into two crates), because feature unification means some other crate in the graph could enable both — the compile_error! guard is your safety net, not your design.

Feature Flags and Conditional Compilation

Quick Overview

TypeScript/JavaScript Example

Rust Equivalent

Detailed Explanation

The [features] table

#[cfg(feature = "...")] — the attribute form

cfg!(...) — the expression form

#[cfg_attr(...)] — conditional attributes

cfg predicates beyond features

Where features come from at build time

Key Differences

Feature unification

Common Pitfalls

Pitfall 1: Calling an item that is gated behind a disabled feature

Pitfall 2: Using cfg! where you needed #[cfg]

Pitfall 3: Designing non-additive (mutually exclusive) features

Pitfall 4: Forgetting your crate compiles with --no-default-features

Pitfall 5: Dead-code warnings when a field is only used by a gated derive

Best Practices

Real-World Example

Further Reading

Exercises

Exercise 1: Add a feature-gated function

Exercise 2: A feature that enables other features

Exercise 3: Mutually exclusive features done safely

The `[features]` table

`#[cfg(feature = "...")]` — the attribute form

`cfg!(...)` — the expression form

`#[cfg_attr(...)]` — conditional attributes

`cfg` predicates beyond features

Pitfall 2: Using `cfg!` where you needed `#[cfg]`

Pitfall 4: Forgetting your crate compiles with `--no-default-features`