skip to content

In Cargo, what does `cargo yank` do to a broken 2.0.3 release, and which builds keep using it?

level: middleimportance: must knowfreq 38%

answer

  1. hidden, not deleted
  2. existing Cargo.lock wins
  3. new resolution skips it
  4. publish 2.0.4 before yanking

basics

~20 s

cargo yank marks 2.0.3 as yanked in the registry index: new resolution never picks it, but nothing is deleted. Any build whose Cargo.lock already names 2.0.3 keeps downloading and compiling it until that lockfile is updated.

solid answer

~40 s

`cargo yank --version 2.0.3` (or `cargo yank [email protected]`) flips a flag in the registry index; `--undo` flips it back. The `.crate` stays downloadable. Cargo will not choose a yanked version for a project or checkout without a lockfile, so a fresh `cargo generate-lockfile` lands on 2.0.2, and a full `cargo update` moves an existing lockfile off 2.0.3. A project whose `Cargo.lock` already pins 2.0.3 keeps building it, even with `--locked`, which is the point: yanking never breaks existing builds. If every compatible version is yanked, resolution fails, so publish a fixed 2.0.4 first and yank second. A yank is not for leaked secrets: the code is still public, so revoke them.

code

console · 13 lines
console
$ cargo yank --registry internal [email protected]
    Updating `internal` index
        Yank [email protected]
$ cargo build --locked
 Downloading crates ...
  Downloaded quantile-sketch v2.0.3 (registry `internal`)
   Compiling quantile-sketch v2.0.3 (registry `internal`)
   Compiling ingest-svc v0.1.0 (/work/ingest-svc)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.21s
$ cargo update
    Updating `internal` index
     Locking 1 package to highest Rust 1.99.1 compatible version
 Downgrading quantile-sketch v2.0.3 (registry `internal`) -> v2.0.2

go deeper

for a junior

Recall that yank hides a version from new resolution and deletes nothing, and that --undo reverses it.

for a middle

Walk through each case: a pinned lockfile keeps building, a fresh lockfile skips the version, a full cargo update moves off it, and --precise can still select it with a warning.

for a senior

Show incident judgment: publish the compatible fix first, yank second, tell users to update, and revoke secrets instead of relying on a yank.

for a principal

Weigh a yank's disruption against an advisory, since a yank breaks fresh resolution for unaffected users too, and set when a team yanks at all.

## What a yank is A library maintainer has published `quantile-sketch` 2.0.2 and 2.0.3, and 2.0.3 turns out to be broken. Cargo cannot delete it (published versions are permanent), but it can **yank** it: ```console $ cargo yank [email protected] $ cargo yank --version 2.0.3 --undo ``` `cargo yank` asks the registry to mark that version as **yanked** in its index; `--undo` puts it back. Both need an owner's token, and both take `--registry NAME` for a private registry. The Cargo manual's one-line summary of the command is "Remove a pushed crate from the index", but its description is more precise: the command **does not delete any data**, and the crate is still downloadable from the registry. ## Who still gets 2.0.3 The rule is that **no new dependency can be created against a yanked version, while existing ones keep working**: | Situation | What Cargo does | |---|---| | project with a `Cargo.lock` that pins 2.0.3 | builds 2.0.3, downloading it if needed, even under `--locked` | | project with no `Cargo.lock`, requirement `"2.0"` | resolves to 2.0.2, the newest compatible version that is not yanked | | full `cargo update` on a lockfile that pins 2.0.3 | re-resolves and moves off it (to 2.0.2, a downgrade, if nothing newer exists) | | `cargo update -p quantile-sketch --precise 2.0.3` | selects it anyway, with a warning that the author yanked it | | every version matching the requirement yanked | resolution fails with "failed to select a version for the requirement" | The first row is the one people get wrong. Yanking is designed so that **every package with a `Cargo.lock` keeps building**, which is why the downloads keep working: a CI job that cached nothing still fetches the yanked `.crate` by its locked version. ## The order of operations The Cargo manual's advice for a broken release is to **publish a fixed, SemVer-compatible version first, then yank**: 1. Fix the bug and publish 2.0.4. 2. Yank 2.0.3, so new lockfiles cannot select it. 3. Tell users to run `cargo update -p quantile-sketch`, which moves an existing lockfile from 2.0.3 to 2.0.4. Yanking first is harmless when an older compatible version (2.0.2 here) exists, but if 2.0.3 were the only version matching some downstream requirement, those downstream crates would stop resolving until a replacement exists. ## When to yank, and when not to The manual reserves yanking for exceptional cases: - an **accidental publish**; - an **unintentional SemVer break**, where a minor release broke callers; - a version so broken it is unusable. It also lists what a yank cannot do: - **Leaked credentials**: the `.crate` stays downloadable and existing lockfiles keep fetching it, so a yank cannot stop the secret from spreading. Revoke it immediately. - **Security vulnerabilities**: the manual points to a security advisory (RustSec) as the less disruptive way to warn users, since a yank also disrupts people who are not affected. - **Copyright, licensing or personal data problems**: a yank may not be enough; contact the registry's maintainers. ## Seeing it happen When a service's lockfile pins the yanked version, nothing changes until someone updates: ```plaintext $ cargo update Updating `internal` index Locking 1 package to highest Rust 1.99.1 compatible version Downgrading quantile-sketch v2.0.3 (registry `internal`) -> v2.0.2 ``` That downgrade is Cargo honouring the yank during resolution. A team that wants to stay on 2.0.3 deliberately can pin it with `--precise`, and Cargo warns that the version was yanked. A team that expected the yank to protect it automatically learns that only a lockfile update does. ## The command itself A few details matter when you run it under pressure: - The version is given either as `cargo yank [email protected]` or as `cargo yank --version 2.0.3 quantile-sketch`; with no crate name, Cargo uses the package in the current directory. - It needs an owner's token, from `cargo login` or the registry's token environment variable, and `--registry NAME` for a private registry. - `--undo` reverses it at any time, which makes a yank the cheap, reversible part of an incident response, and the patch release the durable part. Remember too that a yank is visible only to new resolution. Projects that need the fix still have to run `cargo update -p quantile-sketch` (or a full update) and commit the new `Cargo.lock`; nothing in Cargo pushes the change to them.

  • What happens to a project with requirement "2.0" and no lockfile if both 2.0.2 and 2.0.3 are yanked?
    Resolution fails. Cargo prints "failed to select a version for the requirement `quantile-sketch = \"^2.0\"`" and lists each candidate as yanked. That is why the manual says to publish a compatible fix before yanking the last good version a requirement can match.
  • Can a team keep using a yanked version on purpose?
    Yes. A lockfile that already pins it keeps working, and `cargo update -p quantile-sketch --precise 2.0.3` can select it explicitly; Cargo prints a warning that the author yanked it and suggests a compatible non-yanked version.
  • Why is a yank the wrong response to an API key committed in 2.0.3?
    The `.crate` is still downloadable and every existing lockfile that pins 2.0.3 keeps fetching it, so the key stays public. The manual says to revoke leaked credentials immediately; yanking only changes what new resolution picks.

  • cargo yank deletes the .crate from the registry
  • Builds with a Cargo.lock pinning the yanked version start failing
  • --locked builds refuse a yanked version
  • Yanking is the way to remove a leaked secret
  • Yanking the only compatible version is harmless to dependents