Features & Optional Dependencies

Cargo features are the standard way to compile optional code paths, wire optional dependencies, and let consumers pay only for what they enable.

Recipe

[features]
default = ["std"]
std = ["dep:log"]
metrics = ["dep:prometheus"]
 
[dependencies]
log = { version = "0.4", optional = true }
prometheus = { version = "0.13", optional = true }

#[cfg(feature = "metrics")]
pub fn export_metrics() { /* ... */ }

When to reach for this: Optional backends, platform-specific code, or trimming compile time for library consumers.

Working Example

A library with database backends selected by feature:

[features]
default = ["postgres"]
postgres = ["dep:sqlx", "sqlx/postgres"]
sqlite = ["dep:sqlx", "sqlx/sqlite"]
 
[dependencies]
sqlx = { version = "0.8", optional = true, default-features = false }

#[cfg(feature = "postgres")]
pub async fn connect(url: &str) -> sqlx::Result<sqlx::PgPool> {
    sqlx::PgPool::connect(url).await
}
 
#[cfg(feature = "sqlite")]
pub async fn connect(url: &str) -> sqlx::Result<sqlx::SqlitePool> {
    sqlx::SqlitePool::connect(url).await
}

cargo build --no-default-features --features sqlite
cargo test --all-features

What this demonstrates:

• Optional dependencies are inactive until a feature enables them
• Feature names should describe capability, not implementation detail
• dep:sqlx syntax ties a feature directly to an optional crate
• CI should test --no-default-features and --all-features

Deep Dive

Feature Composition

[features]
full = ["json", "metrics"]
json = ["dep:serde", "serde/derive"]

• Features can enable other features (union semantics)
• Enabling full pulls in everything it lists
• Avoid cycles: feature A must not enable B if B enables A

cfg in Code

#[cfg(all(feature = "postgres", not(feature = "sqlite")))]
compile_error!("enable at most one database backend");

• Combine feature, target_os, and custom cfg flags
• Use compile_error! for mutually exclusive feature sets
• Document required feature combinations in crate docs

Rust Notes

#[cfg(feature = "std")]
use std::collections::HashMap;
 
#[cfg(not(feature = "std"))]
use hashbrown::HashMap;

• #[cfg(test)] is separate from Cargo features
• cfg_attr attaches attributes conditionally
• required-features on [[example]] gates runnable demos

Gotchas

• Implicit default features on deps - you pull in heavy code unintentionally. Fix: default-features = false and explicit feature list.
• Feature unification across workspace - one member enabling a feature enables it for all crates sharing that dependency. Fix: split incompatible backends into separate crates if needed.
• Breaking feature renames - downstream features = ["old"] breaks silently at compile time. Fix: treat feature renames as semver-major for libraries.
• No features for internal-only modules - using pub + feature for every private helper creates API confusion. Fix: keep internal modules private; gate only public surface.
• Testing only default features - optional paths rot. Fix: matrix CI with --all-features and per-feature jobs.

Alternatives

FAQs

Related

• Cargo.toml Explained - manifest tables
• Profiles & Build Settings - size vs speed
• Build Scripts (build.rs) - custom cfg flags
• Configuration & Feature Design - app-level design

Stack versions: This page was written for Rust 1.97.0 (edition 2024), Tokio 1.x, Axum 0.8, serde 1.0, sqlx 0.8, clap 4, and Polars 0.46+.