Cargo publishing guide warns Rust crate releases are permanent

Before you hit publish, remember this is not a build artifact

Publishing a Rust crate is a supply-chain event, not a casual upload. The Cargo Book is blunt about it: once a version is published to crates.io, it cannot be overwritten, and the code cannot be deleted. That permanence is not an accident. crates.io launched with Cargo in 2014 as permanent storage for releases, so projects could keep building the exact same versions years later.

That is the mindset shift first-time crate authors need most. A publish button can look routine, but the registry treats it like a durable record. Cargo’s own FAQ frames crates.io as the primary package source, in the same role that npmjs.com and rubygems.org play for their ecosystems, while still leaving git repositories available for early development and temporary patches.

Get the account and token story right before anything else

The first practical checkpoint is access. Cargo’s publishing flow starts with logging in through GitHub, verifying an email address, creating an API token, and storing that token locally with `cargo login`. That token should be treated like a key to the registry, because it is. If it leaks, revoke it.

That advice matters even more now that crates.io has moved beyond one-size-fits-all tokens. In June 2023, it introduced scoped API tokens that can be limited to publishing new versions only, or even restricted to specific crate names. By early 2026, crate owners could enforce Trusted Publishing only, which disables traditional API-token publishing for selected crates and removes the need for GitHub Actions secrets when releasing from CI/CD.

Treat metadata like packaging, not paperwork

Crate names on crates.io are first-come, first-served, so naming is part of the release strategy long before publish day. Once a name is taken, the practical identity of the crate is set, and the search surface around it becomes part of how people judge your work.

The Cargo publishing guide pushes authors to fill out the metadata that makes a crate legible to other developers: license, homepage, repository, readme, keywords, and categories. That is not decorative. crates.io’s searchable index depends on this information, and the crate page itself now carries richer presentation, including dynamic OpenGraph images that show the crate name, keywords, description, latest or default version, number of releases, license, and crate size. If you are publishing a library, the guide also points you toward the Rust API Guidelines, which is Cargo’s way of saying packaging and interface quality belong in the same conversation.

Inspect the archive before the registry does

`cargo publish` does more than upload files. It checks the package, compresses the source into a `.crate` file, extracts that archive into a temporary directory to verify that it compiles, and then uploads it to the default registry, crates.io. That sequence is a reminder that what you think you are publishing and what actually gets packaged can differ in small, embarrassing ways.

That is why `cargo publish dry-run` and `cargo package` are essential habits, not optional caution. They surface warnings and let you inspect the generated archive under `target/package` before the release becomes permanent. The Cargo guide also calls out the 10 MB crate size limit and warns about accidentally bundling things that do not belong in a release, such as test data, documentation sites, or generated files.

A clean package is easier to trust and easier to reuse. The release should contain exactly the source and metadata another developer needs, not the extra build detritus that bloats the archive and complicates review.

Understand the registry’s trust model, not just its upload flow

The publishing workflow has tightened because the ecosystem has been forced to think harder about supply-chain risk. In February 2025, crates.io laid out deletion rules that are intentionally narrow: a crate can be removed only if it was published less than 72 hours ago, or if it has a single owner, low downloads relative to its age, and no dependents on crates.io. That is not a “delete later” system. It is a system built to preserve history unless there is a strong reason not to.

The history behind that caution is real. After a malware incident in 2023, the crates.io team yanked the affected crates and locked the account, which made the packages uninstallable through normal Cargo usage. The files would still have remained downloadable directly from static.crates.io at the time, but normal installation paths were cut off. In 2025, crates.io also published multiple malicious-crate notices, with affected users disabled and the crates deleted shortly after discovery.

That backdrop explains why release practices are now part of Rust security culture. A crate does not just represent code. It can become a dependency for thousands of downstream builds, and the registry has learned to treat that consequence seriously.

Make workspace publishing predictable before the first release

Once a project grows past a single crate, publication becomes a coordination problem. Community tooling has emerged around that pain point, including cargo-publish-workspace and cargo-publish-all, both of which aim to publish packages in dependency order while verifying builds. Those tools exist because multi-crate releases are where small mistakes get amplified.

If your workspace contains interdependent crates, the checklist before publishing is simple but unforgiving: make sure the dependency graph is in order, verify that every member builds cleanly, and confirm that the versioning plan matches the publish order. The more crates in the workspace, the more a release starts to look like choreography.

Read crates.io like a long-lived archive, because that is what it is

The scale alone should change how you think about release hygiene. The crates.io index now lists more than 260,000 total crates, which means every new release enters a densely populated registry where metadata, packaging, and trust signals matter. In a catalog that large, small habits make a big difference: precise descriptions, accurate categories, a maintained repository link, and a package that excludes junk all help other developers decide whether to depend on you.

That is the real lesson of the publishing guide. Cargo is not asking first-time authors to perform bureaucracy for its own sake. It is asking them to handle a permanent artifact with the care of something that will be rebuilt, audited, and depended on long after the original branch is gone.