skip to content

Multi-Crate Workspaces

A workspace builds several packages with one Cargo.lock and one target directory, and members inherit shared dependencies. Interviewers ask what a workspace buys a multi-crate project.

on this pageshow

explore

questions

4

In a Cargo workspace, how does a member inherit a dependency from [workspace.dependencies], and what may the member still change on that entry?

level: middleimportance: must knowfreq 50%

answer

  1. declare once at the root
  2. dep.workspace = true
  3. additive features, optional on member side
  4. version key is ignored
  5. default-features override, 2024 edition

basics

~20 s

The root declares the requirement once in [workspace.dependencies]; a member opts in with serde.workspace = true. The member may add features, mark it optional and, since Cargo 1.99 on edition 2024, turn default features off, but not change its version.

solid answer

~40 s

The root `Cargo.toml` declares each shared dependency once, with its version, source and base features, under `[workspace.dependencies]`. A member that needs it writes `serde.workspace = true` (or `serde = { workspace = true, features = ["rc"] }`) in `[dependencies]`, `[dev-dependencies]`, `[build-dependencies]` or a target table. Inheritance is opt-in: a member that does not list it does not get it. Besides `workspace`, a member may set only `optional`, `features` (added to the workspace's) and, since Cargo 1.99 for edition 2024 members, `default-features`. A `version` written next to `workspace = true` is ignored with an `unused manifest key` warning, and `optional = true` in the root table is a parse error. `[workspace.package]` works the same way for metadata: `version.workspace = true`.

code

toml · 26 lines
toml
# Cargo.toml (workspace root)
[workspace]
members = ["crates/*"]
resolver = "3"

[workspace.package]
version = "0.4.0"
edition = "2024"
license = "MIT OR Apache-2.0"

[workspace.dependencies]
serde = { version = "1.0.200", features = ["derive"] }
serde_json = "1.0"
ledger-core = { path = "crates/core" }

# crates/api/Cargo.toml
[package]
name = "ledger-api"
version.workspace = true
edition.workspace = true
license.workspace = true

[dependencies]
ledger-core.workspace = true
serde = { workspace = true, features = ["rc"] }
serde_json.workspace = true

go deeper

for a junior

Recall the two halves: the root declares the dependency once, and each member writes name.workspace = true to use it.

for a middle

Explain which keys a member may still set (features added, optional, default-features on edition 2024 since 1.99) and that a version beside workspace = true is ignored with a warning.

for a senior

Diagnose drift in real repositories: an ignored version key, a default-features override that silently does nothing on an older edition, features unifying back on.

for a principal

Weigh centralising every requirement at the root against letting independently released crates keep their own versions and metadata.

## The problem inheritance solves In a workspace with `ledger-core`, `ledger-api` and `ledger-cli`, the three manifests used to repeat the same requirement, such as `serde = { version = "1.0.200", features = ["derive"] }`, and drift apart over time. Since Cargo 1.64, a workspace can state that requirement once and let members **inherit** it. The single `Cargo.lock` already forces one locked version; inheritance makes the *requirement* one line too. ## Declaring and inheriting 1. In the root manifest, add the entry under `[workspace.dependencies]`, using the same syntax as a normal dependency: a version, a `path`, a `git` source, `features`, `default-features`. 2. In each member that needs it, write `name.workspace = true` (dotted form) or `name = { workspace = true, ... }` (inline table). 3. The member may inherit into `[dependencies]`, `[dev-dependencies]`, `[build-dependencies]` or `[target."cfg(...)".dependencies]`. A **path** in `[workspace.dependencies]` is relative to the workspace root, so `ledger-core = { path = "crates/core" }` lets every member write `ledger-core.workspace = true`. Inheritance is **opt-in per dependency**. Declaring `serde_json` at the root does not add it to any member; only members that name it get it. ## What a member may still set | Key beside `workspace = true` | Effect | |---|---| | `features` | **added** to the workspace entry's features | | `optional` | makes the dependency optional for this member only | | `default-features` | overrides the workspace value, for edition 2024 members on Cargo 1.99 or later | | `version`, `git`, `package` and other keys | not allowed; ignored with an `unused manifest key` warning | Run on Cargo 1.99.1, two of these edges produce messages worth recognising: - A member writing `serde = { workspace = true, version = "1.0.150" }` builds, but Cargo prints `unused manifest key: dependencies.serde.version` and keeps the root's requirement. The Cargo book says inherited entries "cannot use" other keys; the tool enforces that by ignoring them with a warning, not by failing. - `optional = true` **in the root table** fails to parse: `serde_json is optional, but workspace dependencies cannot be optional`. Optionality is a per-member decision, so it lives on the member side. ## Default features and the 1.99 change Since Cargo 1.99, a member on **edition 2024** can write `serde = { workspace = true, default-features = false }` and that member's dependency no longer requests serde's default features, even when the root entry leaves them on. On an earlier edition, Cargo 1.99.1 ignores the key with a warning that ends: `` overriding workspace `default-features` to false requires Rust 1.99+ and the 2024 edition ``. Before 1.99 the book says such a key may be ignored or rejected unless the workspace entry itself disables defaults. Features still unify across the build, so if another member enables serde's defaults and both are built together, serde is compiled with them; that unification belongs with Cargo's feature rules. ## Inheriting package metadata `[workspace.package]` lets members inherit metadata keys the same way: - supported keys include `version`, `edition`, `rust-version`, `license`, `authors`, `description`, `repository`, `homepage`, `readme`, `publish`, `include` and `exclude`; - a member writes `version.workspace = true`, `edition.workspace = true` and so on, **one key at a time**; - inheriting a key the root never defined fails: `` `workspace.package.description` was not defined ``; - in a check with Cargo 1.99.1, `cargo new` inside the workspace wrote `version.workspace = true`, `edition.workspace = true`, `license.workspace = true` and `rust-version.workspace = true` for the keys the root defined, and added the new package to `members` because no glob covered its directory. `name` is never inheritable, since every package needs its own. ## A worked layout The root declares `serde` with `derive` and `ledger-core` by path; `ledger-api` adds `rc` on top. `cargo tree -p ledger-api -e features -i serde` shows one `serde` with `derive` and `rc` and `ledger-core` resolved from the workspace path. Changing the serde requirement for all three crates is now a one-line edit at the root, which is the point: a version bump becomes a single reviewed change rather than three.

  • Why can't the root's [workspace.dependencies] entry say optional = true?
    Whether a dependency is optional is a choice each package makes about its own features, so Cargo only accepts `optional` on the member side. In the root table it is a parse error: `serde_json is optional, but workspace dependencies cannot be optional`. A member writes `serde_json = { workspace = true, optional = true }` and gets the usual implicit or `dep:` feature for it.
  • A member on edition 2021 writes serde = { workspace = true, default-features = false } under Cargo 1.99.1. What happens?
    Cargo ignores the key and warns that overriding the workspace's `default-features` to false requires Rust 1.99+ and the 2024 edition, so serde keeps its default features for that member. The fixes are to move the member to edition 2024, or set `default-features = false` on the root entry and let members that want the defaults add them back through `features`.
  • Does inheriting version.workspace = true make all members share one version forever?
    Only for members that opt in. Each member chooses per key, so a crate released on its own schedule can keep a literal `version = "2.1.0"` while the rest inherit. Lockstep versioning is a team policy; Cargo only supplies the mechanism.

  • Declaring a dependency in [workspace.dependencies] adds it to every member.
  • A member can pin a different version next to workspace = true.
  • Member features replace the workspace entry's features.
  • optional = true belongs in the root's [workspace.dependencies] table.
  • Every [package] key, including name, can be inherited from the workspace.

Assumes Cargo 1.99; workspace inheritance dates from Cargo 1.64, and an edition 2024 member can override default-features only since 1.99.

open as a page

In Cargo, what does a workspace holding api, core and cli crates share across its members that three standalone packages would each keep separately?

level: juniorimportance: should knowfreq 48%

basics

~20 s

A Cargo workspace gives its member packages one Cargo.lock and one target directory at the workspace root, lets one command build or test every member, and reads profiles and [patch] only from the root manifest.

open as a page

In a Cargo virtual manifest, which packages does a bare cargo build at the root compile, and why must that manifest set resolver itself?

level: middleimportance: should knowfreq 38%

basics

~20 s

A virtual manifest has [workspace] and no [package]; a bare cargo build at its root builds every member, or default-members if set. With no edition to infer from, it must set resolver, or Cargo falls back to resolver 1.

open as a page

As a lead, how do you decide how finely to split a Rust codebase into crates in a Cargo workspace, and what does each extra crate cost?

level: principalimportance: should knowfreq 27%

basics

~20 s

Split where it buys something measurable: crates Cargo can compile in parallel, a stable base that edits above it do not rebuild, isolated heavy dependencies, enforced API boundaries. Each crate costs a manifest, a public API, possible orphan-rule friction and lost inlining.

open as a page