How to Publish Your First Rust Crate: A Step‑by‑Step Guide

I just released my first Rust crate and want to share the whole process.

I'm learning Rust and decided to implement a function converting integers to Roman numerals as a small, manageable project.

I started coding, using NixOS as my environment.

First I added Roman numeral symbols as constants, then implemented the conversion function, testing it with a simple main that prints results.

After completing the function, I refined the code using suggestions from the Rust language server and renamed variables for readability, following the Rust API Guidelines.

Next I explain how to turn the code into a library and publish it, a process that applies to any Rust project:

Describe your project in Cargo.toml .

Create a comprehensive README file.

Publish the code to a public repository.

Add appropriate tests.

Write documentation for the code.

Publish.

1. Describe your project in Cargo.toml

Usually we create a project with cargo new , which generates a basic Cargo.toml . Some keys need manual setting. Example:

<code>[package]
name = "roman_numerals_fn"
version = "1.0.0"
edition = "2021"
rust-version = "1.60.0"
description = """ A function to convert integers to their roman numeral representation as strings. Values from 1 to 3999 are possible, otherwise it returns an OutOfRangeError. Zero has no representation in roman numerals. """
authors = ["Pierre Thibault <[email protected]>"]
license = "MIT"
keywords = ["roman", "numerals", "roman-numerals"]
categories = ["text-processing"]
readme = "README.md"
repository = "https://github.com/Pierre-Thibault/roman_numerals.git"
homepage = "https://github.com/Pierre-Thibault/roman_numerals"
[dependencies]
range_check = "0.2.0"
[dev-dependencies]
regex = "1.11.0"
[lib]
name = "roman_numerals_fn"
path = "src/roman_numerals_fn.rs"
test = true
doctest = true
bench = true
doc = true
proc-macro = false
crate-type = ["lib"]
required-features = []</code>

Key points:

edition should stay at 2021 , the current default.

rust-version indicates the minimum required Rust version; you can find it with cargo msrv (install msrv first if needed).

Make sure readme points to the actual README file.

repository must start with http or https; URLs like [email protected] are rejected.

[dependencies] are needed by users of your crate, while [dev-dependencies] are only for development (e.g., testing tools).

If you publish an executable instead of a library, remove the [lib] section and add a [[bin]] section; a package can contain one library but multiple binaries.

For more details on the keys, see the Cargo Book.

Note that cargo build does not produce a physical library file like in C/C++; Rust libraries are not compiled to a separate file unless you create one.

To understand the .toml structure, refer to the official TOML documentation or a quick reference.

2. Create a comprehensive README file

A good README.md is the first impression for users; see “How to write an excellent README for a GitHub project” for tips.

3. Publish the code to a public repository

Use platforms such as GitHub, GitLab, or Bitbucket, ensure the repository is public, and follow basic Git steps. See “How to push a local project to GitHub”.

4. Add appropriate tests

Provide thorough unit tests covering all code; run cargo test to ensure they pass.

5. Write documentation for the code

Refer to “What is rustdoc?” and generate docs with cargo doc , iterating until the documentation is complete.

6. Publish

Before publishing, make sure you have optimized the code, completed the README, added tests, and written documentation. Then run:

<code>cargo publish</code>

This uploads the crate to crates.io . If you lack an account, the command will prompt you to create one and guide you through any errors.

Following these steps lets you successfully create and publish your own Rust crate.