How to publish a Rust crate to crates.io

Step 01: Make an account and verify your email

Log in at crates.io with GitHub (it is the only login option today) and verify your email address on the Account Settings page. crates.io refuses to publish from an account without a verified email.

Step 02: Create a scoped token and run cargo login

Go to crates.io/settings/tokens and create a token. Since 2023 tokens can be limited to specific operations, specific crate names and an expiry date. For a laptop, a token that can publish new crates and update existing ones, with an expiry, is plenty. You will see the token once; copy it before you leave the page.

cargo login

Treat that file like a password. cargo logout removes it.

Step 03: Fill in the Cargo.toml metadata

crates.io needs description and either license (an SPDX expression such as MIT OR Apache-2.0) or license-file. The Cargo Book also lists homepage, repository and readme, and recommends keywords (up to five) and categories. Here is the real [package] block of our most downloaded crate:

The line that matters most is the last one. include is an allow list: only those paths go into the .crate. Without it, Cargo packages everything in the crate folder that git does not ignore, and a stray dataset or screenshot folder can push you past crates.io's 10 MB limit on the .crate file.

Two more fields worth setting: rust-version (your minimum supported Rust, so users on old compilers get a clear error) and documentation if you host docs anywhere other than docs.rs.

Step 04: See exactly what will ship

Before every first publish, run both of these:

cargo package --list      # every file that will go into the .crate
cargo publish --dry-run   # package + compile the packaged copy, no upload

The dry run unpacks the .crate into a temp folder and builds it from there. That is the point: if your code reads a file that include left out, or a path = "../shared" dependency has no version, the build fails on your machine instead of for your first user. Cargo also refuses a dirty git tree unless you pass --allow-dirty, which is a feature, not an obstacle: it stops you publishing code you have not committed.

Step 05: Publish

cargo publish

When it returns, the version is in the index. Anyone can now cargo add it, and docs.rs starts building its documentation automatically.

Step 06: Publishing a workspace (and the 429)

If your project is a workspace, every member is its own crate, and members have to go up in dependency order. Since Rust 1.90 (September 18, 2025), cargo publish --workspace does the ordering for you. The release notes warn that it is still not atomic: a network or server failure can leave half a workspace published, so re-run it rather than bumping versions.

The rate limit is where big workspaces hurt. crates.io does not publish its current numbers. From our own runs, new crate names are the tight one: when we published CoreScout 1.2.0 on October 4, 2026 (33 crates, 19 of them brand new names), we paced it around one new crate every ten minutes. For the October 21 republish of 53 crates, the script waited 65 seconds between crates and slept 10 minutes on any 429. Our real loop, trimmed:

p = subprocess.run(["cargo", "publish"], cwd=crate_dir, capture_output=True, text=True)
if p.returncode:
    if "429" in p.stderr or "Too Many" in p.stderr:
        time.sleep(600)          # rate limited: wait, don't hammer
    continue
time.sleep(65)                   # spacing between successful publishes

If you have a genuine one-time need, the 429 message itself tells you how to ask the crates.io team for a temporary higher limit.

Step 07: What happens after you publish

Something downloads every new version within hours, whether or not a human has seen it. Across 181 of our versions, the mean was 13.45 downloads on day 0 (median 10), then about 1 on day 1 and almost nothing after. We dug into why in the crates.io download count article.

So do not read your first-day number as interest. Watch the quiet days between releases and the Dependents tab instead. Our free crate downloads checker splits any crate's chart into publish-day and quiet-day downloads for you.

Step 08: Publish from CI without a stored token

Once the crate exists, stop pasting tokens into CI secrets. crates.io supports Trusted Publishing (RFC 3691): you tell crates.io which GitHub repository and workflow may publish, and the workflow exchanges its OIDC identity for a short-lived token. The first release still has to be done by hand.

The crates-io-auth-action revokes the token when the job finishes. It is the same idea as an App Store Connect API key in CI, minus the stored secret: no long-lived credential sits in your repo settings at all. In January 2026 crates.io added GitLab CI support (gitlab.com only) and an option to turn off token-based publishing for a crate entirely.

Step 09: Fixing a bad release

cargo yank --version 1.0.1          # new projects won't pick it
cargo yank --version 1.0.1 --undo   # changed your mind

A yank does not delete anything. Projects with that version in their Cargo.lock keep building, and the code stays downloadable. The fix for a broken release is a new patch version. The fix for a leaked secret is rotating the secret.