How I Use Cargo Workspace to structure my Rust projects

2025-09-03T00:00:00+00:00

I’ve learn to use Cargo Workspace from Olivia’s post in bluesky</a>, which you should checkout. This article is a way of self-documenting since I’ve come back to it more often. </blockquote>
🔗</a>What is a Cargo Workspace</h2>
A cargo workspace is collection of one or more library or binary crates. Cargo workspace let’s you break your rust project into multiple different crates (or packages), which may aid you in better project structure and management.
🔗</a>Why use Cargo Workspace</h2>

Your rust project has grown big and is hard to manage</li>
Multiple people work on a project, so breaking your project into multiple crates can help with better ownership and less conflict among developers</li>
You want to reduce your project’s compile time</li> </ul>

Read this (external link): Cutting Down Rust Compile Times From 30 to 2 Minutes With One Thousand Crates</a> </blockquote>
🔗</a>Creating a Workspace</h2>
Create a new workspace directory
mkdir runner cd runner</code></pre> Now create Cargo.toml</code> with following content
[workspace] resolver = "3"</code></pre> Here we are using resolver</code> version 3, which is the latest version and comes in Rust 2024 edition (Rust 1.84+). Resolver tells cargo how to resolve the dependencies.
🔗</a>Create a binary crate</h3> We are going to use cargo new</code> command to create a binary crate. When no argument is passed, cargo new command will create binary crate by default, you can use --lib</code> as argument to create library crate or --bin</code> to explicit that you want binary crate. cargo new run</code></pre> Now your workspace will look like this: . ├── Cargo.toml └── run ├── Cargo.toml └── src └── main.rs</code></pre> If you look at your workspace’s Cargo.toml</code> you will notice that cargo has already added the newly added crate run</code> against the members</code> key. [workspace] resolver = "3" members = ["run"]</code></pre>🔗</a>Adding lib crates</h3> Let’s add two lib crates cargo new participant --lib cargo new track --lib</code></pre> Updated structure: . ├── Cargo.lock ├── Cargo.toml ├── participant │ ├── Cargo.toml │ └── src │ └── lib.rs ├── run │ ├── Cargo.toml │ └── src │ └── main.rs └── track ├── Cargo.toml └── src └── lib.rs</code></pre>🔗</a>Adding dependencies</h3> If you try to simply add a dependency like this cargo add uuid --features v4</code></pre> ‼️ it will fail and you will see this error error: `cargo add` could not determine which package to modify. Use the `--package` option to specify a package. available packages: participant, run, track</code></pre> Since inside our Cargo workspace we have 3 packages, therefore cargo is unable to determine to which package dependency belongs to. ✅ We can solve this by using --package</code> arg. cargo add uuid --features v4 --package participant</code></pre>🔗</a>Dependency Resolution</h3> Since in cargo workspace we can have multiple crates, which means we have to add dependency to each crate separately and in that sometimes there may be a version mismatch. Like with uuid</code> in participant</code> crate, it is using version 1.18.1</code> and now you if you try to add uuid</code> of different version in run</code> crate, for example if we want to stick to only 1.17</code> version of the uuid</code> crate: cargo add uuid@=1.17 --features v4 --package run</code></pre> But wait, we got error error: failed to select a version for `uuid`. ... required by package `run v0.1.0 (/home/vivek/Documents/code/hands-on/runner/run)` versions that meet the requirements `=1.17` are: 1.17.0 all possible versions conflict with previously selected packages. previously selected package `uuid v1.18.1` ... which satisfies dependency `uuid = "^1.18.1"` of package `participant v0.1.0 (/home/vivek/Documents/code/hands-on/runner/participant)` failed to select a version for `uuid` which could resolve this conflict</code></pre> It’s because a Cargo workspace can only have one Cargo.lock</code> file, which is shared between all the members of the workspace, so it can only have one version of the dependency across the workspace. So instead of pinning to =1.17</code> version of uuid, we had used just 1.17</code>, cargo would have choosen uuid@1.18.1</code> since that was already being used by participant</code> crate. In order to resolve the dependency across workspace, cargo will try to find the most suitable version of a crate, mostly by downgrading to the appropriate version. </blockquote> 🔗</a>Better way to declare dependency</h3> It’s very normal to have common dependencies across crates, that is why Cargo Workspace let us declare dependencies in workspace’s Cargo.toml</code> and then you can re-use the same dependency inside of your crate. # Cargo.toml [workspace.dependencies] uuid = { version = "=1.17", features = ["v4"] }</code></pre> And then in your crates you can use the dependency with: # participant/Cargo.toml [dependencies] uuid = { workspace = true } # run/Cargo.toml [dependencies] uuid = { workspace = true }</code></pre>🔗</a>Importing members as dependencies</h3> A common way to import a crate (or package) inside another crate is like this: # run/Cargo.toml [dependencies] participant = { path = "../participant" } track = { path = "../track" } # track/Cargo.toml [dependencies] participant = { path = "../participant" }</code></pre> But now if you had to do this for each of the crate in your project and sometime there can be a lot of crates. Also the path is relative to the current Cargo.toml file, so if you dare re-structure your workspace, it can backfire and you will have another mess to deal with. However we can use the same way of delcaring the dependency in the workspace’s Cargo.toml</code> and then just use it inside the members by telling cargo to use workspace’s dependency. # Cargo.toml [workspace] resolver = "3" members = ["participant", "run", "track"] [workspace.dependencies] participant = { path = "participant" } track = { path = "track" } # run/Cargo.toml [dependencies] participant = { workspace = true } track = { workspace = true } # track/Cargo.toml [dependencies] participant = { workspace = true }</code></pre>🔗</a>Multiple Binaries</h3> When you have multiple binaries in your workspace, cargo run</code> won’t work since it doesn’t know which binary crate to run. So instead explicitly pass the crate name: cargo run --package my_bin_crate</code></pre>🔗</a>Cheat sheet</h2> Create workspace: # Cargo.toml [workspace] resolver = "3"</code></pre> Adding bin and lib to workspace: # creates binary crate cargo new my_bin # crates lib crate cargo new my_lib --lib</code></pre> Importing dependencies: # Add dependencies in workspace's Cargo.toml [workspace.dependencies] uuid = { version = "=1.17", features = ["v4"] } # import in members like this: my_lib/Cargo.toml [dependencies] uuid = { workspace = true }</code></pre> Import members like this: # Cargo.toml [workspace] resolver = "3" members = ["my_bin", "my_lib"] [workspace.dependencies] my_lib = { path = "my_lib" } # my_bin/Cargo.toml [dependencies] my_lib = { workspace = true }</code></pre> Other commands: # run if multiple binaries exist cargo run --package my_bin # build specific binary cargo build --package my_bin # build all cargo build --all # test all cargo test --all</code></pre>

Vivek Shukla - Cargo

How I Use Cargo Workspace to structure my Rust projects