cargo-publish

Perform checks, create a .crate file and upload it to the registry

$ cargo publish

$ cargo publish [[-n|--dry-run]]

$ cargo publish --registry [name]

cargo publish [OPTIONS]

--token TOKEN
    Specifies an API token to use for authentication to the registry. This overrides any saved token from cargo login.

--no-verify
    Skips verification of the crate's contents and integrity after packaging. This includes skipping the execution of tests before publishing. Use with caution.

--allow-dirty
    Allows publishing the crate even if the Git working directory contains uncommitted changes. By default, Cargo prevents publishing from a dirty directory.

--dry-run
    Performs all pre-flight checks, packaging, and validation steps without actually uploading the crate to the registry. Highly recommended for testing the publishing process.

--registry REGISTRY
    Specifies the name of the registry to publish to, overriding the default crates.io. The registry must be pre-configured in your .cargo/config.toml.

-p, --package SPEC
    Specifies the package to publish. This option is useful in a workspace with multiple packages; otherwise, it defaults to the current package.

--manifest-path PATH
    Specifies the path to the Cargo.toml file for the package being published.

cargo publish is the essential command used to upload a Rust package, also known as a crate, to a public or private package registry. By default, it targets crates.io, the official package registry for Rust. This action makes your crate available for other developers to discover and use as a dependency in their own Rust projects, fostering collaboration and code reuse within the Rust ecosystem.

Before the actual publication, cargo publish performs several critical pre-flight checks: it validates the package's metadata in Cargo.toml, ensures there are no uncommitted changes in your working directory (unless explicitly overridden), builds and tests the crate to verify its integrity, and then creates a source tarball (a .crate file). This tarball is then uploaded to the specified registry. Successful publication requires prior authentication, typically managed via the cargo login command or by providing a token directly.

Authentication Prerequisite: Requires prior authentication with the target registry using cargo login or by providing a token via the --token option.

Clean Working Directory: By default, the Git working directory must be clean (i.e., no uncommitted changes) to publish. Use --allow-dirty to bypass this check.

Crate Uniqueness & Immutability: The chosen crate name must be unique on the target registry. Once a specific version of a crate is published, it is immutable and cannot be modified or re-uploaded.

Metadata Requirements: Essential metadata fields in Cargo.toml such as description, license (or license-file), readme, repository, and homepage are highly recommended or, in some cases, required by registries like crates.io.

Dependency Availability: All transitive dependencies of your crate must also be published and available on the registry before your crate can be successfully published.

Before you can publish a crate to crates.io (the default registry), you must authenticate your machine. This is typically achieved by running the command cargo login <YOUR_API_TOKEN>, which securely stores your API token locally. This token grants Cargo the necessary permissions to upload packages on your behalf. Alternatively, the token can be provided directly via the --token argument for a single publication.

The publishing process is designed to ensure crate quality and integrity. Cargo first attempts to build the crate to verify it compiles. It then runs the crate's tests (unless --no-verify is specified). It also performs various sanity checks on your Cargo.toml metadata and ensures your working directory is clean (unless --allow-dirty is used). Finally, it packages your crate's source code into a gzipped tarball (.crate file) and uploads it to the registry. It's highly recommended to use --dry-run to test this entire workflow without actually uploading.

cargo publish is a core command within Cargo, the official Rust package manager. Cargo was developed alongside the Rust language to provide a robust and integrated build system and dependency manager. The ability to publish crates to crates.io has been fundamental since the early days of the Rust ecosystem, enabling the widespread sharing and reuse of libraries. The command's functionality has consistently evolved with Cargo, adding features like --dry-run for safe testing and enhanced validation checks to ensure the quality and integrity of published crates, reflecting the community's commitment to a stable and reliable package registry.

cargo login(1), cargo owner(1), cargo yank(1), cargo package(1), cargo build(1)