Publishing a Crate to Crates.io

We’ve used packages from crates.io as dependencies of our project, but you can also share your code with other people by publishing your own packages. The crate registry at crates.io distributes the source code of your packages, so it primarily hosts code that is open source.

Rust and Cargo have features that make your published package easier for people to find and use. We’ll talk about some of these features next and then explain how to publish a package.

Documentation Comments

Use /// for API documentation that generates HTML:

/// Adds one to the number given.
///
/// # Examples
///
/// ```
/// let arg = 5;
/// let answer = my_crate::add_one(arg);
///
/// assert_eq!(6, answer);
/// ```
pub fn add_one(x: i32) -> i32 {
    x + 1
}

Generate docs: cargo doc --open

Standard Sections

  • Panics: Conditions that cause panics
  • Errors: Error types and causes for Result returns
  • Safety: Safety requirements for unsafe functions

Documentation Tests

Code in documentation comments runs as tests with cargo test:

   Doc-tests my_crate

running 1 test
test src/lib.rs - add_one (line 5) ... ok

Module Documentation

Use //! for crate/module-level documentation:

//! # My Crate
//!
//! `my_crate` is a collection of utilities to make performing certain
//! calculations more convenient.

/// Adds one to the number given.
// --snip--
///
/// # Examples
///
/// ```
/// let arg = 5;
/// let answer = my_crate::add_one(arg);
///
/// assert_eq!(6, answer);
/// ```
pub fn add_one(x: i32) -> i32 {
    x + 1
}

Public API Design with pub use

Re-export items to create a clean public API regardless of internal structure:

//! # Art
//!
//! A library for modeling artistic concepts.

pub mod kinds {
    /// The primary colors according to the RYB color model.
    pub enum PrimaryColor {
        Red,
        Yellow,
        Blue,
    }

    /// The secondary colors according to the RYB color model.
    pub enum SecondaryColor {
        Orange,
        Green,
        Purple,
    }
}

pub mod utils {
    use crate::kinds::*;

    /// Combines two primary colors in equal amounts to create
    /// a secondary color.
    pub fn mix(c1: PrimaryColor, c2: PrimaryColor) -> SecondaryColor {
        // --snip--
        unimplemented!();
    }
}

Without re-exports, users must write:

use art::kinds::PrimaryColor;
use art::utils::mix;
//! # Art
//!
//! A library for modeling artistic concepts.

pub use self::kinds::PrimaryColor;
pub use self::kinds::SecondaryColor;
pub use self::utils::mix;

pub mod kinds {
    // --snip--
    /// The primary colors according to the RYB color model.
    pub enum PrimaryColor {
        Red,
        Yellow,
        Blue,
    }

    /// The secondary colors according to the RYB color model.
    pub enum SecondaryColor {
        Orange,
        Green,
        Purple,
    }
}

pub mod utils {
    // --snip--
    use crate::kinds::*;

    /// Combines two primary colors in equal amounts to create
    /// a secondary color.
    pub fn mix(c1: PrimaryColor, c2: PrimaryColor) -> SecondaryColor {
        SecondaryColor::Orange
    }
}

Now users can write:

use art::{PrimaryColor, mix};

Publishing Workflow

  1. Create account: Log in at crates.io with GitHub
  2. Get API token: From account settings, store with cargo login
  3. Add metadata to Cargo.toml:
[package]
name = "your_crate_name"
version = "0.1.0"
edition = "2024"
description = "A brief description of your crate's functionality."
license = "MIT OR Apache-2.0"
  1. Publish: cargo publish

Version Management

  • New versions: Update version in Cargo.toml, run cargo publish
  • Yanking: cargo yank --vers 1.0.1 (prevents new usage, doesn’t break existing)
  • Un-yanking: cargo yank --vers 1.0.1 --undo

Note: Published versions are permanent and cannot be deleted.

License Options

Use SPDX identifiers. Common choices:

  • MIT: Permissive
  • Apache-2.0: Permissive with patent grant
  • MIT OR Apache-2.0: Rust ecosystem standard

For custom licenses, use license-file instead of license.