cargo-yank

Yank the specified version of a crate

$ cargo yank [crate]@[version]

$ cargo yank --undo [crate]@[version]

$ cargo yank --registry [name] [crate]@[version]

cargo yank [OPTIONS] <CRATE_NAME>@<VERSION_NUMBER>...

@
    Specifies the name of the crate and its version to yank or un-yank. Multiple CRATE_NAME@VERSION_NUMBER pairs can be provided.

--crate <CRATE_NAME>
    An alternative way to specify the crate name.

--version <VERSION_NUMBER>
    An alternative way to specify the crate version. Must be used with --crate.

--yank
    Explicitly marks the specified crate version(s) as yanked. This is the default action if neither --yank nor --undo is provided.

--undo
    Reverses a previous yank operation, making the specified crate version(s) available again for new dependencies.

--token <API_TOKEN>
    An API token to use for authentication with the registry. If not provided, Cargo will attempt to use a token from the configuration (e.g., from the ~/.cargo/credentials file).

--registry <REGISTRY_NAME>
    The name of the registry to interact with (e.g., crates.io). If not specified, the default registry is used.

--dry-run
    Performs a 'dry run' of the yank operation. Cargo will report what actions it would take without actually making any changes on the registry. Useful for testing.

The cargo yank command is used to mark a specific version of a crate as 'yanked' on a package registry, such as crates.io.

Yanking a version does not delete it from the registry. Instead, it prevents new projects from resolving to that particular version, effectively deprecating it. This is useful for removing a version that has critical bugs or security vulnerabilities without breaking existing builds that might already depend on it via a Cargo.lock file.

When a crate version is yanked, new dependency resolutions will avoid it. However, if a Cargo.lock file already specifies a yanked version, Cargo will still download and use it. This ensures stability for existing projects while guiding new projects towards more stable or secure versions.

Doesn't Delete: Yanking a version does not delete it from the registry; it only marks it as unavailable for new resolutions.

Existing Builds: Existing projects with a Cargo.lock file that specifies a yanked version will still be able to download and use that version.

Ownership Required: Only the owner(s) of a crate can yank or un-yank its versions.

Dependency Stability: You cannot yank the only version of a crate if other crates in the ecosystem depend on it. This prevents breaking the dependency graph for critical foundational crates.

Authentication: The command requires proper authentication (an API token) to interact with the registry.

When Cargo resolves dependencies for a new project or when updating existing ones, it will by default avoid selecting yanked versions. This ensures that new builds receive the most up-to-date and potentially safer versions of dependencies.

However, if a Cargo.lock file already pins a specific, yanked version, Cargo will respect that lock file and continue to use the yanked version, maintaining reproducibility.

cargo yank is primarily used to address issues discovered after a crate version has been published, such as critical bugs, security vulnerabilities, or severe regressions.

It allows maintainers to discourage usage of a problematic version without forcing a breaking change on users who have already adopted it.

The cargo yank command has been an integral part of the Cargo package manager from relatively early in its development, reflecting the necessity for maintainers to manage crate versions effectively on registries like crates.io. Its introduction addressed the need to deprecate faulty or insecure versions without completely removing them and breaking existing builds, a common challenge in package management ecosystems. It evolved alongside other commands focused on registry interaction and crate lifecycle management.

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