skip to content

A Cargo.toml declares rust-version = "1.80", yet users on Rust 1.80 hit compile errors inside the crate; what does rust-version actually make Cargo enforce?

level: seniorimportance: should knowfreq 35%

answer

  1. a declaration, not a proof
  2. compares against the active rustc
  3. checked for dependencies too
  4. a newer API passes a newer compiler
  5. only an old-toolchain build proves it

basics

~20 s

Cargo enforces rust-version as a floor: it refuses a rustc older than the declared version, for the package and its dependencies. It never checks that the code avoids newer APIs, so the claim can silently go false.

solid answer

~40 s

Cargo compares the active `rustc` with each package's `rust-version` and stops with "rustc X is not supported by the following package" when the compiler is older; `--ignore-rust-version` overrides that. It does not verify the claim: a crate declaring `1.80` that calls `Option::is_none_or` (stable since 1.82) builds cleanly on 1.99, and a 1.80 user then gets a plain compiler error. Clippy's `incompatible_msrv` lint flags many such calls, but the only proof is a CI job on the declared toolchain. Cargo also uses the field when choosing versions (`cargo add` since 1.79, and the MSRV-aware resolver), and rejects a value below the edition's floor: 2024 needs 1.85.

code

toml · 5 lines
toml
[package]
name = "geo-tiles"
version = "0.1.0"
edition = "2021"
rust-version = "1.80"

go deeper

for a junior

Recall that rust-version names the oldest Rust the package supports and that Cargo refuses to build it with an older compiler.

for a middle

Explain the floor check across the package and its dependencies, the bare-version syntax, the edition floor, and what --ignore-rust-version switches off.

for a senior

Diagnose a broken MSRV claim: the field is never verified against the code, so require a CI job on the declared toolchain and keep clippy's incompatible_msrv lint on.

for a principal

Frame the field as a public promise: who it protects downstream, what a bump costs them, and which check backs the number before it ships.

## What the field is `rust-version` in `[package]` declares the package's **minimum supported Rust version** (MSRV): the oldest stable toolchain the maintainers promise works. The value is a bare version such as `"1.80"` or `"1.80.1"`, with no pre-release part; requirement syntax such as `"^1.80"` is rejected with `unexpected version requirement, expected a version like "1.32"`. Cargo has acted on the key since 1.56. The scenario in the question is common: a library declares `1.80`, a contributor uses a newer standard-library method, CI builds only on the latest stable, and the first user on 1.80 gets a compile error from deep inside the crate. To see why nothing stopped it, separate what Cargo enforces from what it merely records. ## What Cargo enforces 1. **A floor on the active compiler.** Before compiling, Cargo compares the running `rustc` with the `rust-version` of every package in the build, dependencies included. If the compiler is older, it stops before compiling anything: ```plaintext error: rustc 1.99.1 is not supported by the following package: [email protected] requires rustc 1.105 ``` The check covers every target of the package: binaries, examples, tests and benches. `--ignore-rust-version` builds anyway. 2. **Consistency with the edition.** A value below the edition's own minimum is a manifest error. With `edition = "2024"` and `rust-version = "1.80"`, Cargo reports that rust-version 1.80 is incompatible with the version (1.85.0) required by the specified edition (2024). The 2021 edition's floor is 1.56. ## What Cargo does not check - It never inspects the code. A crate declaring `1.80` that calls `Option::is_none_or`, stabilised in Rust 1.82, builds without a warning on 1.99. The declaration is a promise the compiler cannot see. - It does not install or select a toolchain. Which `rustc` runs is rustup's business (`rust-toolchain.toml`, overrides), not the manifest's. - It does not make old compilers fail early in a friendly way when the claim is **wrong**: a 1.80 user passes Cargo's check (1.80 is not older than 1.80) and then meets an ordinary compiler error, which is exactly the report in the question. | Tool | What it catches about the MSRV claim | |---|---| | Cargo's floor check | a user's compiler older than the declared version | | `cargo clippy` (`incompatible_msrv`, on by default) | many uses of std items stabilised after `rust-version` | | a CI job on the declared toolchain | everything, because it really compiles on that version | ## Where Cargo uses the field when choosing versions The field also steers dependency selection, which is how the claim can stay true over time: - **`cargo add`** (since Cargo 1.79) picks the newest version of a dependency compatible with your `rust-version` and says so when that is not the latest release. - **The resolver** can prefer dependency versions whose own `rust-version` is less than or equal to yours. Resolver `"3"` (it requires Rust 1.84 and is the default for 2024-edition packages) turns that preference on by default. How it chooses and locks versions is the material on the resolver and `Cargo.lock`. ## Who else reads the field - `cargo metadata` reports it as `rust_version`, so CI scripts and editors can read the declared floor without parsing TOML. - Cargo sets `CARGO_PKG_RUST_VERSION` when compiling the crate, so a build script or the code itself can see the value. - `cargo install` applies the same floor to the package it installs and accepts `--ignore-rust-version` as well. None of these readers verifies the claim either; they all trust the number the manifest states. ## Making the claim true 1. Keep a CI job that runs `cargo build` and `cargo test` on exactly the declared toolchain; nothing else proves the number. 2. Keep Clippy running, so `incompatible_msrv` warns at review time instead of at a user's desk. 3. Raise `rust-version` deliberately when you adopt a newer feature, and treat the bump as a visible change in release notes; the Cargo book treats changing it as a minor incompatibility. How a team picks its MSRV and how often it moves is a release-policy question for the Rust release-train material; the manifest's job is narrower, recording the number and enforcing the floor.

  • Does Cargo check the rust-version of dependencies as well as your own package?
    Yes. Before compiling, Cargo checks every package in the build. A path dependency declaring `rust-version = "1.105"` stops a 1.99 build with "rustc 1.99.1 is not supported by the following package" naming that dependency, until the toolchain is upgraded or `--ignore-rust-version` is passed.
  • Why can a crate not declare rust-version = "1.80" with edition = "2024"?
    The 2024 edition first shipped in Rust 1.85, so no 1.80 compiler could build the crate. Cargo rejects the manifest, saying rust-version 1.80 is incompatible with the version (1.85.0) required by the specified edition.
  • When is --ignore-rust-version the right flag to reach for?
    When you knowingly try a package on a toolchain below its declared floor, for example to test whether an MSRV could be lowered. It switches off Cargo's refusal only; any real incompatibility then surfaces as an ordinary compiler error.

  • Cargo verifies that the code uses no API newer than rust-version.
  • rust-version makes rustup install that toolchain for the project.
  • rust-version takes a requirement such as >=1.80, like a dependency.
  • Only your own package's rust-version is checked, never a dependency's.
  • A user on exactly the declared version is guaranteed a successful build.

Assumes Cargo 1.99.1; Cargo has honoured rust-version since 1.56, cargo add has respected it since 1.79, and the 2024 edition requires 1.85.