skip to content

With `cargo publish`, what happens when you upload version 2.1.0 of a crate, and why can't you fix a mistake by re-uploading 2.1.0?

level: juniorimportance: should knowfreq 35%

answer

  1. package, verify, upload
  2. the registry is an archive
  3. a version number is spent once
  4. fixes ship as 2.1.1

basics

~20 s

cargo publish packs the crate into a .crate file, builds that tarball to verify it, and uploads it. A published version is permanent: it cannot be overwritten or deleted, so a fix ships as a new version such as 2.1.1.

solid answer

~40 s

`cargo publish` checks the manifest (including which registries `package.publish` allows), creates a compressed `.crate` file the same way `cargo package` does, extracts it into `target/package` and builds it from that pristine copy, then uploads it and waits for the version to appear in the registry index. It needs an API token, usually stored with `cargo login`. The upload is permanent: the version can never be overwritten and the code cannot be deleted, because the registry is meant to be an archive that lockfiles can rely on. Cargo checks the index first, so re-running `cargo publish` on 2.1.0 stops with "already exists". The fix is to bump `version` to 2.1.1 and publish again; `cargo yank` can stop new projects from picking 2.1.0, but it deletes nothing.

code

console · 4 lines
console
$ cargo publish
note: found `internal` as only allowed registry. Publishing to it automatically.
    Updating `internal` index
error: crate [email protected] already exists on `internal` index

go deeper

for a junior

Recall the pipeline: check, package into a .crate, build that tarball, upload, wait for the index. Then state plainly that a published version can never be replaced and fixes get a new number.

for a middle

Explain why the registry refuses overwrites: lockfiles record exact versions, so a version must always mean the same bytes. Contrast yank, which only hides a version from new resolution.

for a senior

Show release discipline: run cargo publish --dry-run in CI, keep the token out of logs, and plan the fix-forward path (2.1.1, then maybe a yank) before anything goes wrong.

for a principal

Frame permanence as a contract with every downstream lockfile, which is why release automation, tagging and changelogs matter more than speed of publishing.

## What `cargo publish` does **`cargo publish`** is Cargo's command for uploading a package to a **registry** (crates.io by default, or a private registry named in Cargo's config). For a library maintainer cutting version 2.1.0 of a crate called `quantile-sketch`, one command runs a short pipeline: 1. **Checks** the manifest, including the `package.publish` key, which can restrict the registries the package may go to. 2. **Packages** the source into a compressed `.crate` file, exactly as `cargo package` would, under `target/package/`. 3. **Verifies** the package by extracting the `.crate` and building it from scratch, so a file that is missing from the tarball shows up now instead of on a user's machine. `--no-verify` skips this step. 4. **Uploads** the `.crate` to the registry's web API. The server runs its own checks before accepting it. 5. **Waits** for the new version to appear in the registry index, polling until it does. A timeout here does not undo the upload. `cargo publish --dry-run` runs every check and the verify build but does not upload; `cargo package` does the same packaging and verification without any registry upload. ## Why a published version is permanent The Cargo book is blunt: a publish is generally permanent, **the version can never be overwritten, and the code cannot be deleted**. There is no limit on how many versions you publish, but each version number is spent once. The reason is reproducibility. Thousands of projects record exact versions in their `Cargo.lock`, and the registry promises that `quantile-sketch 2.1.0` will always mean the same bytes. If 2.1.0 could be replaced, a build that worked yesterday could silently compile different code today. Cargo enforces this on the client side too. Before packaging, it looks the version up in the index and stops: - re-running `cargo publish` without changing `version` fails with an "already exists" error; - with `--dry-run`, the same situation is downgraded to a warning, so a rehearsal still runs. ## How a mistake is fixed | You want to... | Cargo's tool | |---|---| | ship corrected code | bump `version` in `Cargo.toml` (2.1.0 to 2.1.1) and `cargo publish` again | | stop new projects from choosing a broken version | `cargo yank --version 2.1.0` (and `--undo` to reverse it) | | remove leaked secrets from the code | not possible through Cargo: revoke the secret, because the old `.crate` stays downloadable | A **yank** is not a delete. It marks the version so that no new lockfile selects it, while every existing `Cargo.lock` that names it keeps building. Yanking also never frees the version number: 2.1.0 cannot be re-uploaded after a yank either. ## Before the first publish - Get an **API token** from the registry and run `cargo login` (or `cargo login --registry NAME` for another registry). With the default `cargo:token` credential provider the token is stored in plain text in `credentials.toml` in Cargo's home directory, normally `~/.cargo`. - Treat the token as a secret. `cargo logout` removes it from local storage, but Cargo notes that this does **not** revoke it on the server. - Fill in the metadata the registry demands. crates.io requires `description` and either `license` or `license-file`; `cargo package` warns about missing metadata. - Run `cargo publish --dry-run` (or `cargo package --list`) and read what goes into the tarball. ## Who may publish Only a crate's **owners** may publish new versions or yank old ones. `cargo owner --list` shows them, `cargo owner --add` invites a user or a team, and `cargo owner --remove` takes one away. On crates.io a user added by name gets full rights, including adding and removing owners, while a GitHub team added as `github:org:team` may publish and yank but cannot change the owner list. ## Making permanence routine Because every upload is final, the Cargo book recommends treating publishing as a **release process** and automating what you can. Each version should come with: - a **changelog entry**, preferably curated by hand; - a **git tag** pointing at the exact commit that was published. A typical routine for 2.1.0 is to bump `version`, update the changelog, run `cargo publish --dry-run` in CI, tag the commit, and only then run `cargo publish`. If a mistake slips through, the response is always forward: a new patch version, plus a yank of the bad one when new users must not pick it. Third-party release tools such as cargo-release and release-plz, which the Cargo book lists as examples, script this sequence; whichever you use, the registry's rule does not change: one version number, one immutable upload.

  • What is the difference between `cargo publish --dry-run` and `cargo package`?
    Both create the `.crate` under `target/package` and run the verify build. `cargo publish --dry-run` also goes through publishing's own checks, such as which registries `package.publish` allows and whether the version already exists in that registry's index (reported as a warning on a dry run), and then stops short of the upload. `cargo package` uploads nothing and skips those publishing checks: it packages even a crate marked `publish = false`.
  • If 2.1.0 has a bug, does yanking it let you publish a corrected 2.1.0?
    No. A yank only tells the resolver not to choose 2.1.0 for new lockfiles; the version and its code stay in the registry, and the number is still taken. Publish the fix as 2.1.1, and yank 2.1.0 only if it is harmful enough that new users must not pick it up.

  • Re-running cargo publish overwrites the existing 2.1.0
  • cargo yank deletes the version and its code
  • After a yank you can publish the same version number again
  • cargo logout revokes the API token on the registry
  • --no-verify is a safe default that only speeds publishing up