Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

14.4 Publishing Crates Part 2

14.4.1 Create and Set Up a crates.io Account

Before publishing any crate, you need to have a crates.io account and obtain an API token. To do this, visit the crates.io homepage and sign in with a GitHub account. Currently, only GitHub login is supported. If you are already signed in, open your account settings at https://crates.io/me/ and find the API key. Then use the cargo login command locally and paste your API key when prompted:

$ cargo login
just1a1nexample

This command tells Cargo your API token and stores it locally in ~/.cargo/credentials.toml. Note that this token must not be shared with anyone else. If you leak it, you should revoke it and generate a new token on crates.io.

14.4.2 Add Metadata to the Crate

Before publishing a crate, you also need to add some metadata to the [package] section in Cargo.toml:

  • First, make sure the project name is unique on the website.
  • Second, write a description, which is a short introduction. It does not need to be long; one or two sentences is enough. The description will appear in crate search results.
  • You need to provide the license identifier value used by this crate (you can look it up at spdx.org/licenses/); you can specify multiple licenses, separated by OR, in license.
  • Semantic version information goes in version.

Of course, you can provide more information than that; for details, see the Cargo Book.

The full [package] section should look like this:

[package]
name = "guessing_game"
version = "0.1.0"
edition = "2021"
description = "A fun game where you guess what number the computer has chosen."
license = "MIT OR Apache-2.0"

14.4.3 Publish a Crate with a Command

You can publish a crate with the cargo publish command, but only if the metadata is complete and the project name is unique. Your crates.io account must also have a verified email address before publishing is allowed.

If something goes wrong, cargo publish reports an error:

$ cargo publish
    Updating crates.io index
warning: manifest has no description, license, license-file, documentation, homepage or repository.
See https://doc.rust-lang.org/cargo/reference/manifest.html#package-metadata for more info.
......
error: failed to publish to registry at https://crates.io

Caused by:
  the remote server responded with an error: missing or empty metadata fields: description, license. Please see https://doc.rust-lang.org/cargo/reference/manifest.html for how to upload metadata

I omitted some of the middle content. The Caused by section says that the error was caused by missing metadata.

Once a crate is published, it is permanent: that version cannot be overwritten, and the code cannot be deleted except in certain limited circumstances. This is so projects depending on that version can continue to work normally.

14.4.4 Publish a New Crate Version

If you need to publish a newer version of an existing crate, modify the crate source code, update the version value in Cargo.toml according to semantic versioning, and then publish again.

14.4.5 Yank a Version

Yanking a version prevents new projects from depending on that version, but projects that were already built against it can still use and download it.

The command is cargo yank --vers the-specified-version. For example, to yank version 1.0.1, write:

cargo yank --vers 1.0.1

If you change your mind after yanking and want to undo it, write:

cargo yank --vers 1.0.1 --undo

yank means:

  • Projects that already have a generated Cargo.lock will not be interrupted by the version being yanked.
  • Future Cargo.lock files will not use the yanked version.