skip to content

In a Cargo project, what does Cargo.lock record that a requirement like `serde_json = "1.0"` in Cargo.toml does not, and should you commit it?

level: juniorimportance: must knowfreq 72%

answer

  1. range in one file, pick in other
  2. exact version, source, checksum
  3. lock wins until cargo update
  4. dependents ignore your lockfile
  5. cargo new tracks it since 1.74

basics

~20 s

Cargo.toml states a range ("1.0" means >=1.0.0, <2.0.0); Cargo.lock records the exact version Cargo resolved for every package, with source and checksum for registry crates, so later builds reuse it. Cargo's guidance: when in doubt, commit it.

solid answer

~40 s

`serde_json = "1.0"` is a caret requirement: any 1.x release from 1.0.0 up is acceptable. The first build resolves the whole graph and writes `Cargo.lock`, which lists every package with its exact `version`, and for registry crates its `source` and `checksum`. On later builds Cargo gives locked versions the highest priority, so a newer 1.0.x does not slip in until you run `cargo update` or change the requirement. The Cargo book says to check `Cargo.lock` in when in doubt, and since Cargo 1.74 `cargo new` no longer ignores it for libraries. The caveat: a library's lockfile only governs its own CI and checkouts; projects that depend on it resolve from their own `Cargo.lock`.

code

toml · 17 lines
toml
# Cargo.toml
[dependencies]
serde_json = "1.0"

# Cargo.lock (excerpt), written by the first resolve
[[package]]
name = "serde_json"
version = "1.0.154"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "e7e9cc8b1b85264074fbcc02a88680c4096b1e47df8f739dceb03bf482f04bd6"
dependencies = [
 "itoa",
 "memchr",
 "serde",
 "serde_core",
 "zmij",
]

go deeper

for a junior

Recall the split: Cargo.toml holds ranges you write, Cargo.lock holds the exact versions Cargo chose. Know that the lock is reused until cargo update runs.

for a middle

Explain what an entry holds (version, source, checksum, dependency names), when Cargo rewrites the lock on its own, and why the current guidance commits it for libraries too.

for a senior

Show you know the lockfile's reach ends at your repository: dependents resolve their own graph, so library CI also needs a job that tests the newest matching versions.

for a principal

Frame the lockfile as a team decision: what CI enforces with --locked, how often the lock moves, and how a library proves its declared ranges are honest.

## Two files, two jobs A Cargo package has a **manifest**, `Cargo.toml`, which you write, and a **lockfile**, `Cargo.lock`, which Cargo writes. They answer different questions: - `Cargo.toml` says which versions you are *willing* to use. `serde_json = "1.0"` is a **caret requirement**, Cargo's default operator, meaning `>=1.0.0, <2.0.0`. - `Cargo.lock` says which versions were *actually chosen*: one exact version for every package in the resolved graph, including dependencies of dependencies that never appear in your manifest. The book's own summary: the manifest describes dependencies "in a broad sense" and is written by you; the lockfile "contains exact information", is maintained by Cargo and should not be edited by hand. The file even opens with the comment `# It is not intended for manual editing.` ## What an entry holds Each `[[package]]` entry carries: 1. `name` and exact `version` (for example `1.0.154`). 2. `source`: where it came from, such as `registry+https://github.com/rust-lang/crates.io-index` or a git URL with the commit hash. 3. `checksum`: a SHA-256 of the downloaded `.crate`, so Cargo refuses a download that no longer matches the locked checksum. 4. `dependencies`: the names of the packages this one uses in the graph. Path dependencies (crates inside your repository) get an entry with name, version and dependencies but no `source` or `checksum`, since there is nothing to download. The lockfile does **not** record features or the dependents' requirement strings; features are worked out again on every build. ## How Cargo uses it The resolver gives **the highest priority to versions already in `Cargo.lock`**. If `serde_json` was locked at 1.0.154 and 1.0.160 is published tomorrow, every build keeps using 1.0.154. The lock moves when, for example: - you run `cargo update` (everything) or `cargo update -p serde_json` (one package), - you edit a requirement so the locked version no longer matches it (raising it to `"1.0.160"` forces a re-pick), or - you add a dependency, which is locked to its newest matching version. That is what makes builds **deterministic**: the same commit builds the same versions on every laptop and CI runner, which is what makes bisecting a regression and trusting a red CI run possible. A CI job can make the guarantee strict with `--locked`, which errors instead of rewriting a lockfile that no longer matches the manifest. ## Commit it? Current guidance Older advice was "commit for binaries, ignore for libraries". The current Cargo book says: **when in doubt, check `Cargo.lock` into version control**, and pair it with a CI job that also tests the newest dependency versions. Cargo 1.74 changed `cargo new` and `cargo init` so they no longer list `Cargo.lock` in the generated ignore file for libraries, and the FAQ now describes tracking it as the default. | Package kind | Commit `Cargo.lock`? | Who reads it | |---|---|---| | Binary, service, CLI | Yes | Every build of that repository; `cargo install --locked` | | Library | Yes, when in doubt | Only the library's own CI and contributors | The limit to remember: **a lockfile never affects your dependents.** When another project depends on your library, its resolver reads your `Cargo.toml` requirements and writes its own `Cargo.lock`; yours is ignored. Since Cargo 1.84 `cargo publish` always includes `Cargo.lock` in the uploaded package, but it is used only by `cargo install --locked` on a package with binaries. That is why the book warns that the lockfile can give a false sense of security for libraries: users will see newer versions than your CI did unless you also test them. ## Common slips - Hand-editing `Cargo.lock` to pin a version. Use `cargo update -p NAME --precise VERSION`, which validates the choice against every requirement. - Assuming `cargo build` silently upgrades within the caret range. It does not while a lock exists. - Deleting the lockfile to "fix" a build, which upgrades the whole graph at once and loses the record of what worked. - Treating `Cargo.lock` as a dependent-facing pin. To force consumers off a bad version, a library has to change its `Cargo.toml` requirement.

  • A library commits Cargo.lock. Why can its users still hit a dependency version its CI never built?
    Dependents resolve from their own `Cargo.lock` and read only the library's `Cargo.toml` requirements, so they pick the newest versions matching those ranges. The library's lockfile pins only its own CI. The Cargo book therefore pairs a committed lockfile with a CI job that runs `cargo update` and then builds and tests, so the latest versions inside the ranges get exercised.
  • When does Cargo rewrite an existing Cargo.lock without you running cargo update?
    When the manifest no longer matches it: a requirement edited so the locked version falls outside it, a dependency added or removed, or a `[patch]` entry changed. Cargo re-resolves just enough and writes the result. Passing `--locked` turns that silent rewrite into an error, which is why CI uses it.

Cargo.toml is a shopping list that says 'milk, any brand under two euros'; Cargo.lock is the receipt naming the exact carton bought, so the next trip buys the same one until you decide to shop around.

  • cargo build upgrades to the newest 1.x on every run
  • Libraries must never commit Cargo.lock
  • My library's Cargo.lock pins versions for everyone who depends on it
  • Editing Cargo.lock by hand is the normal way to pin a version
  • Cargo.lock records which features each crate was built with

Assumes Cargo 1.99; cargo new stopped ignoring Cargo.lock for libraries in 1.74, and cargo publish always includes it since 1.84.