Text of doc.rust-lang.org › cargo › reference › publishing.html as Styx crawled it on Nov 19, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

Publishing on crates.io - The Cargo Book

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 The Cargo Book Publishing on crates.io Once you’ve got a library that you’d like to share with the world, it’s time to publish it on crates.io ! Publishing a crate is when a specific version is uploaded to be hosted on crates.io . Take care when publishing a crate, because a publish is generally permanent .

The version can never be overwritten, and the code cannot be deleted. There is no limit to the number of versions which can be published, however. Before your first publish First things first, you’ll need an account on crates.io to acquire an API token. To do so, visit the home page and log in via a GitHub account (required for now). You will also need to provide and verify your email address on the Account Settings page.

Once that is done create an API token , make sure you copy it. Once you leave the page you will not be able to see it again. Then run the cargo login command. $ cargo login Then at the prompt put in the token specified. please paste the API Token found on https://crates.io/me below abcdefghijklmnopqrstuvwxyz012345 This command will inform Cargo of your API token and store it locally in your ~/.cargo/credentials.toml .

Note that this token is a secret and should not be shared with anyone else. If it leaks for any reason, you should revoke it immediately. Note The cargo logout command can be used to remove the token from credentials.toml . This can be useful if you no longer need it stored on the local machine. Before publishing a new crate Keep in mind that crate names on crates.io are allocated on a first-come-first-serve basis. Once a crate name is taken, it cannot be used for another crate.

Check out the metadata you can specify in Cargo.toml to ensure your crate can be discovered more easily! Before publishing, make sure you have filled out the following fields: license or license-file description homepage repository readme It would also be a good idea to include some keywords and categories , though they are not required. If you are publishing a library, you may also want to consult the Rust API Guidelines .

Packaging a crate The next step is to package up your crate and upload it to crates.io . For this we’ll use the cargo publish subcommand. This command performs the following steps: Perform some verification checks on your package. Compress your source code into a .crate file. Extract the .crate file into a temporary directory and verify that it compiles. Upload the .crate file to crates.io . The registry will perform some additional checks on the uploaded package before adding it.

It is recommended that you first run cargo publish --dry-run (or cargo package which is equivalent) to ensure there aren’t any warnings or errors before publishing. This will perform the first three steps listed above. $ cargo publish --dry-run You can inspect the generated .crate file in the target/package directory. crates.io currently has a 10MB size limit on the .crate file. You may want to check the size of the .crate file to ensure you didn’t accidentally package up large assets that are not required to build your package, such as test data, website documentation, or code generation.

You can check which files are included with the following command: $ cargo package --list Cargo will automatically ignore files ignored by your version control system when packaging, but if you want to specify an extra set of files to ignore you can use the exclude key in the manifest: [package] # ... exclude = [ "public/assets/*", "videos/*", ] If you’d rather explicitly list the files to include, Cargo also supports an include key , which if set, overrides the exclude key: [package] # ... include = [ "**/*.rs", ] Uploading the crate When you are ready to publish, use the cargo publish command to upload to crates.io : $ cargo publish And that’s it, you’ve now published your first crate!

Publishing a new version of an existing crate In order to release a new version, change the version value specified in your Cargo.toml manifest. Keep in mind the SemVer rules which provide guidelines on what is a compatible change. Then run cargo publish as described above to upload the new version. Tip Consider the full release process and automate what you can. Each version should include: A changelog entry, preferably manually curated though a generated one is better than nothing A git tag pointing to the published commit Examples of third-party tools that are representative of different workflows include (in alphabetical order): cargo-release cargo-smart-release release-plz For more, see crates.io .

Managing a crates.io-based crate Management of crates is primarily done through the command line cargo tool rather than the crates.io web interface. For this, there are a few subcommands to manage a crate. cargo yank Occasions may arise where you publish a version of a crate that actually ends up being broken for one reason or another (syntax error, forgot to include a file, etc.). For situations such as this, Cargo supports a “yank” of a version of a crate. $ cargo yank --version 1.0.1 $ cargo yank --version 1.0.1 --undo A yank does not delete any code.

This feature is not intended for deleting accidentally uploaded secrets, for example. If that happens, you must reset those secrets immediately. The semantics of a yanked version are that no new dependencies can be created against that version, but all existing dependencies continue to work. One of the major goals of crates.io is to act as a permanent archive of crates that does not change over time, and allowing deletion of a version would go against this goal.

Essentially a yank means that all packages with a Cargo.lock will not break, while any future Cargo.lock files generated will not list the yanked version. cargo owner A crate is often developed by more than one person, or the primary maintainer may change over time! The owner of a crate is the only person allowed to publish new versions of the crate, but an owner may designate additional owners. $ cargo owner --add github-handle $ cargo owner --remove github-handle $ cargo owner --add github:rust-lang:owners $ cargo owner --remove github:rust-lang:owners The owner IDs given to these commands must be GitHub user names or GitHub teams.

If a user name is given to --add , that user is invited as a “named” owner, with full rights to the crate. In addition to being able to publish or yank versions of the crate, they have the ability to add or remove owners, including the owner that made them an owner. Needless to say, you shouldn’t make people you don’t fully trust into a named owner. In order to become a named owner, a user must have logged into crates.io previously.

If a team name is given to --add , that team is invited as a “team” owner, with restricted right to the crate. While they have permission to publish or yank versions of the crate, they do not have the ability to add or remove owners. In addition to being more convenient for managing groups of owners, teams are just a bit more secure against owners becoming malicious. The syntax for teams is currently github:org:team (see examples above).

In order to invite a team as an owner one must be a member of that team. No such restriction applies to removing a team as an owner. GitHub permissions Team membership is not something GitHub provides simple public access to, and it is likely for you to encounter the following message when working with them: It looks like you don’t have permission to query a necessary property from GitHub to complete this request. You may need to re-authenticate on crates.io to grant permission to read GitHub org memberships.

This is basically a catch-all for “you tried to query a team, and one of the five levels of membership access control denied this”. That is not an exaggeration. GitHub’s suppor

The rest of this page is on the live site.