Format:Rust crate
| Magic | 1F 8B (gzip) around tar |
|---|---|
| Extensions | .crate |
| On this wiki | Facts · Code · Notes · Topics |
The .crate file cargo package uploads to crates.io: a gzip-compressed tar with a single name-version/ directory containing the sources, a rewritten normalized Cargo.toml, the original as Cargo.toml.orig, Cargo.lock and .cargo_vcs_info.json; build.rs runs on the consumer's machine when the crate is built.
cargo package writes target/package/<name>-<version>.crate. Everything is inside one top-level directory <name>-<version>/ (tar entry paths are joined to it) and the gzip header stores the file name.
Contents
From src/ops/cargo_package/mod.rs in rust-lang/cargo:
- The source files selected by the include/exclude rules and git.
Cargo.toml: regenerated in normalized form (to_normalized_contents): path and git dependencies resolved, workspace inheritance expanded. The author's file is stored asCargo.toml.orig. Both names are reserved: a source tree that already containsCargo.toml.origor.cargo_vcs_info.jsonmakes packaging fail.Cargo.lock: generated and included (the packaging code skips a lock file found in the source list and adds a generated one when lockfile inclusion is on)..cargo_vcs_info.json: only when the package sits in a git repository; JSON of the form{"git": {"sha1": "<commit>", "dirty": true}, "path_in_vcs": "<subdir>"}, wheredirtyis omitted when false andpath_in_vcsis empty for the repository root. This gives the exact upstream commit a crate was built from: compare it with the repository to find unpublished differences.
Determinism
Gzip level is Compression::best() (9). File entries use tar HeaderMode::Deterministic; the generated files (Cargo.toml, Cargo.lock, .cargo_vcs_info.json) get mode 0644 and a fixed mtime of 1153704088 (2006-07-24 01:21:28 UTC). Hence crates have no meaningful timestamps for the generated files.
Where code runs
A file named build.rs at the package root (or the build key of the manifest) is compiled and executed by cargo just before building the package, on the machine that builds the crate. It can run any code, compile C sources and print cargo:: directives. Procedural macros (proc-macro = true crates) are also compiled and run inside the compiler during any build. Neither runs when the crate is merely downloaded or unpacked.
Registry side
The sparse and git registry index lists each version with cksum, the SHA-256 of the .crate file, which cargo verifies after download.
Code & repositories
- https://github.com/rust-lang/cargo @
3022244f7ba6d509b2db1fc65900f4bdda1d52a9· license: MIT OR Apache-2.0 (declared by the contributor; GitHub's detector did not recognize a license file)
Cargo: src/ops/cargo_package builds the .crate archive; reference docs on build scripts and registry index.
Tested on: source read, not run · checked 2026-10-19