Cargo, crates and editions: how a Rust project is built and versioned

What it is

A crate is the unit of compilation: a library or a binary. A package is a directory with a Cargo.toml manifest holding [package] (name, version, edition), [dependencies] and optional targets, features and workspace members. Version requirements default to caret semantics, which the Cargo book documents: "1.2.3" means >=1.2.3, <2.0.0, and for 0.x versions the left-most non-zero component must match, so "0.2.3" means >=0.2.3, <0.3.0. The resolver documentation states that Cargo unifies dependency versions when they are SemVer compatible and, when only incompatible versions are available for two requirements, resolves and builds two different versions. Cargo.lock records the exact versions of a successful resolution. The Cargo FAQ states that the lock file gives deterministic builds at different times and on different systems, but does not affect the consumers of your package; only Cargo.toml does that. Editions (2015, 2018, 2021, 2024) group backwards-incompatible language changes; the Edition Guide states that editions are opt-in per crate and that crates in one edition must seamlessly interoperate with those compiled with other editions.

Why it matters

Coming from pip or npm, the surprising parts are that a library's lock file is irrelevant to its users, that two versions of one crate can coexist in a binary (their types are distinct and do not unify), and that the language itself has a versioning switch separate from the compiler version, chosen in the manifest.

How to apply

• cargo new, cargo add serde, cargo build, cargo test, cargo run; cargo update moves the lock file within the allowed ranges; cargo build --release for optimised builds.
• Run cargo fmt and cargo clippy in CI; Clippy's lints flag many newcomer patterns before a reviewer has to.
• For a library, keep the [dependencies] ranges as wide as is honest; for an application, commit Cargo.lock and update deliberately. cargo install selects the latest dependencies unless --locked is passed, as the FAQ notes.
• Migrate editions with cargo fix --edition, one crate at a time; the guide says the automatic migrations are not perfect and that corner cases may need manual changes.
• Use a workspace for several related crates so that they share one lock file and target directory.

Pitfalls

Two versions of one crate compile fine until a type from one is passed to an API expecting the other; the error message names two identically spelled types. cargo update is silent about behavioural changes inside a compatible range. A 0.x dependency treats every minor bump as breaking, so "0.7" will never pick 0.8.