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?
answer
- a declaration, not a proof
- compares against the active rustc
- checked for dependencies too
- a newer API passes a newer compiler
- only an old-toolchain build proves it
basics
~20 sCargo 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 sCargo 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[package]
name = "geo-tiles"
version = "0.1.0"
edition = "2021"
rust-version = "1.80"go deeper
Recall that rust-version names the oldest Rust the package supports and that Cargo refuses to build it with an older compiler.
Explain the floor check across the package and its dependencies, the bare-version syntax, the edition floor, and what --ignore-rust-version switches off.
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.
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.