CARGO-YANK(1)

👑 CARGO-YANK(1) — Remove a pushed crate from the index 💅

okay bestie, welcome to the cargo-yank page, straight out of the General Commands Manual. this one's short but it's important, so put your phone down for like four minutes. 🫶

---

✨ NAME ✨

cargo-yank — Remove a pushed crate from the index 🗑️

---

🎀 SYNOPSIS 🎀

cargo yank [options] crate@version
cargo yank [options] --version version [crate]

two whole shapes, pick your fighter. 🥊

---

🌸 DESCRIPTION 🌸

the yank command takes a version of a crate you already published and removes it from the server's index. that's it. that's the whole job.

no cap: this command does not delete any data. the crate is still downloadable via the registry's download link. yanking is a vibe, not a shredder. 😭

so what actually changes? Cargo will not use a yanked version for any new project or checkout that doesn't already have a pre-existing lockfile. and if there are no longer any compatible versions left for your crate, Cargo will straight up generate an error. 💀

you gotta be authenticated for this — either with the --token option or by using cargo-login(1).

and if you don't specify the crate name? it just uses the package name from the current directory. convenient. iconic. 🎀

---

🧠 How yank works

picture this: the foo crate published version 1.5.0, and another crate, bar, declared a dependency on version foo = "1.5". now foo drops a new version — 2.0.0 — but it's not semver compatible, and oops, they found a critical issue with 1.5.0. 🙈

if 1.5.0 gets yanked, then no new project or checkout without an existing lockfile will be able to use crate bar, because bar relies on 1.5. and that's a bad time for everybody.

so in this case, the maintainers of foo should first publish a semver compatible version like 1.5.1, and then yank 1.5.0. that way bar and every project that depends on bar keeps working. the way that order of operations matters… 🔥

another example, bestie. consider a crate bar with published versions 1.5.0, 1.5.1, 1.5.2, 2.0.0 and 3.0.0. here's what Cargo could use in the absence of a lockfile, for different SemVer requirements, after a given release gets yanked:

• if the yanked version is 1.5.0
  • with bar = "1.5.0" → Use either 1.5.1 or 1.5.2
  • with bar = "=1.5.0" → Return Error 💀
  • with bar = "2.0.0" → Use 2.0.0
• if the yanked version is 1.5.1
  • with bar = "1.5.0" → Use either 1.5.0 or 1.5.2
  • with bar = "=1.5.0" → Use 1.5.0
  • with bar = "2.0.0" → Use 2.0.0
• if the yanked version is 2.0.0
  • with bar = "1.5.0" → Use either 1.5.0, 1.5.1 or 1.5.2
  • with bar = "=1.5.0" → Use 1.5.0
  • with bar = "2.0.0" → Return Error 💀

(yes, the columns are Yanked Version / SemVer requirement on one side and the three bar requirement flavours on the other. that's the whole grid. 💖)

---

🦋 When to yank

crates should only be yanked in exceptional circumstances. like:

• an accidental publish 🙈
• unintentional SemVer breakages
• a significantly broken and unusable crate

if it's a security vulnerability situation? RustSec <https://rustsec.org/> is typically a less disruptive mechanism to inform users and encourage them to upgrade. it also avoids the possibility of significant downstream disruption irrespective of susceptibility to the vulnerability in question. so, like, consider it first. ✨

a common workflow is to yank a crate having already published a semver compatible version — this reduces the probability of preventing dependent crates from compiling. publish first, yank second. periodt. 💅

now, if you're dealing with copyright, licensing, or personal data issues on a published crate, simply yanking it may not suffice. in those cases you gotta contact the maintainers of the registry you used. for crates.io, go read their policies <https://crates.io/policies> and hit them up at <help@crates.io>. 📧

and if credentials have been leaked? the recommended course of action is to revoke them immediately. once a crate has been published, it is impossible to determine if the leaked credentials have been copied. yanking only prevents Cargo from selecting this version when resolving dependencies by default. existing lock files or direct downloads are not affected, so yanking cannot stop further spreading of the leaked credentials. big yikes, be careful out there. 🚨

---

💅 OPTIONS 💅

🎯 Yank Options

• --vers version, --version version — the version to yank or un-yank. yes, two spellings, same energy. ✨
• --undo — undo a yank, putting a version back into the index. the uno reverse card. 🔄
• --token token — API token to use when authenticating. this overrides the token stored in the credentials file (which is created by cargo-login(1)).
  • Cargo config <https://doc.rust-lang.org/cargo/reference/config.html> environment variables can be used to override the tokens stored in the credentials file. the token for crates.io may be specified with the CARGO_REGISTRY_TOKEN environment variable. tokens for other registries may be specified with environment variables of the form CARGO_REGISTRIES_NAME_TOKEN where NAME is the name of the registry in all capital letters. 👑
• --index index — the URL of the registry index to use.
• --registry registry — name of the registry to use. registry names are defined in Cargo config files <https://doc.rust-lang.org/cargo/reference/config.html>. if not specified, the default registry is used, which is defined by the registry.default config key — and that defaults to crates-io. 🎀

🌈 Display Options

• -v, --verbose — use verbose output. may be specified twice for "very verbose" output, which includes extra output such as dependency warnings and build script output. may also be specified with the term.verbose config value <https://doc.rust-lang.org/cargo/reference/config.html>. 🗣️
• -q, --quiet — do not print cargo log messages. may also be specified with the term.quiet config value <https://doc.rust-lang.org/cargo/reference/config.html>. 🤫
• --color when — control when colored output is used. valid values:
  • auto (default): automatically detect if color support is available on the terminal. 🔍
  • always: always display colors. 🌈
  • never: never display colors. 🚫
  • may also be specified with the term.color config value <https://doc.rust-lang.org/cargo/reference/config.html>.

🫶 Common Options

• +toolchain — if Cargo has been installed with rustup, and the first argument to cargo begins with +, it will be interpreted as a rustup toolchain name (such as +stable or +nightly). see the rustup documentation <https://rust-lang.github.io/rustup/overrides.html> for more information about how toolchain overrides work. 🛠️
• --config KEY=VALUE or PATH — overrides a Cargo configuration value. the argument should be in TOML syntax of KEY=VALUE, or provided as a path to an extra configuration file. this flag may be specified multiple times. see the command-line overrides section <https://doc.rust-lang.org/cargo/reference/config.html#command-line-overrides> for more information.
• -C PATH — changes the current working directory before executing any specified operations. this affects things like where cargo looks by default for the project manifest (Cargo.toml), as well as the directories searched for discovering .cargo/config.toml, for example. this option must appear before the command name, for example cargo -C path/to/my-project build.
  • > ⚠️ this option is only available on the nightly channel <https://doc.rust-lang.org/book/appendix-07-nightly-rust.html> and requires the -Z unstable-options flag to enable (see #10098 <https://github.com/rust-lang/cargo/issues/10098>). not for the faint of heart, bestie.
• -h, --help — prints help information. 🆘
• -Z flag — unstable (nightly-only) flags to Cargo. run cargo -Z help for details. 🧪

---

🌍 ENVIRONMENT 🌍

see the reference <https://doc.rust-lang.org/cargo/reference/environment-variables.html> for details on environment variables that Cargo reads. that's the whole section, she's brief but she's thorough. 💜

---

⭐ EXIT STATUS ⭐

• 0: Cargo succeeded. 🎉
• 101: Cargo failed to complete. 😭

---

🍓 EXAMPLES 🍓

1. Yank a crate from the index:

cargo yank foo@1.0.7

---

🔗 SEE ALSO 🔗

cargo(1), cargo-login(1), cargo-publish(1)

---

and that's the whole page, bestie!! 🎀 this one came straight out of the General Commands Manual, filed under CARGO-YANK(1) — go forth and yank responsibly. mwah. 💖✨🦋