'\" t
.TH "CARGO\-YANK" "1"
.nh
.ad l
.ss \n[.ss] 0
.SH "NAME"
cargo\-yank \[em] Remove a pushed crate from the index
.SH "SYNOPSIS"
\fBcargo yank\fR [\fIoptions\fR] \fIcrate\fR@\fIversion\fR
.br
\fBcargo yank\fR [\fIoptions\fR] \fB\-\-version\fR \fIversion\fR [\fIcrate\fR]
.SH "DESCRIPTION"
The yank command removes a previously published crate\[cq]s version from the
server\[cq]s index. This command does not delete any data, and the crate will
still be available for download via the registry\[cq]s download link.
.sp
Cargo will not use a yanked version for any new project or checkout without a
pre\-existing lockfile, and will generate an error if there are no longer
any compatible versions for your crate.
.sp
This command requires you to be authenticated with either the \fB\-\-token\fR option
or using \fBcargo\-login\fR(1).
.sp
If the crate name is not specified, it will use the package name from the
current directory.
.SS "How yank works"
For example, the \fBfoo\fR crate published version \fB1.5.0\fR and another crate \fBbar\fR
declared a dependency on version \fBfoo = "1.5"\fR\&. Now \fBfoo\fR releases a new, but
not semver compatible, version \fB2.0.0\fR, and finds a critical issue with \fB1.5.0\fR\&.
If \fB1.5.0\fR is yanked, no new project or checkout without an existing lockfile
will be able to use crate \fBbar\fR as it relies on \fB1.5\fR\&.
.sp
In this case, the maintainers of \fBfoo\fR should first publish a semver compatible
version such as \fB1.5.1\fR prior to yanking \fB1.5.0\fR so that \fBbar\fR and all projects
that depend on \fBbar\fR will continue to work.
.sp
As another example, consider a crate \fBbar\fR with published versions \fB1.5.0\fR,
\fB1.5.1\fR, \fB1.5.2\fR, \fB2.0.0\fR and \fB3.0.0\fR\&. The following table identifies the
versions cargo could use in the absence of a lockfile for different SemVer
requirements, following a given release being yanked:

.TS
allbox tab(:);
lt lt lt lt.
T{
Yanked Version / SemVer requirement
T}:T{
\fBbar = "1.5.0"\fR
T}:T{
\fBbar = "=1.5.0"\fR
T}:T{
\fBbar = "2.0.0"\fR
T}
T{
\fB1.5.0\fR
T}:T{
Use either \fB1.5.1\fR or \fB1.5.2\fR
T}:T{
\fBReturn Error\fR
T}:T{
Use \fB2.0.0\fR
T}
T{
\fB1.5.1\fR
T}:T{
Use either \fB1.5.0\fR or \fB1.5.2\fR
T}:T{
Use \fB1.5.0\fR
T}:T{
Use \fB2.0.0\fR
T}
T{
\fB2.0.0\fR
T}:T{
Use either \fB1.5.0\fR, \fB1.5.1\fR or \fB1.5.2\fR
T}:T{
Use \fB1.5.0\fR
T}:T{
\fBReturn Error\fR
T}
.TE
.sp
.SS "When to yank"
Crates should only be yanked in exceptional circumstances, for example, an
accidental publish, an unintentional SemVer breakages, or a significantly
broken and unusable crate. In the case of security vulnerabilities, \fIRustSec\fR <https://rustsec.org/>
is typically a less disruptive mechanism to inform users and encourage them
to upgrade, and avoids the possibility of significant downstream disruption
irrespective of susceptibility to the vulnerability in question.
.sp
A common workflow is to yank a crate having already published a semver
compatible version, to reduce the probability of preventing dependent
crates from compiling.
.sp
When addressing copyright, licensing, or personal data issues with a published
crate, simply yanking it may not suffice. In such cases, contact the maintainers
of the registry you used. For crates.io, refer to their \fIpolicies\fR <https://crates.io/policies> and contact
them at <help@crates.io>\&.
.sp
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 the crate only prevents new
users from downloading it, but cannot stop those who have already downloaded it
from keeping or even spreading the leaked credentials.
.SH "OPTIONS"
.SS "Yank Options"
.sp
\fB\-\-vers\fR \fIversion\fR, 
\fB\-\-version\fR \fIversion\fR
.RS 4
The version to yank or un\-yank.
.RE
.sp
\fB\-\-undo\fR
.RS 4
Undo a yank, putting a version back into the index.
.RE
.sp
\fB\-\-token\fR \fItoken\fR
.RS 4
API token to use when authenticating. This overrides the token stored in
the credentials file (which is created by \fBcargo\-login\fR(1)).
.sp
\fICargo config\fR <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 \fBCARGO_REGISTRY_TOKEN\fR environment
variable. Tokens for other registries may be specified with environment
variables of the form \fBCARGO_REGISTRIES_NAME_TOKEN\fR where \fBNAME\fR is the name
of the registry in all capital letters.
.RE
.sp
\fB\-\-index\fR \fIindex\fR
.RS 4
The URL of the registry index to use.
.RE
.sp
\fB\-\-registry\fR \fIregistry\fR
.RS 4
Name of the registry to use. Registry names are defined in \fICargo config
files\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. If not specified, the default registry is used,
which is defined by the \fBregistry.default\fR config key which defaults to
\fBcrates\-io\fR\&.
.RE
.SS "Display Options"
.sp
\fB\-v\fR, 
\fB\-\-verbose\fR
.RS 4
Use verbose output. May be specified twice for \[lq]very verbose\[rq] output which
includes extra output such as dependency warnings and build script output.
May also be specified with the \fBterm.verbose\fR
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.sp
\fB\-q\fR, 
\fB\-\-quiet\fR
.RS 4
Do not print cargo log messages.
May also be specified with the \fBterm.quiet\fR
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.sp
\fB\-\-color\fR \fIwhen\fR
.RS 4
Control when colored output is used. Valid values:
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBauto\fR (default): Automatically detect if color support is available on the
terminal.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBalways\fR: Always display colors.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBnever\fR: Never display colors.
.RE
.sp
May also be specified with the \fBterm.color\fR
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.SS "Common Options"
.sp
\fB+\fR\fItoolchain\fR
.RS 4
If Cargo has been installed with rustup, and the first argument to \fBcargo\fR
begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such
as \fB+stable\fR or \fB+nightly\fR).
See the \fIrustup documentation\fR <https://rust\-lang.github.io/rustup/overrides.html>
for more information about how toolchain overrides work.
.RE
.sp
\fB\-\-config\fR \fIKEY=VALUE\fR or \fIPATH\fR
.RS 4
Overrides a Cargo configuration value. The argument should be in TOML syntax of \fBKEY=VALUE\fR,
or provided as a path to an extra configuration file. This flag may be specified multiple times.
See the \fIcommand\-line overrides section\fR <https://doc.rust\-lang.org/cargo/reference/config.html#command\-line\-overrides> for more information.
.RE
.sp
\fB\-C\fR \fIPATH\fR
.RS 4
Changes the current working directory before executing any specified operations. This affects
things like where cargo looks by default for the project manifest (\fBCargo.toml\fR), as well as
the directories searched for discovering \fB\&.cargo/config.toml\fR, for example. This option must
appear before the command name, for example \fBcargo \-C path/to/my\-project build\fR\&.
.sp
This option is only available on the \fInightly
channel\fR <https://doc.rust\-lang.org/book/appendix\-07\-nightly\-rust.html> and
requires the \fB\-Z unstable\-options\fR flag to enable (see
\fI#10098\fR <https://github.com/rust\-lang/cargo/issues/10098>).
.RE
.sp
\fB\-h\fR, 
\fB\-\-help\fR
.RS 4
Prints help information.
.RE
.sp
\fB\-Z\fR \fIflag\fR
.RS 4
Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details.
.RE
.SH "ENVIRONMENT"
See \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/environment\-variables.html> for
details on environment variables that Cargo reads.
.SH "EXIT STATUS"
.sp
.RS 4
\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fB101\fR: Cargo failed to complete.
.RE
.SH "EXAMPLES"
.sp
.RS 4
\h'-04' 1.\h'+01'Yank a crate from the index:
.sp
.RS 4
.nf
cargo yank foo@1.0.7
.fi
.RE
.RE
.SH "SEE ALSO"
\fBcargo\fR(1), \fBcargo\-login\fR(1), \fBcargo\-publish\fR(1)