skip to content

In a Cargo.toml, what do `default` in `[features]`, `--no-default-features` and `default-features = false` each control?

level: middleimportance: must knowfreq 65%

answer

  1. on unless someone opts out
  2. command line vs dependency entry
  3. --features adds, it does not replace
  4. another dependent can still ask

basics

~20 s

The default feature lists what Cargo turns on automatically. --no-default-features switches it off for the packages built from the command line; default-features = false does the same in a dependency entry, but another dependent can still re-enable them.

solid answer

~40 s

Every Cargo feature is off unless something enables it, and `default = [...]` in `[features]` is the one feature Cargo enables on its own. A database-client crate with `default = ["tls-rustls"]` builds with rustls unless the user opts out. On the command line, `--no-default-features` drops the default feature of the selected packages, and `--features` (`-F`) only *adds* features, so `-F tls-native` alone still leaves `tls-rustls` on. In a dependent's Cargo.toml, `default-features = false` stops *that entry* from requesting the defaults. It is not a graph-wide guarantee: if any other package in the build depends on the crate with defaults, Cargo unifies the requests and the defaults come back.

code

toml · 9 lines
toml
# db-client/Cargo.toml
[features]
default = ["tls-rustls"]
tls-rustls = []
tls-native = []

# worker/Cargo.toml
[dependencies]
db-client = { path = "../db-client", default-features = false, features = ["tls-native"] }

go deeper

for a junior

Recall that features are off unless enabled, that default is the one Cargo turns on by itself, and the two ways to opt out: a command-line flag and a key in the dependency entry.

for a middle

Explain that --features adds rather than replaces, that --no-default-features covers only the selected packages, and show the flag combination that builds exactly one non-default backend.

for a senior

Show why default-features = false is a request, not a guarantee: a second dependent with a plain entry brings the defaults back, and cargo tree -e features -i names that dependent.

for a principal

Treat the default set as a public promise: it decides what most users compile, removing an entry later is a breaking change, and intermediate libraries should opt out so the application decides.

## The default feature A **Cargo feature** is a named flag declared in the `[features]` table of a package's Cargo.toml. Each feature lists other features (or optional dependencies) that it turns on, and Cargo passes every enabled feature to rustc as a `--cfg feature="..."` flag. The Cargo book states the starting point plainly: *all features are disabled unless explicitly enabled*. The one exception is the feature named `default`. Cargo enables it automatically whenever the package is built, and through it whatever it lists. Take a database-client crate: - `default = ["tls-rustls"]` — rustls support is on for every user who does nothing special; - `tls-rustls = []` and `tls-native = []` — two TLS backends, each an empty marker feature; - a user who wants the native backend must say so, and must also decide what to do about the default. `default` is an ordinary feature in every other respect: it can list several features, and `cargo tree -f "{p} {f}"` prints it beside the others, as `default,tls-rustls`. ## Turning defaults off from the command line Three flags control features for the packages you build: 1. `--features` (short `-F`) enables the listed features, comma- or space-separated; inside a workspace `package/feature` targets one member. 2. `--no-default-features` does not activate the `default` feature of the **selected packages** — the ones named with `-p`, or the current package. 3. `--all-features` activates every feature of the selected packages. The trap is that `--features` *adds*. Running `cargo build -F tls-native` on the database client builds it with `default`, `tls-rustls` **and** `tls-native`. To get only the native backend you combine the two flags: `cargo build --no-default-features -F tls-native`. None of these flags reach into dependencies: a dependency keeps whatever its dependency entries asked for. ## Turning defaults off in a dependency entry In a dependent's manifest the switch is a key on the dependency: ```toml [dependencies] db-client = { path = "../db-client", default-features = false, features = ["tls-native"] } ``` This entry asks for `tls-native` and nothing else. A dependency written as a plain version string, or as a table without the key, asks for the defaults: Cargo enables a dependency's default features unless that entry says `default-features = false`. ## Why the opt-out is not a guarantee Cargo compiles a dependency with the **union** of the features every dependent in the build requested. So `default-features = false` means "I do not request the defaults", not "the defaults are off". If a second crate in the same build depends on `db-client` with a plain entry, that entry requests `default`, and `tls-rustls` is on for everyone. The Cargo book warns about exactly this: to keep a dependency's defaults off, *every* package that depends on it must say `default-features = false`. | Where | Spelling | Scope | |---|---|---| | Library's Cargo.toml | `default = ["tls-rustls"]` | what is on when nobody opts out | | Command line | `--no-default-features` | the selected packages only | | Command line | `-F tls-native` | adds to whatever is already on | | Dependent's Cargo.toml | `default-features = false` | this one request, not the whole graph | ## Reading what Cargo enabled `cargo tree -f "{p} {f}"` prints the final feature list beside each package, so each of the cases above can be checked rather than guessed: 1. a plain `cargo tree -p db-client` shows `default,tls-rustls`; 2. adding `--no-default-features` shows an empty list; 3. adding only `-F tls-native` shows `default,tls-native,tls-rustls`, both backends at once; 4. the worker, whose entry says `default-features = false, features = ["tls-native"]`, shows `tls-native` alone, as long as nothing else in its build asks for the defaults. When the list is longer than expected, the inverted form, `cargo tree -e features -i db-client`, names the dependent behind every extra feature. ## What this means in practice - Choose the default set with care: the defaults are what most users get, and removing a feature from it later is usually a breaking change under Cargo's SemVer guidance. - A library that depends on another library should usually write `default-features = false` and list only what it needs, so it does not force defaults onto the final application. - `cargo test`, Clippy and `cargo doc` use the default set unless told otherwise, so a CI job that also runs `cargo build --no-default-features` catches code that silently relies on a default. - When a default "will not turn off", `cargo tree -e features -i <crate>` shows which package requested it.

  • With that database client's defaults, what does `cargo build -F tls-native` actually enable?
    `default`, `tls-rustls` and `tls-native`. `--features` adds to the default set rather than replacing it, so both backends are on. To build only the native backend you write `cargo build --no-default-features -F tls-native`.
  • Does `--no-default-features` also switch off the default features of the crate's dependencies?
    No. It applies to the packages selected on the command line. Each dependency still gets the features its dependency entries request, including its defaults unless an entry says `default-features = false`.
  • Why can a library's own `cargo test` pass while a user's `default-features = false` build fails?
    Tests, Clippy and docs build with the default set unless told otherwise, so code that quietly needs a default feature compiles in CI. Adding `cargo build --no-default-features` (and `--all-features`) to CI builds the other configurations too.

  • Passing --features tls-native replaces the default feature list
  • default-features = false guarantees the defaults stay off in the final build
  • Every feature is on unless you disable it
  • --no-default-features also strips defaults from every dependency in the graph
  • --all-features turns on every feature of every dependency