crates.io is the official Rust package registry, and publishing your crate there makes it accessible to the entire Rust ecosystem.
Let’s walk through it.
First, you need a crates.io account. You can sign up using your GitHub account.
Once you have an account, you need to generate an API token. Go to your crates.io account settings and click "New API Token." Give it a descriptive name, like "my-laptop-publish-token," and click "Generate token." Copy this token immediately. You won’t be able to see it again, and you’ll need it to authenticate your publishing commands.
Now, on your local machine, you need to configure cargo to use this token. Open your terminal and run:
cargo login
It will prompt you for your API token. Paste the token you just copied. This command stores your token securely in ~/.cargo/credentials.toml.
Next, ensure your Cargo.toml is set up correctly for publishing. This involves a few key fields:
name: The name of your crate. This must be unique on crates.io.version: The semantic version of your crate. For initial publication, this will likely be0.1.0.authors: Your name or organization.description: A concise summary of what your crate does.license: Specify the license under which you’re releasing your crate (e.g., "MIT OR Apache-2.0").repository: A link to your source code repository (e.g., on GitHub).keywords: Relevant keywords to help users discover your crate.categories: Classify your crate into broader categories.
Here’s an example Cargo.toml snippet:
[package]
name = "my-awesome-crate"
version = "0.1.0"
authors = ["Your Name <your.email@example.com>"]
edition = "2021"
description = "A simple example crate for demonstration."
license = "MIT OR Apache-2.0"
repository = "https://github.com/yourusername/my-awesome-crate"
keywords = ["example", "demo", "rust"]
categories = ["examples", "no-std"]
[dependencies]
# Add your dependencies here
Before publishing, it’s a good practice to run cargo check to ensure your code compiles without warnings.
cargo check
You can also run cargo test to make sure all your tests pass.
cargo test
Now you’re ready to publish. Navigate to your crate’s root directory in the terminal (the one containing Cargo.toml) and run:
cargo publish
cargo will first ask you to confirm the details of your crate (name, version, etc.) and will then upload it to crates.io.
If this is your first time publishing a crate with this name, cargo will ask for confirmation.
Packaging my-awesome-crate v0.1.0 (file:///path/to/my-awesome-crate)
Verifying my-awesome-crate v0.1.0 (file:///path/to/my-awesome-crate)
Compiling my-awesome-crate v0.1.0 (file:///path/to/my-awesome-crate)
Finished release [optimized] target(s) in 0.0s
Uploading my-awesome-crate v0.1.0 to crates.io
...
Success!
Once it says "Success!", your crate is live on crates.io. It might take a minute or two for it to appear in search results.
If you need to update your crate, you simply increment the version in your Cargo.toml file and run cargo publish again. For example, to publish a patch update:
[package]
name = "my-awesome-crate"
version = "0.1.1" # Increment the patch version
# ... other fields
Then run:
cargo publish
A crucial detail is that you cannot yank (remove) a published version of a crate after it’s been published. However, you can "yank" a specific version to mark it as unusable for new projects. This is done via the crates.io website under your crate’s page, or programmatically. Yanking is useful if you discover a critical bug in a released version and want to prevent new users from depending on it, while still allowing existing projects that depend on it to continue building.
The next step after publishing is often to write good documentation, which can be done using Rust’s built-in documentation system and cargo doc.