🎓 A1Learner
🔍
0 of 149 lessons completed

Rust Publishing to Crates.io

Publishing uploads a library to crates.io for anyone to use. One publishing step cannot be undone.

Two fields you must add

Without a description and a license, cargo publish refuses. Many crates offer the dual licence MIT OR Apache-2.0:

description = "Small helpers for working with words."
license = "MIT OR Apache-2.0"

Log in once with your token

Sign in on crates.io with a GitHub account, copy your API token from account settings, and paste it here. Cargo saves it in ~/.cargo/credentials.toml — a secret, so never share it:

cargo login

Preview before it counts

The first command lists the exact files that would be uploaded. The second packs everything up but uploads nothing:

cargo package --list
cargo publish --dry-run

Yank a broken version

A yank stops new projects from depending on the version. Projects already using it keep building. And --undo reverses the yank:

cargo yank --vers 1.0.1
cargo yank --vers 1.0.1 --undo

Bump a version in code

Raising a field by hand follows the same reset rules Cargo expects: a minor bump zeroes the patch:

let mut version = Version::parse("0.2.6").unwrap();
version.patch += 1;
println!("patch release = {}", version);
version.minor += 1;
version.patch = 0;
println!("minor release = {}", version);

Pick the newest allowed version

let req = VersionReq::parse(">=1.2, <2.0.0").unwrap();
let candidates = ["1.1.0", "1.5.0", "2.0.0"];
let best = candidates
    .iter()
    .filter_map(|s| Version::parse(s).ok())
    .filter(|v| req.matches(v))
    .max();
println!("best = {}", best.unwrap());

Example

// Cargo.toml
// [package]
// name = "wordtools"
// version = "0.1.0"
// description = "Small helpers for working with words."
// license = "MIT OR Apache-2.0"
fn main() {
    println!("ready to publish: wordtools 0.1.0");
    println!("description and license are set");
    println!("cargo publish uploads this version forever");
}

Key points

  • A crate name on crates.io is first come, first served.
  • Search the name before you publish.
  • Once a name is taken, no one else can publish under it.
  • Use keywords to help searches find the crate.
  • Pick up to 5 words of your own.
  • crates.io allows no more.
  • And each word is at most 20 characters.
  • Use categories to shelve the crate on crates.io.
  • You may pick up to 5.
  • Each one must match the fixed list on the crates.io categories page exactly.
  • Use the rust-version field to name the oldest compiler your crate supports.
  • A user on an older rustc gets one clear error.
  • The error reads: rustc 1.99.1 is not supported... requires rustc 1.99.2, in a real test.
  • They do not get a wall of confusing failures instead.
  • Publishing puts one exact version on crates.io for anyone to use.
  • Cargo requires a short description and a licence to publish.

In this example, the comments show a Cargo.toml that is ready to publish. It has a name, a version, and a one-line description. It also has the dual licence MIT OR Apache-2.0. The runnable code prints the checklist in order. First, the crate and its version. Then, the two required fields. Last, the warning that matters most. cargo publish uploads this exact version permanently. So the check happens before the command, not after.

Note

Yank is a safety valve, not an eraser.

Because published code stays archived for good, check the name, the metadata and the contents twice before you publish.

Try it Yourself

Edit the code, then press Run.

Running is simulated · Rust Playground

Exercise

You published version 1.0.1 and then found it is broken. What does cargo yank do?