3 The `Cargo.toml` file for each package is called its *manifest*. It is written
4 in the [TOML] format. It contains metadata that is needed to compile the package. Checkout
5 the `cargo locate-project` section for more detail on how cargo finds the manifest file.
7 Every manifest file consists of the following sections:
9 * [`cargo-features`](unstable.md) --- Unstable, nightly-only features.
10 * [`[package]`](#the-package-section) --- Defines a package.
11 * [`name`](#the-name-field) --- The name of the package.
12 * [`version`](#the-version-field) --- The version of the package.
13 * [`authors`](#the-authors-field) --- The authors of the package.
14 * [`edition`](#the-edition-field) --- The Rust edition.
15 * [`rust-version`](#the-rust-version-field) --- The minimal supported Rust version.
16 * [`description`](#the-description-field) --- A description of the package.
17 * [`documentation`](#the-documentation-field) --- URL of the package documentation.
18 * [`readme`](#the-readme-field) --- Path to the package's README file.
19 * [`homepage`](#the-homepage-field) --- URL of the package homepage.
20 * [`repository`](#the-repository-field) --- URL of the package source repository.
21 * [`license`](#the-license-and-license-file-fields) --- The package license.
22 * [`license-file`](#the-license-and-license-file-fields) --- Path to the text of the license.
23 * [`keywords`](#the-keywords-field) --- Keywords for the package.
24 * [`categories`](#the-categories-field) --- Categories of the package.
25 * [`workspace`](#the-workspace-field) --- Path to the workspace for the package.
26 * [`build`](#the-build-field) --- Path to the package build script.
27 * [`links`](#the-links-field) --- Name of the native library the package links with.
28 * [`exclude`](#the-exclude-and-include-fields) --- Files to exclude when publishing.
29 * [`include`](#the-exclude-and-include-fields) --- Files to include when publishing.
30 * [`publish`](#the-publish-field) --- Can be used to prevent publishing the package.
31 * [`metadata`](#the-metadata-table) --- Extra settings for external tools.
32 * [`default-run`](#the-default-run-field) --- The default binary to run by [`cargo run`].
33 * [`autobins`](cargo-targets.md#target-auto-discovery) --- Disables binary auto discovery.
34 * [`autoexamples`](cargo-targets.md#target-auto-discovery) --- Disables example auto discovery.
35 * [`autotests`](cargo-targets.md#target-auto-discovery) --- Disables test auto discovery.
36 * [`autobenches`](cargo-targets.md#target-auto-discovery) --- Disables bench auto discovery.
37 * [`resolver`](resolver.md#resolver-versions) --- Sets the dependency resolver to use.
38 * Target tables: (see [configuration](cargo-targets.md#configuring-a-target) for settings)
39 * [`[lib]`](cargo-targets.md#library) --- Library target settings.
40 * [`[[bin]]`](cargo-targets.md#binaries) --- Binary target settings.
41 * [`[[example]]`](cargo-targets.md#examples) --- Example target settings.
42 * [`[[test]]`](cargo-targets.md#tests) --- Test target settings.
43 * [`[[bench]]`](cargo-targets.md#benchmarks) --- Benchmark target settings.
45 * [`[dependencies]`](specifying-dependencies.md) --- Package library dependencies.
46 * [`[dev-dependencies]`](specifying-dependencies.md#development-dependencies) --- Dependencies for examples, tests, and benchmarks.
47 * [`[build-dependencies]`](specifying-dependencies.md#build-dependencies) --- Dependencies for build scripts.
48 * [`[target]`](specifying-dependencies.md#platform-specific-dependencies) --- Platform-specific dependencies.
49 * [`[badges]`](#the-badges-section) --- Badges to display on a registry.
50 * [`[features]`](features.md) --- Conditional compilation features.
51 * [`[patch]`](overriding-dependencies.md#the-patch-section) --- Override dependencies.
52 * [`[replace]`](overriding-dependencies.md#the-replace-section) --- Override dependencies (deprecated).
53 * [`[profile]`](profiles.md) --- Compiler settings and optimizations.
54 * [`[workspace]`](workspaces.md) --- The workspace definition.
56 <a id="package-metadata"></a>
57 ### The `[package]` section
59 The first section in a `Cargo.toml` is `[package]`.
63 name = "hello_world" # the name of the package
64 version = "0.1.0" # the current version, obeying semver
65 authors = ["Alice <a@example.com>", "Bob <b@example.com>"]
68 The only fields required by Cargo are [`name`](#the-name-field) and
69 [`version`](#the-version-field). If publishing to a registry, the registry may
70 require additional fields. See the notes below and [the publishing
71 chapter][publishing] for requirements for publishing to [crates.io].
75 The package name is an identifier used to refer to the package. It is used
76 when listed as a dependency in another package, and as the default name of
77 inferred lib and bin targets.
79 The name must use only [alphanumeric] characters or `-` or `_`, and cannot be empty.
81 Note that [`cargo new`] and [`cargo init`] impose some additional restrictions on
82 the package name, such as enforcing that it is a valid Rust identifier and not
83 a keyword. [crates.io] imposes even more restrictions, such as:
85 - Only ASCII characters are allowed.
86 - Do not use reserved names.
87 - Do not use special Windows names such as "nul".
88 - Use a maximum of 64 characters of length.
90 [alphanumeric]: ../../std/primitive.char.html#method.is_alphanumeric
92 #### The `version` field
94 Cargo bakes in the concept of [Semantic
95 Versioning](https://semver.org/), so make sure you follow some basic rules:
97 * Before you reach 1.0.0, anything goes, but if you make breaking changes,
98 increment the minor version. In Rust, breaking changes include adding fields to
99 structs or variants to enums.
100 * After 1.0.0, only make breaking changes when you increment the major version.
101 Don’t break the build.
102 * After 1.0.0, don’t add any new public API (no new `pub` anything) in patch-level
103 versions. Always increment the minor version if you add any new `pub` structs,
104 traits, fields, types, functions, methods or anything else.
105 * Use version numbers with three numeric parts such as 1.0.0 rather than 1.0.
107 See the [Resolver] chapter for more information on how Cargo uses versions to
108 resolve dependencies, and for guidelines on setting your own version. See the
109 [SemVer compatibility] chapter for more details on exactly what constitutes a
112 [Resolver]: resolver.md
113 [SemVer compatibility]: semver.md
115 <a id="the-authors-field-optional"></a>
116 #### The `authors` field
118 The optional `authors` field lists in an array the people or organizations that are considered
119 the "authors" of the package. The exact meaning is open to interpretation --- it
120 may list the original or primary authors, current maintainers, or owners of the
121 package. An optional email address may be included within angled brackets at
122 the end of each author entry.
127 authors = ["Graydon Hoare", "Fnu Lnu <no-reply@rust-lang.org>"]
130 This field is only surfaced in package metadata and in the `CARGO_PKG_AUTHORS`
131 environment variable within `build.rs`. It is not displayed in the [crates.io]
134 > **Warning**: Package manifests cannot be changed once published, so this
135 > field cannot be changed or removed in already-published versions of a
138 <a id="the-edition-field-optional"></a>
139 #### The `edition` field
141 The `edition` key is an optional key that affects which [Rust Edition] your package
142 is compiled with. Setting the `edition` key in `[package]` will affect all
143 targets/crates in the package, including test suites, benchmarks, binaries,
152 Most manifests have the `edition` field filled in automatically by [`cargo new`]
153 with the latest stable edition. By default `cargo new` creates a manifest with
154 the 2021 edition currently.
156 If the `edition` field is not present in `Cargo.toml`, then the 2015 edition is
157 assumed for backwards compatibility. Note that all manifests
158 created with [`cargo new`] will not use this historical fallback because they
159 will have `edition` explicitly specified to a newer value.
161 #### The `rust-version` field
163 The `rust-version` field is an optional key that tells cargo what version of the
164 Rust language and compiler your package can be compiled with. If the currently
165 selected version of the Rust compiler is older than the stated version, cargo
166 will exit with an error, telling the user what version is required.
168 The first version of Cargo that supports this field was released with Rust 1.56.0.
169 In older releases, the field will be ignored, and Cargo will display a warning.
174 rust-version = "1.56"
177 The Rust version must be a bare version number with two or three components; it
178 cannot include semver operators or pre-release identifiers. Compiler pre-release
179 identifiers such as -nightly will be ignored while checking the Rust version.
180 The `rust-version` must be equal to or newer than the version that first
181 introduced the configured `edition`.
183 The `rust-version` may be ignored using the `--ignore-rust-version` option.
185 Setting the `rust-version` key in `[package]` will affect all targets/crates in
186 the package, including test suites, benchmarks, binaries, examples, etc.
188 #### The `description` field
190 The description is a short blurb about the package. [crates.io] will display
191 this with your package. This should be plain text (not Markdown).
196 description = "A short description of my package"
199 > **Note**: [crates.io] requires the `description` to be set.
201 <a id="the-documentation-field-optional"></a>
202 #### The `documentation` field
204 The `documentation` field specifies a URL to a website hosting the crate's
205 documentation. If no URL is specified in the manifest file, [crates.io] will
206 automatically link your crate to the corresponding [docs.rs] page.
211 documentation = "https://docs.rs/bitflags"
214 #### The `readme` field
216 The `readme` field should be the path to a file in the package root (relative
217 to this `Cargo.toml`) that contains general information about the package.
218 This file will be transferred to the registry when you publish. [crates.io]
219 will interpret it as Markdown and render it on the crate's page.
227 If no value is specified for this field, and a file named `README.md`,
228 `README.txt` or `README` exists in the package root, then the name of that
229 file will be used. You can suppress this behavior by setting this field to
230 `false`. If the field is set to `true`, a default value of `README.md` will
233 #### The `homepage` field
235 The `homepage` field should be a URL to a site that is the home page for your
241 homepage = "https://serde.rs/"
244 #### The `repository` field
246 The `repository` field should be a URL to the source repository for your
252 repository = "https://github.com/rust-lang/cargo/"
255 #### The `license` and `license-file` fields
257 The `license` field contains the name of the software license that the package
258 is released under. The `license-file` field contains the path to a file
259 containing the text of the license (relative to this `Cargo.toml`).
261 [crates.io] interprets the `license` field as an [SPDX 2.1 license
262 expression][spdx-2.1-license-expressions]. The name must be a known license
263 from the [SPDX license list 3.11][spdx-license-list-3.11]. Parentheses are not
264 currently supported. See the [SPDX site] for more information.
266 SPDX license expressions support AND and OR operators to combine multiple
272 license = "MIT OR Apache-2.0"
275 Using `OR` indicates the user may choose either license. Using `AND` indicates
276 the user must comply with both licenses simultaneously. The `WITH` operator
277 indicates a license with a special exception. Some examples:
279 * `MIT OR Apache-2.0`
280 * `LGPL-2.1-only AND MIT AND BSD-2-Clause`
281 * `GPL-2.0-or-later WITH Bison-exception-2.2`
283 If a package is using a nonstandard license, then the `license-file` field may
284 be specified in lieu of the `license` field.
289 license-file = "LICENSE.txt"
292 > **Note**: [crates.io] requires either `license` or `license-file` to be set.
294 [^slash]: Previously multiple licenses could be separated with a `/`, but that
297 #### The `keywords` field
299 The `keywords` field is an array of strings that describe this package. This
300 can help when searching for the package on a registry, and you may choose any
301 words that would help someone find this crate.
306 keywords = ["gamedev", "graphics"]
309 > **Note**: [crates.io] has a maximum of 5 keywords. Each keyword must be
310 > ASCII text, start with a letter, and only contain letters, numbers, `_` or
311 > `-`, and have at most 20 characters.
313 #### The `categories` field
315 The `categories` field is an array of strings of the categories this package
319 categories = ["command-line-utilities", "development-tools::cargo-plugins"]
322 > **Note**: [crates.io] has a maximum of 5 categories. Each category should
323 > match one of the strings available at <https://crates.io/category_slugs>, and
324 > must match exactly.
326 <a id="the-workspace--field-optional"></a>
327 #### The `workspace` field
329 The `workspace` field can be used to configure the workspace that this package
330 will be a member of. If not specified this will be inferred as the first
331 Cargo.toml with `[workspace]` upwards in the filesystem. Setting this is
332 useful if the member is not inside a subdirectory of the workspace root.
337 workspace = "path/to/workspace/root"
340 This field cannot be specified if the manifest already has a `[workspace]`
341 table defined. That is, a crate cannot both be a root crate in a workspace
342 (contain `[workspace]`) and also be a member crate of another workspace
343 (contain `package.workspace`).
345 For more information, see the [workspaces chapter](workspaces.md).
347 <a id="package-build"></a>
348 <a id="the-build-field-optional"></a>
349 #### The `build` field
351 The `build` field specifies a file in the package root which is a [build
352 script] for building native code. More information can be found in the [build
353 script guide][build script].
355 [build script]: build-scripts.md
363 The default is `"build.rs"`, which loads the script from a file named
364 `build.rs` in the root of the package. Use `build = "custom_build_name.rs"` to
365 specify a path to a different file or `build = false` to disable automatic
366 detection of the build script.
368 <a id="the-links-field-optional"></a>
369 #### The `links` field
371 The `links` field specifies the name of a native library that is being linked
372 to. More information can be found in the [`links`][links] section of the build
375 [links]: build-scripts.md#the-links-manifest-key
377 For example, a crate that links a native library called "git2" (e.g. `libgit2.a`
378 on Linux) may specify:
386 <a id="the-exclude-and-include-fields-optional"></a>
387 #### The `exclude` and `include` fields
389 The `exclude` and `include` fields can be used to explicitly specify which
390 files are included when packaging a project to be [published][publishing],
391 and certain kinds of change tracking (described below).
392 The patterns specified in the `exclude` field identify a set of files that are
393 not included, and the patterns in `include` specify files that are explicitly
395 You may run [`cargo package --list`][`cargo package`] to verify which files will
396 be included in the package.
401 exclude = ["/ci", "images/", ".*"]
407 include = ["/src", "COPYRIGHT", "/examples", "!/examples/big_example"]
410 The default if neither field is specified is to include all files from the
411 root of the package, except for the exclusions listed below.
413 If `include` is not specified, then the following files will be excluded:
415 * If the package is not in a git repository, all "hidden" files starting with
416 a dot will be skipped.
417 * If the package is in a git repository, any files that are ignored by the
418 [gitignore] rules of the repository and global git configuration will be
421 Regardless of whether `exclude` or `include` is specified, the following files
424 * Any sub-packages will be skipped (any subdirectory that contains a
426 * A directory named `target` in the root of the package will be skipped.
428 The following files are always included:
430 * The `Cargo.toml` file of the package itself is always included, it does not
431 need to be listed in `include`.
432 * A minimized `Cargo.lock` is automatically included if the package contains a
433 binary or example target, see [`cargo package`] for more information.
434 * If a [`license-file`](#the-license-and-license-file-fields) is specified, it
437 The options are mutually exclusive; setting `include` will override an
438 `exclude`. If you need to have exclusions to a set of `include` files, use the
439 `!` operator described below.
441 The patterns should be [gitignore]-style patterns. Briefly:
443 - `foo` matches any file or directory with the name `foo` anywhere in the
444 package. This is equivalent to the pattern `**/foo`.
445 - `/foo` matches any file or directory with the name `foo` only in the root of
447 - `foo/` matches any *directory* with the name `foo` anywhere in the package.
448 - Common glob patterns like `*`, `?`, and `[]` are supported:
449 - `*` matches zero or more characters except `/`. For example, `*.html`
450 matches any file or directory with the `.html` extension anywhere in the
452 - `?` matches any character except `/`. For example, `foo?` matches `food`,
454 - `[]` allows for matching a range of characters. For example, `[ab]`
455 matches either `a` or `b`. `[a-z]` matches letters a through z.
456 - `**/` prefix matches in any directory. For example, `**/foo/bar` matches the
457 file or directory `bar` anywhere that is directly under directory `foo`.
458 - `/**` suffix matches everything inside. For example, `foo/**` matches all
459 files inside directory `foo`, including all files in subdirectories below
461 - `/**/` matches zero or more directories. For example, `a/**/b` matches
462 `a/b`, `a/x/b`, `a/x/y/b`, and so on.
463 - `!` prefix negates a pattern. For example, a pattern of `src/*.rs` and
464 `!foo.rs` would match all files with the `.rs` extension inside the `src`
465 directory, except for any file named `foo.rs`.
467 The include/exclude list is also used for change tracking in some situations.
468 For targets built with `rustdoc`, it is used to determine the list of files to
469 track to determine if the target should be rebuilt. If the package has a
470 [build script] that does not emit any `rerun-if-*` directives, then the
471 include/exclude list is used for tracking if the build script should be re-run
472 if any of those files change.
474 [gitignore]: https://git-scm.com/docs/gitignore
476 <a id="the-publish--field-optional"></a>
477 #### The `publish` field
479 The `publish` field can be used to prevent a package from being published to a
480 package registry (like *crates.io*) by mistake, for instance to keep a package
481 private in a company.
489 The value may also be an array of strings which are registry names that are
490 allowed to be published to.
495 publish = ["some-registry-name"]
498 If publish array contains a single registry, `cargo publish` command will use
499 it when `--registry` flag is not specified.
501 <a id="the-metadata-table-optional"></a>
502 #### The `metadata` table
504 Cargo by default will warn about unused keys in `Cargo.toml` to assist in
505 detecting typos and such. The `package.metadata` table, however, is completely
506 ignored by Cargo and will not be warned about. This section can be used for
507 tools which would like to store package configuration in `Cargo.toml`. For
515 # Metadata used when generating an Android APK, for example.
516 [package.metadata.android]
517 package-name = "my-awesome-android-app"
518 assets = "path/to/static"
521 There is a similar table at the workspace level at
522 [`workspace.metadata`][workspace-metadata]. While cargo does not specify a
523 format for the content of either of these tables, it is suggested that
524 external tools may wish to use them in a consistent fashion, such as referring
525 to the data in `workspace.metadata` if data is missing from `package.metadata`,
526 if that makes sense for the tool in question.
528 [workspace-metadata]: workspaces.md#the-metadata-table
530 #### The `default-run` field
532 The `default-run` field in the `[package]` section of the manifest can be used
533 to specify a default binary picked by [`cargo run`]. For example, when there is
534 both `src/bin/a.rs` and `src/bin/b.rs`:
541 ### The `[badges]` section
543 The `[badges]` section is for specifying status badges that can be displayed
544 on a registry website when the package is published.
546 > Note: [crates.io] previously displayed badges next to a crate on its
547 > website, but that functionality has been removed. Packages should place
548 > badges in its README file which will be displayed on [crates.io] (see [the
549 > `readme` field](#the-readme-field)).
553 # The `maintenance` table indicates the status of the maintenance of
554 # the crate. This may be used by a registry, but is currently not
555 # used by crates.io. See https://github.com/rust-lang/crates.io/issues/2437
556 # and https://github.com/rust-lang/crates.io/issues/2438 for more details.
558 # The `status` field is required. Available options are:
559 # - `actively-developed`: New features are being added and bugs are being fixed.
560 # - `passively-maintained`: There are no plans for new features, but the maintainer intends to
561 # respond to issues that get filed.
562 # - `as-is`: The crate is feature complete, the maintainer does not intend to continue working on
563 # it or providing support, but it works for the purposes it was designed for.
564 # - `experimental`: The author wants to share it with the community but is not intending to meet
565 # anyone's particular use case.
566 # - `looking-for-maintainer`: The current maintainer would like to transfer the crate to someone
568 # - `deprecated`: The maintainer does not recommend using this crate (the description of the crate
569 # can describe why, there could be a better solution available or there could be problems with
570 # the crate that the author does not want to fix).
571 # - `none`: Displays no badge on crates.io, since the maintainer has not chosen to specify
572 # their intentions, potential crate users will need to investigate on their own.
573 maintenance = { status = "..." }
576 ### Dependency sections
578 See the [specifying dependencies page](specifying-dependencies.md) for
579 information on the `[dependencies]`, `[dev-dependencies]`,
580 `[build-dependencies]`, and target-specific `[target.*.dependencies]` sections.
582 ### The `[profile.*]` sections
584 The `[profile]` tables provide a way to customize compiler settings such as
585 optimizations and debug settings. See [the Profiles chapter](profiles.md) for
590 [`cargo init`]: ../commands/cargo-init.md
591 [`cargo new`]: ../commands/cargo-new.md
592 [`cargo package`]: ../commands/cargo-package.md
593 [`cargo run`]: ../commands/cargo-run.md
594 [crates.io]: https://crates.io/
595 [docs.rs]: https://docs.rs/
596 [publishing]: publishing.md
597 [Rust Edition]: ../../edition-guide/index.html
598 [spdx-2.1-license-expressions]: https://spdx.org/spdx-specification-21-web-version#h.jxpfx0ykyb60
599 [spdx-license-list-3.11]: https://github.com/spdx/license-list-data/tree/v3.11
600 [SPDX site]: https://spdx.org/license-list
601 [TOML]: https://toml.io/
606 "#the-project-layout": "../guide/project-layout.html",
607 "#examples": "cargo-targets.html#examples",
608 "#tests": "cargo-targets.html#tests",
609 "#integration-tests": "cargo-targets.html#integration-tests",
610 "#configuring-a-target": "cargo-targets.html#configuring-a-target",
611 "#target-auto-discovery": "cargo-targets.html#target-auto-discovery",
612 "#the-required-features-field-optional": "cargo-targets.html#the-required-features-field",
613 "#building-dynamic-or-static-libraries": "cargo-targets.html#the-crate-type-field",
614 "#the-workspace-section": "workspaces.html#the-workspace-section",
615 "#virtual-workspace": "workspaces.html",
616 "#package-selection": "workspaces.html#package-selection",
617 "#the-features-section": "features.html#the-features-section",
618 "#rules": "features.html",
619 "#usage-in-end-products": "features.html",
620 "#usage-in-packages": "features.html",
621 "#the-patch-section": "overriding-dependencies.html#the-patch-section",
622 "#using-patch-with-multiple-versions": "overriding-dependencies.html#using-patch-with-multiple-versions",
623 "#the-replace-section": "overriding-dependencies.html#the-replace-section",
625 var target = fragments[window.location.hash];
627 var url = window.location.toString();
628 var base = url.substring(0, url.lastIndexOf('/'));
629 window.location.replace(base + "/" + target);