crates.io does not have any way to remove a crate from the registry. Instead, cargo yank allows a crate owner to mark a version of a crate as yanked. Such crate versions are not shown on the web page of crates.io and cannot be added to a project, however, if a yanked version of a crate is in a Cargo.lock file, it can still be downloaded and used.
Versions of a crates are marked as yanked in the registry, and the registry API includes ways to yank a crate version and inspect its yanked status. How a yanked crate is used is implemented in Cargo. That means a determined user can get around the restrictions by synthesizing a lock file or by changing the Cargo source.
The goal of yanking (as opposed to removal) is to allow authors to withdraw a crate (for example due to a security issue, without breaking downstream users. The arrangement with building reflects this - it is assumed that downstream binaries will commit a lock file and thus still be buildable even after a version is yanked. However, adding the yanked crate or building a library with such a dependency is not possible.
There is an intrinsic tension with yank: on one hand we want to make it difficult for users to use a yanked crate (in particular if a crate is yanked for a security concern), however, we want to avoid breaking downstream (binary) users if they are relying on a yanked crate.
Problems
downstream libraries who have not committed a Cargo.lock (as recommended) could be broken when a crate version is yanked. It might be that there is no other crate version to use without a breaking change (e.g., #5263).
if every version of a crate is yanked, then users without lock files are screwed (similar to npm's left-pad incident)
binary users might be using a yanked crate with serious security issues without knowing about it
messaging to users about what to do when a crate version is yanked is not very clear
we are relying on manual solutions in extreme situations (that is maintainers hacking the crates.io index directly)
Possible solutions
[ ] - better error messages and documentation,
[ ] - when a user yanks a version, supply a message to be displayed on crates.io and when a user attempts to use it (#2607)
[ ] - warn when a downstream user uses a yanked crate via Cargo.lock. Maybe offer to update the dep to a non-yanked version if possible.
[ ] - allow yanking to be overridden by the user (#5967) even if the yanked version is not in a Cargo.lock. This should be opt-in. We might want to only do this when there is no other version to use without potential breaking changes.
[ ] - when security advisories exist, be able to associate them with yanked versions.
Background
crates.io does not have any way to remove a crate from the registry. Instead,
cargo yankallows a crate owner to mark a version of a crate as yanked. Such crate versions are not shown on the web page of crates.io and cannot be added to a project, however, if a yanked version of a crate is in a Cargo.lock file, it can still be downloaded and used.Versions of a crates are marked as yanked in the registry, and the registry API includes ways to yank a crate version and inspect its yanked status. How a yanked crate is used is implemented in Cargo. That means a determined user can get around the restrictions by synthesizing a lock file or by changing the Cargo source.
The goal of yanking (as opposed to removal) is to allow authors to withdraw a crate (for example due to a security issue, without breaking downstream users. The arrangement with building reflects this - it is assumed that downstream binaries will commit a lock file and thus still be buildable even after a version is yanked. However, adding the yanked crate or building a library with such a dependency is not possible.
There is an intrinsic tension with yank: on one hand we want to make it difficult for users to use a yanked crate (in particular if a crate is yanked for a security concern), however, we want to avoid breaking downstream (binary) users if they are relying on a yanked crate.
Problems
Possible solutions