Yanking a Crate Version

"Yanking" a crate version is a way of marking that version as unsuitable for use, without deleting it (and potentially breaking other code that depends on it).

After a crate version has been yanked, Cargo will never choose that version for use when resolving dependencies. However, if the yanked version had previously been used, and is present in a crate's Cargo.lock file, that crate will still be able to download the yanked version (and use it).

In this way, yanking a version prevents its use going forward while not breaking existing code.

Yanking is reversible; a yanked version may be unyanked.

How to Yank a Crate Version via cargo yank

$ cargo yank \
    --registry ${REGISTRY_NAME} \
    --version ${VERSION_TO_YANK} \
    ${NAME_OF_CRATE}

Or using specific (dummy) names:

$ cargo yank \
    --registry my-private-registry \
    --version 0.2.1 \
    rust-deserts

Requires Auth Token

cargo yank command requires an auth token, which can either be provided using a stored token (saved to ~/.cargo/credentials via cargo login), or by using the --token command line option, e.g.:

$ cargo yank \
    --registry my-private-registry \
    --version 0.2.1 \
    --token ${AUTH_TOKEN} \
    rust-deserts

How to Unyank a Crate Version via cargo yank

To unyank a crate version, pass the --undo flag to the command:

$ cargo yank \
    --registry my-private-registry \
    --version 0.2.1 \
    --undo \
    rust-deserts

How to Yank/Unyank using Shipyard.rs

Shipyard.rs also provides a way to yank or unyank a crate version.

To yank a crate version, navigate to the crate version detail page, located at the (pseudo-) url:

https://shipyard.rs/<org-slug>/crates/<crate-name>/<version>

For example, the crate version detail page for the crate rust-deserts version 1.1.0 for the my-private-registry registry would be:

https://shipyard.rs/my-private-registry/crates/rust-deserts/1.1.0

Navigating to the page should be fairly intuitive starting from the Crates page.

The "Yank" section contains a button to yank the respective crate version:

Yank section from crate version detail page

Yank section from crate version detail page

When a crate version is currently yanked, clicking the "Unyank" button will unyank it:

Unyank mode

Unyank button appears when crate version is yanked