skip to content

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%

answer

  1. compatibility moves right below 1.0
  2. 0.0.x accepts one patch line
  3. tilde fixes the minor
  4. bare * is refused by crates.io

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.

solid answer

~40 s

Cargo's default (caret) rule treats versions as compatible when their **left-most non-zero component** matches, which is stricter than plain SemVer below 1.0: `"0.3.1"` means `>=0.3.1, <0.4.0`, and `"0.0.4"` means `>=0.0.4, <0.0.5`, effectively one release. **Tilde** fixes the minor version when you give one (`~1.2.3` is `>=1.2.3, <1.3.0`) but `~1` still allows `<2.0.0`. A **wildcard** allows anything in its position (`1.2.*` equals `~1.2`), and crates.io refuses a bare `*`. **Comparison** requirements spell bounds out (`>=1.2, <1.5`), and `=1.2.3` pins one release. The Cargo book advises against upper bounds tighter than the next incompatible version, because another package needing a newer release then leaves no version that satisfies both.

code

toml · 3 lines
toml
# crates/wire-format/Cargo.toml declares version = "0.3.1"
[dependencies]
wire-format = { path = "crates/wire-format", version = "0.2" }

go deeper

for a junior

Recall the table: 0.3.1 stops before 0.4.0, 0.0.4 stops before 0.0.5, and = pins one release.

for a middle

Explain the left-most non-zero rule, why tilde with only a major is as wide as caret, and how comma-separated requirements combine.

for a senior

Show why a library's tight upper bound can make a dependent's graph unresolvable, and when the Cargo book says a pin is still justified.

for a principal

Treat a 0.x minor bump in a widely used crate as a breaking release and plan dependents' upgrades the way you would plan a major.

## Compatibility is decided by the left-most non-zero component Cargo's default requirement, the **caret** rule, lets Cargo use any release that is **compatible** with the one written. The Cargo book defines compatible precisely: two versions are compatible when their **left-most non-zero** major, minor or patch component is the same. It also notes that this differs from SemVer itself, which treats all pre-1.0 versions as incompatible with each other. The rule produces three different behaviours depending on where the first non-zero digit sits: | Written | Meaning | Fixed component | |---|---|---| | `"1.2.3"` | `>=1.2.3, <2.0.0` | major | | `"0.3.1"` | `>=0.3.1, <0.4.0` | minor | | `"0.3"` | `>=0.3.0, <0.4.0` | minor | | `"0.0.4"` | `>=0.0.4, <0.0.5` | patch | | `"0.0"` | `>=0.0.0, <0.1.0` | minor | | `"0"` | `>=0.0.0, <1.0.0` | major | So for a crate still on 0.x, a **minor** bump (0.3 to 0.4) is treated as breaking, and a `0.0.x` crate gets no automatic updates at all. A 0.x crate can therefore signal a breaking change with a minor bump and a fix with a patch bump, and dependents receive only the fixes. ## Working out the bounds by hand A reliable way to read any default requirement is a three-step procedure: 1. Pad the written version with zeros to find the **lower bound**: `"0.3"` starts at 0.3.0, `"1"` at 1.0.0. 2. Find the **left-most non-zero** component among the components actually written; if every written component is zero, take the last one written (`"0.0"` uses the minor, `"0"` the major). 3. Increment that component and zero everything to its right to get the **exclusive upper bound**: 0.3.1 becomes `<0.4.0`, 0.0.4 becomes `<0.0.5`. The table above is this procedure applied row by row, and Cargo prints the result back as a caret requirement when one fails to match. ## Tilde requirements A **tilde** requirement is narrower than caret when it names a minor version: - `~1.2.3` means `>=1.2.3, <1.3.0` - `~1.2` means `>=1.2.0, <1.3.0` - `~1` means `>=1.0.0, <2.0.0`, because with only a major version tilde allows minor and patch changes The last row surprises people: `~1` is as wide as `"1"`. ## Wildcard, comparison and exact requirements 1. **Wildcards** allow any version in the wildcard's position: `1.*` is `>=1.0.0, <2.0.0` and `1.2.*` is `>=1.2.0, <1.3.0`. A bare `*` means `>=0.0.0`, and the Cargo book notes that crates.io does not allow bare `*` versions. 2. **Comparison** requirements write the bounds directly: `>= 1.2.0`, `> 1`, `< 2`. Several can be combined with a comma, as in `">=1.2, <1.5"`, and **all** must hold, so non-overlapping parts such as `<1.2, ^1.2.2` match nothing. 3. **Exact** requirements use `=`: `"=1.2.3"` accepts only 1.2.3. ## Why the Cargo book discourages tight upper bounds The Cargo book's recommendation is to use the default operator when in doubt, and to avoid constraining the upper bound to anything less than the next SemVer-incompatible version, naming `">=2.0, <2.4"`, `"2.0.*"` and `~2.0` as examples. The reason is mechanical: Cargo unifies SemVer-compatible requirements onto one version and errors when conflicting requirements make that impossible (the resolver's subject), so if your library says `~2.0` and another package in the graph needs 2.4, no single 2.x version satisfies both and resolution fails. Controlling the exact version in `Cargo.lock` is usually the better tool. The book lists cases where a tight bound is still reasonable: - a package no one else depends on, such as one that only has a `[[bin]]`; - a pre-release dependency, where `"=1.2.3-alpha.3"` avoids breaking changes between pre-releases; - a library that re-exports a procedural macro whose generated code calls back into the library, where `=1.2.3` keeps the two in step. The book also mentions the opposite, deliberately **wide** range: a library whose public API uses only a simple type that has not changed across several incompatible majors may write something like `">=0.4, <2"` so users can choose the version. It warns that users who also depend on that crate may then have to pick a version manually with `cargo update`, so this is a rare tool rather than a habit. ## Seeing the rule fail The quickest way to watch these rules is a path dependency that also carries a `version` key, because Cargo checks the local crate's version against the requirement. With a sibling crate at 0.3.1, `version = "0.3"`, `"~0.3.0"`, `"0.*"`, `"=0.3.1"` and `">=0.2, <0.4"` all succeed, while `"0.2"` and `"0.3.2"` fail with the error shown below. Note that Cargo prints the bare `"0.2"` as `"^0.2"`, confirming that the default operator is caret.

  • A crate at 0.0.7 publishes 0.0.8 with a bug fix. Does a dependent with `"0.0.7"` receive it after `cargo update`?
    No. For a 0.0.x version the patch number is the left-most non-zero component, so `"0.0.7"` means `>=0.0.7, <0.0.8` and 0.0.8 counts as incompatible. The dependent has to edit the requirement to `"0.0.8"` to take the fix.
  • Why might a binary-only service reasonably write `=` requirements while a library should not?
    The Cargo book's warning about tight bounds concerns other packages in the graph needing newer releases. A package that only has a `[[bin]]` has no dependents, so an exact pin cannot conflict with anyone else's requirement. A library's pin is imposed on every consumer and can make their graph unresolvable, so libraries keep caret ranges and leave exact selection to each application's `Cargo.lock`.

  • "0.3.1" allows any 0.x release up to 1.0.0, like 1.x does.
  • ~1 allows only patch releases of 1.0.
  • A 0.0.x requirement still accepts newer patch releases automatically.
  • Cargo follows plain SemVer exactly, with no special rule below 1.0.
  • Pinning every dependency with = in a library is the safe default.
  • Requirements separated by commas match if any one of them holds.