Lesson 17 of 26
Cargo in depth: dependencies and workspaces
Lesson 1 made a tiny crate with one file. Real projects have more: dependencies from crates.io (Rust's PyPI,
with documentation built automatically on docs.rs), several modules, a library next to the program, and
sometimes many crates in one repository. When you open a Rust repository, almost everything you need to know is in
two places: Cargo.toml and the src/ folder.
A crate is either a binary (a program, it has src/main.rs) or a library (code for other
crates, it has src/lib.rs), or both.
Where things live
A typical crate next to a typical Python package. The biggest difference is in the last lines:
Rust's build output goes to target/. It can be large, it is never committed, and you can delete it any time.
shop/
โโโ pyproject.toml
โโโ uv.lock
โโโ src/shop/
โ โโโ __main__.py
โ โโโ __init__.py
โ โโโ models.py
โ โโโ payments/
โ โโโ __init__.py
โ โโโ stripe.py
โโโ tests/
โ โโโ test_models.py
โโโ .venv/shop/
โโโ Cargo.toml
โโโ Cargo.lock
โโโ src/
โ โโโ main.rs
โ โโโ lib.rs
โ โโโ models.rs
โ โโโ payments.rs
โ โโโ payments/
โ โโโ stripe.rs
โโโ tests/
โ โโโ models.rs
โโโ target/Cargo.toml vs pyproject.toml
Both are TOML files, and most sections match one to one. The one surprise is version strings: in Cargo,
"0.12" does not mean exactly 0.12. It means "0.12 or any compatible update". Cargo follows
semantic versioning by default, as if you always wrote Python's ~=.
There is no [project.scripts]: src/main.rs is the program, and it gets the crate's name.
[project]
name = "shop"
version = "0.1.0"
requires-python = ">=3.12"
dependencies = [
"requests>=2.31,<3",
"pydantic[email]>=2,<3",
]
[dependency-groups]
dev = ["pytest>=8"]
[project.scripts]
shop = "shop.__main__:main"[package]
name = "shop"
version = "0.1.0"
edition = "2024"
rust-version = "1.85"
[dependencies]
reqwest = "0.12"
serde = { version = "1", features = ["derive"] }
[dev-dependencies]
pretty_assertions = "1"
[profile.release]
lto = trueModules are files, but only when you say so
In Python, every .py file inside a package can be imported. In Rust, a file only becomes part of
the crate when its parent declares it with mod name;. So when you read a crate, start at
main.rs or lib.rs and follow the mod lines. They are the table of contents.
Everything is private unless marked pub (lesson 2).
# src/shop/models.py
class Order:
...
# src/shop/payments/stripe.py
def charge(cents):
...
# src/shop/payments/__init__.py
# (often empty)
# src/shop/__main__.py
from shop.models import Order
from shop.payments.stripe import charge
order = Order()
charge(250)// src/models.rs
pub struct Order {
// ...
}
// src/payments/stripe.rs
pub fn charge(cents: u32) {
// ...
}
// src/payments.rs
pub mod stripe;
// src/main.rs
mod models;
mod payments;
use models::Order;
use payments::stripe::charge;
fn main() {
let _order = Order {};
charge(250);
}Adding and updating dependencies
cargo add edits Cargo.toml for you. Cargo.lock records the exact
versions that were picked, just like uv.lock. Commit it, so everyone (and CI) builds the same thing.
cargo update moves the lock file forward within the ranges in Cargo.toml.
uv add requests
uv add 'pydantic[email]'
uv add --dev pytest
uv lock --upgrade-package requests
uv treecargo add reqwest
cargo add serde --features derive
cargo add --dev pretty_assertions
cargo update -p reqwest
cargo treeWorkspaces: several crates in one repository
Bigger projects split their code into several crates in one repository, a workspace. All members
share one Cargo.lock and one target/ folder. This is the same idea as a uv workspace.
When the root Cargo.toml has a [workspace] section, look at members to find the
real code. polars, ruff and uv are all organized this way.
[tool.uv.workspace]
members = ["packages/*"]
[tool.uv.sources]
shop-core = { workspace = true }[workspace]
members = ["crates/*"]
resolver = "3"
[workspace.dependencies]
serde = { version = "1", features = ["derive"] }Where the Python analogy breaks
- Modules are not found by file name.
mod payments;in the parent tells Cargo to readpayments.rs. A file nobody declares is ignored, not even compiled. - Dependencies are built into your program. There's no
site-packagesat run time, so people who use your binary don't install anything. serde = "1.0"means "any compatible 1.x", not exactly 1.0. Cargo reads a plain version as^1.0. Inpyproject.tomlyou'd write"serde>=1.0,<2"for the same thing.- Dependencies are compiled from source. The first build of a project can take minutes; after that Cargo only rebuilds what
changed.
pip installmostly downloads ready-made wheels.
Cheat card
| Python | Rust |
|---|---|
uv init shop | cargo new shop |
uv run shop | cargo run |
mypy . | cargo check |
pyproject.toml / uv.lock | Cargo.toml / Cargo.lock |
[project] dependencies = [...] | [dependencies] |
[dependency-groups] dev = [...] | [dev-dependencies] |
requires-python = ">=3.12" | rust-version = "1.85" |
"pydantic[email]~=2.0" | serde = { version = "1", features = ["derive"] } |
uv add requests | cargo add reqwest |
uv lock --upgrade | cargo update |
uv tree | cargo tree |
__main__.py / __init__.py | src/main.rs / src/lib.rs |
import shop.models # file found automatically | mod models; // declare the file, then use |
.venv/ __pycache__/ dist/ | target/ |
PyPI / Read the Docs | crates.io / docs.rs |
โ Building and running a real program Tests, builds and shipping โ