Rust Cargo Workspaces
A workspace is a group of crates managed together under one top-level Cargo.toml. It allows shared dependency resolution, unified builds/tests, and centralized configuration.
Declaration
Top-level Cargo.toml:
[workspace]
resolver = "2" # use new feature resolver (optional)
members = ["crate_a", "crate_b", "examples/*"]
exclude = ["old_crate"]
[workspace.dependencies] # optional
serde = "1" # shared dependency for all members
resolverβ "1" (default) or "2" (new, more flexible, better for dependency resolution).membersβ list of crate paths included in the workspace. Can use globs (examples/*).excludeβ paths to ignore (e.g., archived crates).[workspace.dependencies]β dependencies shared by all members.- Members can override locally or use
workspace = trueto inherit.
- Members can override locally or use
Member Crates
crate_a/Cargo.toml example:
[package]
name = "crate_a"
version = "0.1.0"
[dependencies]
serde = { workspace = true } # pulls version from workspace
tokio = { version = "1", optional = true } # local override
crate_b = { path = "../crate_b" } # inter-crate dependency
Notes:
workspace = trueβ ensures all crates use the same version from[workspace.dependencies].- Inter-crate path dependencies are local and versioned independently from crates.io.
- Optional features can still be enabled per member.
Common Workspace Features & Gotchas
Profiles (
[profile.dev],[profile.release])
* Can be defined globally under `[workspace]`.
* Member crates inherit unless overridden.
Shared Lints / Metadata
Publishing
- Each member crate is published separately unless marked
publish = false. - Workspace crate cannot be published itself; only members.
Examples / Tests / Benches
- Members can have their own
examples/,tests/,benches/. - Workspace allows
cargo test --allorcargo build --all.
Dev-dependencies in Workspace
- Dev-dependencies are not shared by default.
[workspace.dev-dependencies]can be declared to avoid repeating them in each member.
Features Across Workspace
- Each crate manages its own features.
- Can βforwardβ dependency features using
dep:crateorcrate/feature. cargo build --all-featuresβ enables all features in all workspace members.
Overriding Dependencies
- Overrides a crate globally for all workspace members.
Commands
cargo buildβ builds current cratecargo build -p crate_aβ builds specific membercargo build --allβ builds all workspace memberscargo test --allβ runs all tests across workspacecargo check --workspaceβ checks all members without buildingcargo update -p crate_nameβ update a dependency for all members
Real-world Notes
- Large OSS projects use workspaces to avoid multiple lockfiles and keep dependencies consistent.
- Optional features and dev-dependencies often vary per crate; shared dependencies minimize version conflicts.
- Beware of cyclic dependencies β Cargo forbids them even inside a workspace.
- Path dependencies are local and always take precedence over crates.io.