Rust for Pythonistas

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.

Python package
shop/
โ”œโ”€โ”€ pyproject.toml
โ”œโ”€โ”€ uv.lock
โ”œโ”€โ”€ src/shop/
โ”‚   โ”œโ”€โ”€ __main__.py
โ”‚   โ”œโ”€โ”€ __init__.py
โ”‚   โ”œโ”€โ”€ models.py
โ”‚   โ””โ”€โ”€ payments/
โ”‚       โ”œโ”€โ”€ __init__.py
โ”‚       โ””โ”€โ”€ stripe.py
โ”œโ”€โ”€ tests/
โ”‚   โ””โ”€โ”€ test_models.py
โ””โ”€โ”€ .venv/
Rust crate
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.

pyproject.toml
[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"
Cargo.toml
[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 = true

Modules 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).

Python files
# 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)
Rust files
// 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.

Terminal ยท Python
uv add requests
uv add 'pydantic[email]'
uv add --dev pytest
uv lock --upgrade-package requests
uv tree
Terminal ยท Rust
cargo add reqwest
cargo add serde --features derive
cargo add --dev pretty_assertions
cargo update -p reqwest
cargo tree

Workspaces: 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.

pyproject.toml (root)
[tool.uv.workspace]
members = ["packages/*"]

[tool.uv.sources]
shop-core = { workspace = true }
Cargo.toml (root)
[workspace]
members = ["crates/*"]
resolver = "3"

[workspace.dependencies]
serde = { version = "1", features = ["derive"] }

Where the Python analogy breaks

Cheat card

PythonRust
uv init shopcargo new shop
uv run shopcargo run
mypy .cargo check
pyproject.toml / uv.lockCargo.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 requestscargo add reqwest
uv lock --upgradecargo update
uv treecargo tree
__main__.py / __init__.pysrc/main.rs / src/lib.rs
import shop.models # file found automaticallymod models; // declare the file, then use
.venv/ __pycache__/ dist/target/
PyPI / Read the Docscrates.io / docs.rs

โ† Building and running a real program Tests, builds and shipping โ†’