Skip to content
Tutorials Center
My learning

Topics

Rust Reference Β· Tools

cargo publish and cargo package

Reference for cargo package and cargo publish: required manifest fields, what is included in the .crate file, dry runs, yanking and crate name rules.

cargo package bundles your crate's source into a compressed .crate file and builds it in isolation to prove it works. cargo publish does the same and then uploads the archive to a registry, crates.io by default. A published version is permanent: it can be yanked (hidden from new dependency resolution) but never replaced or deleted.

Because of that permanence, always do a dry run first. This page is a read-only command reference; the examples model the naming and versioning rules in plain Rust.

Terminal
$ cargo publish --dry-run
$ cargo publish

Try it

Rust Crate name rules

Press Run (or Ctrl + Enter) to see the result here.

Program input Β· what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.

Rust Choosing the next version

Press Run (or Ctrl + Enter) to see the result here.

Program input Β· what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.

Syntax

Terminal
cargo package [options]
cargo publish [options]
Name Description
--dry-run Package and verify, but do not upload.
--list (cargo package) Print the files that would go into the archive.
--allow-dirty Permit uncommitted changes in the working tree.
--no-verify Skip the test build of the packaged crate (not recommended).
--registry name Publish to another registry configured in .cargo/config.toml.
--token API token; usually set once with cargo login.
-p name Pick a workspace member.

Manifest requirements: name, version, a description, a license (SPDX expression) or license-file, and no path-only dependencies (each needs a version).

Usage notes

  • Use cargo package --list to see exactly what ships. Keep it small with include/exclude in Cargo.toml; the archive limit on crates.io is 10 MB.
  • cargo yank --version 1.2.3 stops new projects from selecting that version; existing lock files still work. --undo reverses it.
  • The packaged crate is rebuilt from the archive; builds that rely on files outside the package directory fail here, not on your machine.
  • Follow semantic versioning. Tools like cargo semver-checks can detect accidental breaking changes before you publish.
  • Put rust-version in the manifest to state your minimum supported Rust version.
  • Publishing needs a verified email and an API token created on crates.io. Never commit the token.
  • Names are first come, first served and cannot be transferred automatically, so choose carefully.