skip to content

Dependency Specifications

A dependency line chooses a version requirement and a source, and caret is the default. Interviewers ask what "1.2" allows and how dev, build and target-specific dependencies differ.

on this pageshow

explore

questions

5

In a Cargo.toml, which versions may Cargo select for `serde = "1.0.200"`, and why does that line count as a caret requirement?

level: juniorimportance: must knowfreq 74%

answer

  1. no operator still means a range
  2. left-most non-zero component stays fixed
  3. the written version is a floor
  4. pre-releases must be asked for

basics

~10 s

A bare version in Cargo is a caret requirement, so serde = "1.0.200" means >=1.0.200, <2.0.0. Cargo may pick any release in that range, normally the newest, and records its pick in Cargo.lock.

solid answer

~40 s

In Cargo a version written with no operator is a **default requirement**, which the Cargo book defines as exactly the caret requirement: `"1.0.200"` and `"^1.0.200"` mean the same thing, `>=1.0.200, <2.0.0`. Cargo treats releases as compatible when their left-most non-zero component matches, so any later 1.x release qualifies and 2.0.0 does not. The number you wrote is a **minimum**, not a pin: Cargo never selects 1.0.150 for this line, and on a fresh resolve it takes the newest matching release (1.0.229 in the run shown). Pre-release versions such as `1.1.0-rc.1` are skipped unless the requirement names a pre-release itself. Which exact version you get is then fixed in `Cargo.lock` until you update it.

code

toml · 8 lines
toml
[package]
name = "ledger-api"
version = "0.1.0"
edition = "2024"

[dependencies]
serde = "1.0.200"
libc = "0.2"

go deeper

for a junior

Recall that a bare version is a range: "1.0.200" means at least 1.0.200 and below 2.0.0, and that the caret is implied.

for a middle

Explain compatibility as the left-most non-zero component, why the written number is a floor rather than a pin, and that pre-releases are excluded unless named.

for a senior

Show you keep floors honest: a library's requirement must name the oldest release whose API it uses, because downstream lockfiles may hold older compatible releases.

for a principal

Frame requirements as the contract a crate offers its dependents, with the lockfile, not the requirement, carrying an application's reproducibility.

## A dependency line is a range, not a version In a `Cargo.toml`, the string on the right of a dependency is a **version requirement**: a rule describing which published versions Cargo may use. The Cargo book's own example is `time = "0.1.12"`, which it describes as the range `>=0.1.12, <0.2.0`. The same idea applies to a service that writes: ```toml [dependencies] serde = "1.0.200" ``` That line does not say "use 1.0.200". It says "use some serde release that is at least 1.0.200 and still compatible with it". ## The default operator is caret Cargo accepts several operators (`^`, `~`, `*`, `=`, `>=`, `<` and combinations), and a requirement with **no operator** is the **default requirement**. The Cargo book states that caret requirements are the default strategy and that `log = "^1.2.3"` is exactly equivalent to `log = "1.2.3"`; it even recommends leaving the caret off. Cargo's own messages show the equivalence: when a bare `"0.2"` fails to match, Cargo reports the requirement as `"^0.2"`. The caret rule is defined by **compatibility**: two versions are compatible when their **left-most non-zero component** (major, minor or patch) is the same. For any 1.x requirement that component is the major version, so: | Written | Meaning | |---|---| | `"1.0.200"` | `>=1.0.200, <2.0.0` | | `"1.2"` | `>=1.2.0, <2.0.0` | | `"1"` | `>=1.0.0, <2.0.0` | Requirements below 1.0 are narrower, because the left-most non-zero component moves to the minor or patch position; that rule is worth learning separately. ## The written number is a floor The most common misreading is that `"1.0.200"` pins 1.0.200. It does the opposite of pinning: - **Lower bound**: Cargo never selects anything older than 1.0.200 for this line, even if an older release is already downloaded. - **Upper bound**: anything up to, but not including, 2.0.0 is allowed. - **Choice**: on a fresh resolve Cargo normally takes the newest matching release; in the run below, with 1.0.229 available, that is what it picked. Because the floor is a promise to Cargo, it should be the oldest release whose API your code actually needs. `cargo add` writes the newest suitable release it finds as the requirement (for example `serde_json = "1.0.154"`), which is safe but may raise the floor higher than necessary. The opposite mistake, a floor that is too low because the code calls an API added in a later release, only shows up for someone whose lockfile holds an older release. Cargo has an **unstable** `-Z minimal-versions` flag that resolves every requirement to its lowest allowed version, intended for checking this in CI; it is not available on the stable channel, and the Cargo book itself does not recommend it in its current form because not all crates in the wider graph declare accurate floors. ## Pre-releases and build metadata Two details sit inside the same rule: 1. **Pre-releases are excluded** unless the requirement names one. With `geo = "1.2"` and only `1.5.0-rc.1` published, Cargo fails to select a version, even though 1.5.0-rc.1 lies numerically inside the range. Writing `"1.5.0-rc.1"`, or an earlier pre-release of the same version such as `"1.5.0-beta"`, opts in, because Cargo moves forward to newer pre-releases of that same version. 2. **Build metadata** such as `+21AF26D3` is ignored and should not appear in a requirement. ## What the requirement does not decide A requirement only describes the acceptable range. Which version is actually built is recorded in `Cargo.lock`, and that record changes when someone runs `cargo update`; how Cargo chooses within the range and how the lockfile behaves belongs to the resolver and `Cargo.lock` lesson. Features of the dependency (`features = [...]`, `default-features = false`) are also separate from the version requirement and are covered with Cargo's features. ## Seeing it on a real project A quick way to confirm what a requirement resolved to is `cargo tree --depth 1`, which lists each direct dependency with the version Cargo locked, or the `Cargo.lock` entry itself. In the example below, the first `cargo build` recorded serde 1.0.229 for `serde = "1.0.200"` and the newest 0.2.x release for `libc = "0.2"`. Reading a requirement correctly is the basis for every other version question: once you know the default is caret, tilde, wildcards and exact pins become deliberate departures from it rather than the norm.

  • Can `cargo update` move `serde = "1.0.200"` down to 1.0.150 if a newer release turns out to be broken?
    No. The written version is the requirement's lower bound, so nothing below 1.0.200 satisfies it. To go back you would have to lower the requirement in `Cargo.toml` itself, for example to `"1.0.150"`, and then select the older release in `Cargo.lock`, which is the resolver's job.
  • If geo publishes `2.0.0-rc.1`, will a requirement of `geo = "1.0"` or `geo = "2"` pick it up?
    Neither does by default. Cargo excludes pre-release versions from a requirement unless the requirement itself names a pre-release, so `"2"` waits for 2.0.0 and `"1.0"` never reaches 2.x at all. Writing `geo = "2.0.0-rc.1"` opts in, and Cargo will later move to newer pre-releases of 2.0.0 and to 2.0.0 itself.
  • Why can a library that declares `serde = "1.0"` break a downstream build even though its own CI is green?
    Its CI resolves to the newest 1.x release, so code calling an API added in, say, 1.0.180 compiles there. A downstream project whose `Cargo.lock` already holds an older 1.0.x release still satisfies `"1.0"`, so Cargo keeps it and the library fails to compile. The fix is to raise the floor to the release that introduced the API.

  • serde = "1.0.200" pins the build to exactly version 1.0.200.
  • Without a caret Cargo treats the version as exact, as if written with =.
  • The line allows only 1.0.x patch releases and never 1.1.0.
  • Cargo may fall back below 1.0.200 if an older release is already cached.
  • A caret range lets Cargo move to 2.0.0 once that release is published.
  • Any pre-release inside the numeric range is picked up automatically.
open as a page

In a Cargo.toml, how do `[dev-dependencies]`, `[build-dependencies]` and `[target.'cfg(...)'.dependencies]` differ from `[dependencies]` in which code may use them?

level: middleimportance: should knowfreq 56%

basics

~10 s

Normal dependencies serve the package and its dependents; dev-dependencies only tests, examples and benchmarks; build-dependencies only build.rs; and a target cfg table adds dependencies only when compiling for a matching platform.

open as a page

In a Cargo.toml, what does the caret rule allow for 0.x and 0.0.x versions, and what do tilde, wildcard and `=` requirements change?

level: middleimportance: should knowfreq 60%

basics

~10 s

Cargo fixes the left-most non-zero component, so "0.3.1" means >=0.3.1, <0.4.0 and "0.0.4" means >=0.0.4, <0.0.5. Tilde and "1.2.*" fix the minor version, and "=1.2.3" accepts that one release.

open as a page

A Rust crate's Cargo.toml has a git dependency pinned by `rev` and a path dependency on a sibling crate; how does Cargo source each, and what must change before `cargo publish`?

level: seniorimportance: should knowfreq 34%

basics

~20 s

Cargo fetches the git repository at the given rev and builds the path crate from that folder. Publishing needs a version on every non-dev dependency: git and path keys are stripped and registry versions used, so each must exist in the registry.

open as a page

In a Cargo.toml, what does `json = { package = "serde_json", version = "1" }` change, and when is renaming a dependency worth doing?

level: middleimportance: nice to knowfreq 24%

basics

~20 s

The package key names the real crate and the table key becomes the name code uses: this line depends on serde_json but code writes json::from_str. Renaming lets one package use two versions or two same-named crates side by side.

open as a page