23.9 Publishing a Crate to Crates.io

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

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, memorable, and composed of 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, used for search queries on Crates.io and platforms like lib.rs. If you use license-file = "LICENSE", place the license text in that file (common if you dual-license or use a custom license).

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 accessible 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. For exceptional cases, contact the Crates.io team. Generally, yanking is preferred over removal.