23.9 Publishing a Crate to Crates.io

Crates.io is Rust’s central package registry. Most library and application crates are published there as source.

23.9.1 Creating a Crates.io Account

To publish a crate, you need a Crates.io account and an API token:

  1. Sign up at Crates.io.
  2. Generate an API token in your account settings.
  3. Run cargo login <API_TOKEN> locally to authenticate.

23.9.2 Choosing a Crate Name

Crate names on Crates.io are global. Pick something descriptive and memorable, using ASCII letters, digits, underscores, or hyphens.

23.9.3 Required Fields in Cargo.toml

To publish, your Cargo.toml must include:

  • name
  • version
  • description
  • license (or license-file)
  • At least one of documentation, homepage, or repository

The description is typically brief. If you use license-file = "LICENSE", place the license text in that file—common for dual-licensing or custom licenses.

23.9.4 Publishing

cargo publish

Cargo packages your crate and uploads it to Crates.io. Once published, anyone can depend on it using:

[dependencies]
your_crate = "x.y.z"

23.9.5 Updating and Yanking

  • Updating: Bump the version in Cargo.toml (following SemVer) and run cargo publish.

  • Yanking: If a published version is critically flawed, yank it:

    cargo yank --vers 1.2.3

Yanked versions remain available to existing projects that already have them in Cargo.lock, but new users won’t fetch them by default.

23.9.6 Deleting a Crate

Crates.io does not allow complete removal of published versions. In exceptional cases, contact the Crates.io team. Generally, yanking is preferred over removal.