A Cargo.toml is a TOML document.
This page lists every table and key that the Cargo Book’s manifest reference defines, in
the order a manifest usually gives them. Cargo ignores the metadata
tables, which are left for other tools.
Sources: The Cargo Book’s chapters
The Manifest Format,
Cargo Targets,
Specifying Dependencies,
Features,
Profiles,
Workspaces,
Dependency Resolution and
Overriding Dependencies;
the rustc book’s codegen options for split-debuginfo; the edition values
accepted by rustc --edition (Rust 1.95).
Top-level tables
| Key or table | Meaning |
|---|---|
cargo-features | Array of unstable, nightly-only features to turn on. Must come before every table. |
[package] | Defines the package; see package keys. Absent in a virtual manifest, which holds only [workspace]. |
[lib] | The library target; see targets. |
[[bin]] | Binary targets (an array of tables). |
[[example]] | Example targets. |
[[test]] | Integration test targets. |
[[bench]] | Benchmark targets. |
[dependencies] | Library dependencies; see dependencies. |
[dev-dependencies] | Dependencies used only by examples, tests and benchmarks. |
[build-dependencies] | Dependencies of the build script. |
[target] | Platform-specific dependency tables, e.g. [target.'cfg(windows)'.dependencies]. |
[badges] | Badges for a registry; only maintenance remains (see badges). |
[features] | Conditional compilation features; see features. |
[lints] | Lint levels for this package (Cargo 1.74 and later); see lints. |
[hints] | Hints for compiling the package (Cargo 1.90 and later). No hints are stable yet; Cargo may ignore any hint and warns about unknown ones. |
[patch] | Overrides dependencies with other sources; see patch and replace. |
[replace] | Overrides dependencies (deprecated; use [patch]). |
[profile] | Compiler settings per profile; see profiles. |
[workspace] | The workspace definition; see workspace. |
[package]
Only name is required by Cargo; crates.io also requires
description and either license or
license-file. Keys marked “inheritable” may be written
key.workspace = true to take the value from
[workspace.package].
| Key | Type | Default | Meaning |
|---|---|---|---|
name | string | required | Package name: letters, digits, - and _, not empty. |
version | string | 0.0.0 | SemVer version: MAJOR.MINOR.PATCH, optional -pre and +build. Needed to publish. Inheritable. |
authors | array of strings | none | Deprecated list of authors. Inheritable. |
edition | string | "2015" | Rust edition: "2015", "2018", "2021" or "2024". cargo new currently writes 2024. Inheritable. |
rust-version | string | none | Minimum supported Rust version, e.g. "1.74". Inheritable. |
description | string | none | Short plain-text description. Inheritable. |
documentation | URL | none | Where the crate’s documentation is hosted. Inheritable. |
readme | path or boolean | README.md, README.txt or README if present | Path to the readme, relative to the manifest; false turns the default off, true means README.md. Inheritable. |
homepage | URL | none | The package’s home page. Inheritable. |
repository | URL | none | The source repository. Inheritable. |
license | string | none | Licence; crates.io reads it as an SPDX 2.3 expression (AND, OR, WITH) of names from SPDX licence list 3.20, e.g. "MIT OR Apache-2.0". Inheritable. |
license-file | path | none | File holding a non-standard licence text. Inheritable. |
keywords | array of strings | none | Search words; crates.io takes at most 5, ASCII, at most 20 characters each. Inheritable. |
categories | array of strings | none | crates.io category slugs, at most 5, matched exactly. Inheritable. |
workspace | path | found by searching upwards | The workspace root this package belongs to. Not allowed in a manifest that has [workspace]. |
build | path or false | "build.rs" if present | The build script; false turns detection off. |
links | string | none | Name of the native library this package links, e.g. "git2" for libgit2. |
exclude | array of patterns | none | gitignore-style patterns left out when packaging. Inheritable. |
include | array of patterns | none | Patterns that are the only files packaged; overrides exclude. Inheritable. |
publish | array of registry names, or false | not stated | Registries the package may be published to; false forbids publishing; with one registry listed, cargo publish uses it by default. Inheritable. |
metadata | table | none | Ignored by Cargo; for other tools. |
default-run | string | none | Binary that cargo run runs when there are several. |
autolib | boolean | true from edition 2018 | false turns off library auto-discovery (src/lib.rs; Rust 1.83). In edition 2015 every auto* key defaults to false once any target is declared by hand. |
autobins | boolean | true | false turns off binary auto-discovery (src/main.rs, src/bin/). |
autoexamples | boolean | true | false turns off example discovery (examples/). |
autotests | boolean | true | false turns off test discovery (tests/). |
autobenches | boolean | true | false turns off benchmark discovery (benches/). |
resolver | string | from the edition | Resolver version, for the whole workspace (only the top-level package’s value counts): "1" (the general default), "2" (default with edition 2021; changes feature unification), "3" (default with edition 2024, Rust 1.84 or later; changes the default of resolver.incompatible-rust-versions from allow to fallback). |
Targets
[lib] is a single table; [[bin]], [[example]],
[[test]] and [[bench]] are arrays of tables, one per target.
Targets are also found automatically from the standard layout unless the
auto* keys turn that off.
| Key | Default | Meaning |
|---|---|---|
name | library: package name with - turned into _; default binary: package name; discovered targets: file or folder name | Name of the target and its output file. Required on every target except [lib]. |
path | inferred from the name | Source file of the crate root, relative to the manifest. |
test | true for lib, bins and tests | Whether cargo test tests it by default. |
doctest | true for the library | Whether documentation examples are tested. Libraries only. |
bench | true for lib, bins and benchmarks | Whether cargo bench benchmarks it by default. |
doc | true for libraries and binaries | Whether cargo doc documents it by default. |
plugin | none | Deprecated and unused. |
proc-macro | false | The library is a procedural macro. [lib] only. |
harness | true | Build with libtest’s harness (--test); with false the target supplies its own main. |
crate-type | ["lib"]; proc macros ["proc-macro"]; examples ["bin"] | Output kinds, an array of bin, lib, rlib, dylib, cdylib, staticlib, proc-macro. Libraries and examples only. |
required-features | [] | Features that must be on for the target to be built; otherwise it is skipped. Not for [lib]. |
edition | the package’s edition | Edition for this target only. Deprecated. |
Dependencies
Each entry in [dependencies], [dev-dependencies] or
[build-dependencies] maps a name to either a version requirement string
(rand = "0.8") or an inline table with these keys. The same tables may
sit under [target.'cfg(…)'.…] or [target.<triple>.…]
to apply on one platform only; cfg expressions combine with
not, any and all.
| Key | Meaning |
|---|---|
version | Version requirement (below). With git or path it is checked against that copy and used when publishing. |
registry | Name of a registry set up in .cargo/config.toml, instead of crates.io. |
git | URL of a Git repository holding the crate. |
branch | Git branch to follow. |
tag | Git tag to use. |
rev | Git commit hash or other named ref (e.g. refs/pull/493/head). |
path | Local folder holding the crate’s Cargo.toml. |
package | Real package name, when the key is a local alias. |
optional | true: only built when a feature turns it on. |
default-features | false: leave out the dependency’s default feature. |
features | Array of the dependency’s features to turn on. |
workspace | true: take the entry from [workspace.dependencies] Only optional, features (added to the workspace’s) and, in edition 2024 with Rust 1.99 or later, default-features may be given beside it; [workspace.dependencies] itself may not set optional. |
Version requirements
| Form | Example | Means |
|---|---|---|
| Default (caret) | 1.2.3 or ^1.2.3 | >=1.2.3, <2.0.0; updates within the left-most non-zero part, so 0.2.3 is >=0.2.3, <0.3.0 and 0.0.3 is >=0.0.3, <0.0.4. |
| Tilde | ~1.2.3 | >=1.2.3, <1.3.0; ~1 is >=1.0.0, <2.0.0. |
| Wildcard | 1.2.* | >=1.2.0, <1.3.0; crates.io refuses a bare *. |
| Comparison | >= 1.2.0, >, <, <=, = 1.2.3 | Explicit bounds or an exact version. |
| Multiple | >= 1.2, < 1.5 | Comma-separated; every one must hold. |
[features]
Each key names a feature; its value is an array of what turning it on also turns on.
All features are off unless enabled; the feature named default is enabled
when the package is built, unless --no-default-features or
default-features = false turns it off. An optional dependency
implicitly defines a feature of the same name (gif = ["dep:gif"])
unless dep: names it anywhere in the table. Feature names may use Unicode
XID characters, may start with _ or a digit, and may contain
-, + and . after the first character;
crates.io allows only ASCII letters, digits, _, - and
+. dep: and ? need Rust 1.60 or later.
| Entry | Meaning |
|---|---|
"other" | Turn on another feature of this package. |
"dep:name" | Turn on the optional dependency name without making a feature of that name. |
"name/feat" | Turn on feature feat of dependency name (and the dependency itself, if optional). |
"name?/feat" | Turn on feat of name only if something else turns name on. |
[lints]
One sub-table per tool, named by the part of the lint name before ::
(a name without :: belongs to rust), such as
[lints.rust], [lints.clippy] and
[lints.cargo]. Each key is a lint or lint group name and the value a
level, or a table { level, priority }. Workspace members can inherit
[workspace.lints]. Lints apply to this package only, not to its
dependencies.
| Key | Values |
|---|---|
level | "forbid", "deny", "warn", "allow". x = "forbid" is short for x = { level = "forbid", priority = 0 }. |
priority | Signed integer; higher values override lower ones, so a group can be set at a low priority and single lints over it. |
[profile.*]
Built-in profiles are dev, release, test and
bench; test inherits dev and bench
inherits release. A custom profile must name the one it extends with
inherits. Profiles are read only from the workspace root’s manifest.
| Key | Values | dev | release |
|---|---|---|---|
opt-level | 0, 1, 2, 3, "s" (size), "z" (size, no loop vectorisation) | 0 | 3 |
debug | 0/false/"none", "line-directives-only", "line-tables-only", 1/"limited", 2/true/"full" | full | none |
split-debuginfo | passed to rustc: "off" (debug info in the binary; default for ELF and windows-gnu), "packed" (one separate file: .pdb, .dSYM or .dwp; default for Windows MSVC and macOS in rustc), "unpacked" (per object file, e.g. .dwo) | platform-specific; Cargo uses "unpacked" on macOS when debug info is on | |
strip | "none", "debuginfo", "symbols"; true = symbols, false = none | "none" | "none" |
debug-assertions | boolean | true | false |
overflow-checks | boolean | true | false |
lto | false (thin local LTO), true/"fat", "thin", "off" | false | false |
panic | "unwind", "abort" | "unwind" | "unwind" |
incremental | boolean | true | false |
codegen-units | integer above 0 | 256 | 16 |
rpath | boolean | false | false |
inherits | profile name | custom profiles only | |
Overrides, first match wins: [profile.dev.package.foo] (one package, or
"foo:2.1.0" for one version), [profile.dev.package."*"]
(every package that is not a workspace member),
[profile.dev.build-override] (build scripts, proc macros and their
dependencies), then [profile.dev], then the built-in defaults. Overrides
cannot set panic, lto or rpath.
[workspace]
| Key | Meaning |
|---|---|
resolver | Resolver version (as in [package]); required in a virtual manifest, which has no edition to infer it from. |
members | Array of member package folders; globs * and ? allowed. |
exclude | Folders that are not members. |
default-members | Members acted on when no -p or --workspace is given at the root. |
package | Values members inherit: authors, categories, description, documentation, edition, exclude, homepage, include, keywords, license, license-file, publish, readme, repository, rust-version, version. license-file and readme are relative to the workspace root. |
dependencies | Dependency entries members inherit with workspace = true. |
lints | Lint tables members inherit with [lints] workspace = true. |
metadata | Ignored by Cargo; for other tools. |
[patch] and [replace]
Each key after [patch] is the URL of the source being patched or the
name of a registry, crates-io for the default registry:
[patch.crates-io], [patch.'https://github.com/example/baz'].
It holds dependency entries (same keys as above) that replace that source’s crates.
Cargo reads patches only from the workspace root’s manifest.
[replace] is deprecated in favour of [patch]. Each key is a
package ID specification with the full three-part version, such as
"foo:0.1.0", and the value a dependency entry (for example
git or path) without features; the replacement must have
the same name and version. It too is read only at the workspace root.
[badges]
Only maintenance = { status = "…" } remains documented, with status
actively-developed, passively-maintained, as-is,
experimental, looking-for-maintainer,
deprecated or none. crates.io no longer shows badges.