Publishing a Rust Crate

2025-10-28

Publishing a crate to crates.io allows you to share your Rust libraries with the broader community. crates.io is the official Rust package registry, and cargo, Rust’s build tool and package manager, has built-in support for publishing. This guide will walk you through the process from preparing your crate to publishing it.

1. Prepare Your Crate’s Metadata

Before you can publish, you need to add some important metadata to your Cargo.toml file. This information helps others discover and use your crate.

A well-configured [package] section in Cargo.toml is essential.

// filepath: Cargo.toml
[package]
name = "my-awesome-crate"
version = "0.1.0"
edition = "2021"
authors = ["Your Name <you@example.com>"]
description = "A short, clear description of what my-awesome-crate does."
license = "MIT OR Apache-2.0"
readme = "README.md"
homepage = "https://github.com/you/my-awesome-crate"
repository = "https://github.com/you/my-awesome-crate"
keywords = ["keyword1", "keyword2", "cli"]
categories = ["command-line-utilities"]

# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html

[dependencies]
# ... your dependencies

Key metadata fields:

  • name: The name of your crate. This will be its identifier on crates.io.
  • version: Follow Semantic Versioning. Cargo will enforce this.
  • authors: Your name and email.
  • description: A brief (one or two sentences) summary of your crate’s purpose.
  • license: A valid SPDX 2.1 license expression. Using a common license like MIT or Apache-2.0 is highly recommended.
  • readme: The path to your README.md file, which will be displayed on the crate’s crates.io page.
  • repository: A link to the source code repository.
  • keywords and categories: These help users find your crate when searching on crates.io.

2. Create a crates.io Account

You need an account on crates.io to get an API token for publishing.

  1. Visit crates.io.
  2. Log in with your GitHub account.
  3. Navigate to Account Settings in the user menu.
  4. Generate a new API token. Copy it to your clipboard.

3. Log in with Cargo

Next, use cargo to save your API token on your local machine. This authenticates you with crates.io.

cargo login <your_api_token>

Paste the token you copied and press Enter. Cargo will store it securely in ~/.cargo/credentials.toml.

4. Run a Dry Run

It’s always a good idea to perform a “dry run” before publishing. This command will compile your crate and show you exactly what files will be uploaded, without actually publishing. It helps catch missing files or other packaging issues.

cargo publish --dry-run

Review the output carefully. Ensure no sensitive files are included and that all necessary files (like src/**/*.rs, Cargo.toml, README.md, and LICENSE) are present.

5. Publish the Crate

Once you are confident that your crate is ready, run the publish command.

cargo publish

Cargo will package your crate, upload it to crates.io, and make it available for others to use.

Note: Publishing a specific version of a crate is permanent. You cannot overwrite a published version. If you find a bug, you must publish a new version (e.g., 0.1.1).

Managing Published Crates

Publishing a New Version

To release an update:

  1. Update the version number in your Cargo.toml file (e.g., from 0.1.0 to 0.1.1 or 0.2.0).
  2. Commit your changes to version control.
  3. Run cargo publish again.

Yanking a Version

If you publish a version with a serious bug, you can “yank” it. Yanking prevents new projects from depending on that version but does not delete it. Existing projects that depend on the yanked version will still be able to download it.

# Yank a specific version
cargo yank --vers 0.1.1

# You can also un-yank a version if you made a mistake
cargo yank --vers 0.1.1 --undo