Before publishing a Rust crate, what does `cargo package` check, and how can an `exclude` entry make its verify build fail?
answer
- the tarball, not your checkout
- target/package and --list
- path dependencies need a version
- include overrides exclude
basics
~20 scargo package checks the manifest, builds a .crate from the files include/exclude select, then extracts and compiles that tarball. If exclude drops a file the code reads at compile time, such as an include_str! fixture, the verify build fails.
solid answer
~40 s`cargo package` first checks the manifest: every non-dev dependency needs a `version` (a `path` alone is rejected, since the path is removed from the published manifest), and missing metadata such as `description` or `license` draws a warning. It then writes `target/package/NAME-VERSION.crate` containing a normalized `Cargo.toml`, the original as `Cargo.toml.orig`, a `Cargo.lock`, and the files that `include` or `exclude` select (version-control ignore rules apply when `include` is not set). Finally it extracts the tarball and builds it from scratch. A build that passes in your checkout can fail here: if `exclude = ["tests/fixtures/"]` drops a file that `include_str!` reads, the extracted copy cannot compile. `cargo package --list` shows what ships; `--no-verify` skips the build and hides the problem.
code
toml · 9 lines[package]
name = "quantile-sketch"
version = "2.1.0"
edition = "2024"
description = "Streaming quantile estimates for latency metrics"
license = "MIT OR Apache-2.0"
exclude = ["data/", "tests/fixtures/"]
[dependencies]go deeper
Recall that cargo package builds the .crate under target/package and that --list shows its files.
Explain the stages: manifest checks, the normalized Cargo.toml and Cargo.toml.orig, the always-included Cargo.lock, include and exclude rules, then a build from the extracted tarball.
Diagnose a verify failure as a file missing from the tarball, fix the include or exclude pattern, and refuse --no-verify as a workaround.
Make cargo package part of every pull request on a published crate so packaging mistakes surface before release day, not after a permanent upload.
## What `cargo package` is for **`cargo package`** assembles the exact artifact a registry would receive: a compressed **`.crate`** tarball, written to `target/package/`. `cargo publish` runs the same steps before uploading, so `cargo package` (or `cargo publish --dry-run`) is the rehearsal a maintainer runs before releasing 2.1.0 of `quantile-sketch`. It runs in stages: 1. **Load and check** the package. Dependencies with only a `path` are rejected, because Cargo removes the `path` key from published manifests; each needs a `version` too. `[dev-dependencies]` are exempt. A package with no `version` field cannot be published either. 2. **Create the `.crate`**: - `Cargo.toml` is rewritten and normalized, with `[patch]`, `[replace]` and `[workspace]` removed; your original is kept as `Cargo.toml.orig`; - `Cargo.lock` is always included (generated if missing); - `.cargo_vcs_info.json` records the commit hash and whether the worktree was dirty, when the package is in version control; - symlinks are flattened, and files are chosen by `include` and `exclude`. 3. **Verify**: extract the `.crate` and build it from a pristine state. `--no-verify` skips this. 4. **Check** that build scripts did not modify any source files. Cargo also warns when human-facing metadata is missing (`description`, `license` or `license-file`, `documentation`, `homepage`, `repository`); `--no-metadata` silences that. The warning is advisory, but crates.io itself refuses a package without `description` and a `license` or `license-file`. ## Choosing the files: `include` and `exclude` With neither key, Cargo packages every file in the package root, minus files your version-control system ignores (or hidden dot-files when the package is not in a repository). Some rules always apply: subdirectories containing their own `Cargo.toml` and a root `target` directory are skipped, and the manifest, the lockfile and any `license-file` are always included. | Key | Meaning | Pattern style | |---|---|---| | `exclude` | drop matching files from the default set | gitignore-style, e.g. `"/data"`, `"tests/fixtures/"` | | `include` | package only matching files; version-control ignore rules no longer apply | gitignore-style, with `!` to carve exceptions | | both set | `include` wins, and Cargo warns "the exclude list will be ignored" | use `!` inside `include` instead | These are worth tuning: crates.io limits a `.crate` to 10 MB, and test data, recordings or generated docs are the usual reason a crate ships megabytes it never needs. `cargo package --list` prints the file list without building anything. ## How `exclude` breaks the verify build The verify step compiles the **tarball**, not your checkout. Any file that compilation reads must therefore be inside it. Typical compile-time reads are `include_str!` and `include_bytes!`, `#[path]` modules, files a build script opens, and doctests that include a file. Suppose the maintainer wants to keep a 300 KB replay file and some fixtures out of the crate and writes `exclude = ["data/", "tests/fixtures/"]`. The library embeds a sample with `include_str!("../tests/fixtures/latencies.txt")`. `cargo build` in the repository succeeds, because the file is on disk. `cargo package` packs five files, then the verify build fails with "couldn't read `src/../tests/fixtures/latencies.txt`" and "failed to verify package tarball". The fix is to exclude only what is truly unused (`exclude = ["/data"]`) or to move the embedded file under `src/`. Reaching for `--no-verify` instead would publish a crate that cannot compile for anyone, and because published versions are permanent, that broken version would stay in the registry. ## A pre-release checklist - `cargo package --list`: does the file list contain what the build needs and nothing large it does not? - `cargo package`: do the metadata warnings matter for your registry, and does the verify build pass? - Check that every path dependency also has a `version` (and a `registry` key if it lives outside crates.io). - Inspect `target/package/*.crate` size before uploading. ## Version control checks When the package lives in a git repository, Cargo refuses to package a working tree with **uncommitted changes** unless you pass `--allow-dirty`, so that the tarball matches a real commit. The commit hash goes into `.cargo_vcs_info.json`, with a `dirty` flag and the package's path inside the repository. Two limits are worth knowing: - the file is a best-effort snapshot, and Cargo states that the provenance is **not verified**: nothing guarantees the tarball matches that commit; - with `include` set, ignore rules from version control stop applying, so a generated file that `.gitignore` used to keep out can slip into the package. Both are reasons to read `cargo package --list` on every release, not only the first.
- Why does `cargo package` reject `sketch-core = { path = "../sketch-core" }`?The published manifest drops `path`, so the dependency must say which registry version to use. Cargo stops with "all dependencies must have a version requirement specified when packaging". Add `version = "0.1"` (and `registry = "..."` if it is not on crates.io); `--no-verify` does not bypass this check, and dev-dependencies are exempt.
- What is `Cargo.toml.orig` in a packaged crate?It is your manifest exactly as written. The `Cargo.toml` inside the `.crate` is a normalized rewrite: workspace inheritance resolved, `[patch]`, `[replace]` and `[workspace]` removed, and `path` keys stripped from dependencies, so registry users build against registry versions.
- If cargo build passes in the repo, the published crate will build
- exclude and include can be combined, with exclude applied last
- --no-verify is a safe fix for a failing verify step
- A path dependency is published along with the crate
- The missing-metadata warning means crates.io will accept it anyway