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:
- Sign up at Crates.io.
- Generate an API token in your account settings.
- 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
(orlicense-file
)- At least one of
documentation
,homepage
, orrepository
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 runcargo 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.