The Cargo Book

Cargo is the Rust package manager. Cargo downloads your Rust package’s dependencies, compiles your packages, makes distributable packages, and uploads them to crates.io, the Rust community’s package registry. You can contribute to this book on GitHub.

Sections

Getting Started

To get started with Cargo, install Cargo (and Rust) and set up your first crate.

Cargo Guide

The guide will give you all you need to know about how to use Cargo to develop Rust packages.

Cargo Reference

The reference covers the details of various areas of Cargo.

Cargo Commands

The commands will let you interact with Cargo using its command-line interface.

Frequently Asked Questions

Appendices:

• Glossary
• Git Authentication

Other Documentation:

• Changelog — Detailed notes about changes in Cargo in each release.
• Rust documentation website — Links to official Rust documentation and tools.

Getting Started

To get started with Cargo, install Cargo (and Rust) and set up your first crate.

• Installation
• First steps with Cargo

Installation

Install Rust and Cargo

The easiest way to get Cargo is to install the current stable release of Rust by using rustup. Installing Rust using rustup will also install cargo.

On Linux and macOS systems, this is done as follows:

curl https://sh.rustup.rs -sSf | sh

It will download a script, and start the installation. If everything goes well, you’ll see this appear:

Rust is installed now. Great!

On Windows, download and run rustup-init.exe. It will start the installation in a console and present the above message on success.

After this, you can use the rustup command to also install beta or nightly channels for Rust and Cargo.

For other installation options and information, visit the install page of the Rust website.

Build and Install Cargo from Source

Alternatively, you can build Cargo from source.

First Steps with Cargo

This section provides a quick sense for the cargo command line tool. We demonstrate its ability to generate a new package for us, its ability to compile the crate within the package, and its ability to run the resulting program.

To start a new package with Cargo, use cargo new:

$ cargo new hello_world

Cargo defaults to --bin to make a binary program. To make a library, we would pass --lib, instead.

Let’s check out what Cargo has generated for us:

$ cd hello_world
$ tree .
.
├── Cargo.toml
└── src
    └── main.rs

1 directory, 2 files

This is all we need to get started. First, let’s check out Cargo.toml:

[package]
name = "hello_world"
version = "0.1.0"
edition = "2021"

[dependencies]

This is called a manifest, and it contains all of the metadata that Cargo needs to compile your package.

Here’s what’s in src/main.rs:

fn main() {
    println!("Hello, world!");
}

Cargo generated a “hello world” program for us, otherwise known as a binary crate. Let’s compile it:

$ cargo build
   Compiling hello_world v0.1.0 (file:///path/to/package/hello_world)

And then run it:

$ ./target/debug/hello_world
Hello, world!

We can also use cargo run to compile and then run it, all in one step:

$ cargo run
     Fresh hello_world v0.1.0 (file:///path/to/package/hello_world)
   Running `target/hello_world`
Hello, world!

Going further

For more details on using Cargo, check out the Cargo Guide

Cargo Guide

This guide will give you all that you need to know about how to use Cargo to develop Rust packages.

• Why Cargo Exists
• Creating a New Package
• Working on an Existing Cargo Package
• Dependencies
• Package Layout
• Cargo.toml vs Cargo.lock
• Tests
• Continuous Integration
• Cargo Home
• Build Cache

Why Cargo Exists

Preliminaries

In Rust, as you may know, a library or executable program is called a crate. Crates are compiled using the Rust compiler, rustc. When starting with Rust, the first source code most people encounter is that of the classic “hello world” program, which they compile by invoking rustc directly:

$ rustc hello.rs
$ ./hello
Hello, world!

Note that the above command required that you specify the file name explicitly. If you were to directly use rustc to compile a different program, a different command line invocation would be required. If you needed to specify any specific compiler flags or include external dependencies, then the needed command would be even more specific (and complex).

Furthermore, most non-trivial programs will likely have dependencies on external libraries, and will therefore also depend transitively on their dependencies. Obtaining the correct versions of all the necessary dependencies and keeping them up to date would be hard and error-prone if done by hand.

Rather than work only with crates and rustc, you can avoid the difficulties involved with performing the above tasks by introducing a higher-level “package” abstraction and by using a package manager.

Enter: Cargo

Cargo is the Rust package manager. It is a tool that allows Rust packages to declare their various dependencies and ensure that you’ll always get a repeatable build.

To accomplish this goal, Cargo does four things:

• Introduces two metadata files with various bits of package information.
• Fetches and builds your package’s dependencies.
• Invokes rustc or another build tool with the correct parameters to build your package.
• Introduces conventions to make working with Rust packages easier.

To a large extent, Cargo normalizes the commands needed to build a given program or library; this is one aspect to the above mentioned conventions. As we show later, the same command can be used to build different artifacts, regardless of their names. Rather than invoke rustc directly, you can instead invoke something generic such as cargo build and let cargo worry about constructing the correct rustc invocation. Furthermore, Cargo will automatically fetch any dependencies you have defined for your artifact from a registry, and arrange for them to be added into your build as needed.

It is only a slight exaggeration to say that once you know how to build one Cargo-based project, you know how to build all of them.

Creating a New Package

To start a new package with Cargo, use cargo new:

$ cargo new hello_world --bin

We’re passing --bin because we’re making a binary program: if we were making a library, we’d pass --lib. This also initializes a new git repository by default. If you don’t want it to do that, pass --vcs none.

Let’s check out what Cargo has generated for us:

$ cd hello_world
$ tree .
.
├── Cargo.toml
└── src
    └── main.rs

1 directory, 2 files

Let’s take a closer look at Cargo.toml:

[package]
name = "hello_world"
version = "0.1.0"
edition = "2021"

[dependencies]

This is called a manifest, and it contains all of the metadata that Cargo needs to compile your package. This file is written in the TOML format (pronounced /tɑməl/).

Here’s what’s in src/main.rs:

fn main() {
    println!("Hello, world!");
}

Cargo generated a “hello world” program for you, otherwise known as a binary crate. Let’s compile it:

$ cargo build
   Compiling hello_world v0.1.0 (file:///path/to/package/hello_world)

And then run it:

$ ./target/debug/hello_world
Hello, world!

You can also use cargo run to compile and then run it, all in one step (You won’t see the Compiling line if you have not made any changes since you last compiled):

$ cargo run
   Compiling hello_world v0.1.0 (file:///path/to/package/hello_world)
     Running `target/debug/hello_world`
Hello, world!

You’ll now notice a new file, Cargo.lock. It contains information about your dependencies. Since there are none yet, it’s not very interesting.

Once you’re ready for release, you can use cargo build --release to compile your files with optimizations turned on:

$ cargo build --release
   Compiling hello_world v0.1.0 (file:///path/to/package/hello_world)

cargo build --release puts the resulting binary in target/release instead of target/debug.

Compiling in debug mode is the default for development. Compilation time is shorter since the compiler doesn’t do optimizations, but the code will run slower. Release mode takes longer to compile, but the code will run faster.

Working on an Existing Cargo Package

If you download an existing package that uses Cargo, it’s really easy to get going.

First, get the package from somewhere. In this example, we’ll use regex cloned from its repository on GitHub:

$ git clone https://github.com/rust-lang/regex.git
$ cd regex

To build, use cargo build:

$ cargo build
   Compiling regex v1.5.0 (file:///path/to/package/regex)

This will fetch all of the dependencies and then build them, along with the package.

Dependencies

crates.io is the Rust community’s central package registry that serves as a location to discover and download packages. cargo is configured to use it by default to find requested packages.

To depend on a library hosted on crates.io, add it to your Cargo.toml.

Adding a dependency

If your Cargo.toml doesn’t already have a [dependencies] section, add that, then list the crate name and version that you would like to use. This example adds a dependency on the time crate:

[dependencies]
time = "0.1.12"

The version string is a SemVer version requirement. The specifying dependencies docs have more information about the options you have here.

If you also wanted to add a dependency on the regex crate, you would not need to add [dependencies] for each crate listed. Here’s what your whole Cargo.toml file would look like with dependencies on the time and regex crates:

[package]
name = "hello_world"
version = "0.1.0"
edition = "2021"

[dependencies]
time = "0.1.12"
regex = "0.1.41"

Re-run cargo build, and Cargo will fetch the new dependencies and all of their dependencies, compile them all, and update the Cargo.lock:

$ cargo build
      Updating crates.io index
   Downloading memchr v0.1.5
   Downloading libc v0.1.10
   Downloading regex-syntax v0.2.1
   Downloading memchr v0.1.5
   Downloading aho-corasick v0.3.0
   Downloading regex v0.1.41
     Compiling memchr v0.1.5
     Compiling libc v0.1.10
     Compiling regex-syntax v0.2.1
     Compiling memchr v0.1.5
     Compiling aho-corasick v0.3.0
     Compiling regex v0.1.41
     Compiling hello_world v0.1.0 (file:///path/to/package/hello_world)

Cargo.lock contains the exact information about which revision was used for all of these dependencies.

Now, if regex gets updated, you will still build with the same revision until you choose to run cargo update.

You can now use the regex library in main.rs.

use regex::Regex;

fn main() {
    let re = Regex::new(r"^\d{4}-\d{2}-\d{2}$").unwrap();
    println!("Did our date match? {}", re.is_match("2014-01-01"));
}

Running it will show:

$ cargo run
   Running `target/hello_world`
Did our date match? true

Package Layout

Cargo uses conventions for file placement to make it easy to dive into a new Cargo package:

.
├── Cargo.lock
├── Cargo.toml
├── src/
│   ├── lib.rs
│   ├── main.rs
│   └── bin/
│       ├── named-executable.rs
│       ├── another-executable.rs
│       └── multi-file-executable/
│           ├── main.rs
│           └── some_module.rs
├── benches/
│   ├── large-input.rs
│   └── multi-file-bench/
│       ├── main.rs
│       └── bench_module.rs
├── examples/
│   ├── simple.rs
│   └── multi-file-example/
│       ├── main.rs
│       └── ex_module.rs
└── tests/
    ├── some-integration-tests.rs
    └── multi-file-test/
        ├── main.rs
        └── test_module.rs

• Cargo.toml and Cargo.lock are stored in the root of your package (package root).
• Source code goes in the src directory.
• The default library file is src/lib.rs.
• The default executable file is src/main.rs.
  • Other executables can be placed in src/bin/.
• Benchmarks go in the benches directory.
• Examples go in the examples directory.
• Integration tests go in the tests directory.

If a binary, example, bench, or integration test consists of multiple source files, place a main.rs file along with the extra modules within a subdirectory of the src/bin, examples, benches, or tests directory. The name of the executable will be the directory name.

You can learn more about Rust’s module system in the book.

See Configuring a target for more details on manually configuring targets. See Target auto-discovery for more information on controlling how Cargo automatically infers target names.

Cargo.toml vs Cargo.lock

Cargo.toml and Cargo.lock serve two different purposes. Before we talk about them, here’s a summary:

• Cargo.toml is about describing your dependencies in a broad sense, and is written by you.
• Cargo.lock contains exact information about your dependencies. It is maintained by Cargo and should not be manually edited.

When in doubt, check Cargo.lock into the version control system (e.g. Git). For a better understanding of why and what the alternatives might be, see “Why have Cargo.lock in version control?” in the FAQ. We recommend pairing this with Verifying Latest Dependencies

Let’s dig in a little bit more.

Cargo.toml is a manifest file in which you can specify a bunch of different metadata about your package. For example, you can say that you depend on another package:

[package]
name = "hello_world"
version = "0.1.0"

[dependencies]
regex = { git = "https://github.com/rust-lang/regex.git" }

This package has a single dependency, on the regex library. It states in this case to rely on a particular Git repository that lives on GitHub. Since you haven’t specified any other information, Cargo assumes that you intend to use the latest commit on the default branch to build our package.

Sound good? Well, there’s one problem: If you build this package today, and then you send a copy to me, and I build this package tomorrow, something bad could happen. There could be more commits to regex in the meantime, and my build would include new commits while yours would not. Therefore, we would get different builds. This would be bad because we want reproducible builds.

You could fix this problem by defining a specific rev value in our Cargo.toml, so Cargo could know exactly which revision to use when building the package:

[dependencies]
regex = { git = "https://github.com/rust-lang/regex.git", rev = "9f9f693" }

Now our builds will be the same. But there’s a big drawback: now you have to manually think about SHA-1s every time you want to update our library. This is both tedious and error prone.

Enter the Cargo.lock. Because of its existence, you don’t need to manually keep track of the exact revisions: Cargo will do it for you. When you have a manifest like this:

[package]
name = "hello_world"
version = "0.1.0"

[dependencies]
regex = { git = "https://github.com/rust-lang/regex.git" }

Cargo will take the latest commit and write that information out into your Cargo.lock when you build for the first time. That file will look like this:

[[package]]
name = "hello_world"
version = "0.1.0"
dependencies = [
 "regex 1.5.0 (git+https://github.com/rust-lang/regex.git#9f9f693768c584971a4d53bc3c586c33ed3a6831)",
]

[[package]]
name = "regex"
version = "1.5.0"
source = "git+https://github.com/rust-lang/regex.git#9f9f693768c584971a4d53bc3c586c33ed3a6831"

You can see that there’s a lot more information here, including the exact revision you used to build. Now when you give your package to someone else, they’ll use the exact same SHA, even though you didn’t specify it in your Cargo.toml.

When you’re ready to opt in to a new version of the library, Cargo can re-calculate the dependencies and update things for you:

$ cargo update         # updates all dependencies
$ cargo update regex   # updates just “regex”

This will write out a new Cargo.lock with the new version information. Note that the argument to cargo update is actually a Package ID Specification and regex is just a short specification.

Tests

Cargo can run your tests with the cargo test command. Cargo looks for tests to run in two places: in each of your src files and any tests in tests/. Tests in your src files should be unit tests and documentation tests. Tests in tests/ should be integration-style tests. As such, you’ll need to import your crates into the files in tests.

Here’s an example of running cargo test in our package, which currently has no tests:

$ cargo test
   Compiling regex v1.5.0 (https://github.com/rust-lang/regex.git#9f9f693)
   Compiling hello_world v0.1.0 (file:///path/to/package/hello_world)
     Running target/test/hello_world-9c2b65bbb79eabce

running 0 tests

test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out

If your package had tests, you would see more output with the correct number of tests.

You can also run a specific test by passing a filter:

$ cargo test foo

This will run any test with foo in its name.

cargo test runs additional checks as well. It will compile any examples you’ve included to ensure they still compile. It also runs documentation tests to ensure your code samples from documentation comments compile. Please see the testing guide in the Rust documentation for a general view of writing and organizing tests. See Cargo Targets: Tests to learn more about different styles of tests in Cargo.

Continuous Integration

Getting Started

A basic CI will build and test your projects:

GitHub Actions

To test your package on GitHub Actions, here is a sample .github/workflows/ci.yml file:

name: Cargo Build & Test

on:
  push:
  pull_request:

env: 
  CARGO_TERM_COLOR: always

jobs:
  build_and_test:
    name: Rust project - latest
    runs-on: ubuntu-latest
    strategy:
      matrix:
        toolchain:
          - stable
          - beta
          - nightly
    steps:
      - uses: actions/checkout@v4
      - run: rustup update ${{ matrix.toolchain }} && rustup default ${{ matrix.toolchain }}
      - run: cargo build --verbose
      - run: cargo test --verbose
  

This will test all three release channels (note a failure in any toolchain version will fail the entire job). You can also click "Actions" > "new workflow" in the GitHub UI and select Rust to add the default configuration to your repo. See GitHub Actions documentation for more information.

GitLab CI

To test your package on GitLab CI, here is a sample .gitlab-ci.yml file:

stages:
  - build

rust-latest:
  stage: build
  image: rust:latest
  script:
    - cargo build --verbose
    - cargo test --verbose

rust-nightly:
  stage: build
  image: rustlang/rust:nightly
  script:
    - cargo build --verbose
    - cargo test --verbose
  allow_failure: true

This will test on the stable channel and nightly channel, but any breakage in nightly will not fail your overall build. Please see the GitLab CI documentation for more information.

builds.sr.ht

To test your package on sr.ht, here is a sample .build.yml file. Be sure to change <your repo> and <your project> to the repo to clone and the directory where it was cloned.

image: archlinux
packages:
  - rustup
sources:
  - <your repo>
tasks:
  - setup: |
      rustup toolchain install nightly stable
      cd <your project>/
      rustup run stable cargo fetch
  - stable: |
      rustup default stable
      cd <your project>/
      cargo build --verbose
      cargo test --verbose
  - nightly: |
      rustup default nightly
      cd <your project>/
      cargo build --verbose ||:
      cargo test --verbose  ||:
  - docs: |
      cd <your project>/
      rustup run stable cargo doc --no-deps
      rustup run nightly cargo doc --no-deps ||:

This will test and build documentation on the stable channel and nightly channel, but any breakage in nightly will not fail your overall build. Please see the builds.sr.ht documentation for more information.

CircleCI

To test your package on CircleCI, here is a sample .circleci/config.yml file:

version: 2.1
jobs:
  build:
    docker:
      # check https://circleci.com/developer/images/image/cimg/rust#image-tags for latest
      - image: cimg/rust:1.77.2
    steps:
      - checkout
      - run: cargo test

To run more complex pipelines, including flaky test detection, caching, and artifact management, please see CircleCI Configuration Reference.

Verifying Latest Dependencies

When specifying dependencies in Cargo.toml, they generally match a range of versions. Exhaustively testing all version combination would be unwieldy. Verifying the latest versions would at least test for users who run cargo add or cargo install.

When testing the latest versions some considerations are:

• Minimizing external factors affecting local development or CI
• Rate of new dependencies being published
• Level of risk a project is willing to accept
• CI costs, including indirect costs like if a CI service has a maximum for parallel runners, causing new jobs to be serialized when at the maximum.

Some potential solutions include:

• Not checking in the Cargo.lock
  • Depending on PR velocity, many versions may go untested
  • This comes at the cost of determinism
• Have a CI job verify the latest dependencies but mark it to “continue on failure”
  • Depending on the CI service, failures might not be obvious
  • Depending on PR velocity, may use more resources than necessary
• Have a scheduled CI job to verify latest dependencies
  • A hosted CI service may disable scheduled jobs for repositories that haven’t been touched in a while, affecting passively maintained packages
  • Depending on the CI service, notifications might not be routed to people who can act on the failure
  • If not balanced with dependency publish rate, may not test enough versions or may do redundant testing
• Regularly update dependencies through PRs, like with Dependabot or RenovateBot
  • Can isolate dependencies to their own PR or roll them up into a single PR
  • Only uses the resources necessary
  • Can configure the frequency to balance CI resources and coverage of dependency versions

An example CI job to verify latest dependencies, using GitHub Actions:

jobs:
  latest_deps:
    name: Latest Dependencies
    runs-on: ubuntu-latest
    continue-on-error: true
    env:
      CARGO_RESOLVER_INCOMPATIBLE_RUST_VERSIONS: allow
    steps:
      - uses: actions/checkout@v4
      - run: rustup update stable && rustup default stable
      - run: cargo update --verbose
      - run: cargo build --verbose
      - run: cargo test --verbose

Notes:

• CARGO_RESOLVER_INCOMPATIBLE_RUST_VERSIONS is set to ensure the resolver doesn’t limit selected dependencies because of your project’s Rust version.

For projects with higher risks of per-platform or per-Rust version failures, more combinations may want to be tested.

Verifying rust-version

When publishing packages that specify rust-version, it is important to verify the correctness of that field.

Some third-party tools that can help with this include:

• cargo-msrv
• cargo-hack

An example of one way to do this, using GitHub Actions:

jobs:
  msrv:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v4
    - uses: taiki-e/install-action@cargo-hack
    - run: cargo hack check --rust-version --workspace --all-targets --ignore-private

This tries to balance thoroughness with turnaround time:

• A single platform is used as most projects are platform-agnostic, trusting platform-specific dependencies to verify their behavior.
• cargo check is used as most issues contributors will run into are API availability and not behavior.
• Unpublished packages are skipped as this assumes only consumers of the verified project, through a registry, will care about rust-version.

Publishing on crates.io

Once you’ve got a library that you’d like to share with the world, it’s time to publish it on crates.io! Publishing a crate is when a specific version is uploaded to be hosted on crates.io.

Take care when publishing a crate, because a publish is permanent. The version can never be overwritten, and the code cannot be deleted. There is no limit to the number of versions which can be published, however.

Before your first publish

First things first, you’ll need an account on crates.io to acquire an API token. To do so, visit the home page and log in via a GitHub account (required for now). You will also need to provide and verify your email address on the Account Settings page. Once that is done create an API token, make sure you copy it. Once you leave the page you will not be able to see it again.

Then run the cargo login command.

$ cargo login

Then at the prompt put in the token specified.

please paste the API Token found on https://crates.io/me below
abcdefghijklmnopqrstuvwxyz012345

This command will inform Cargo of your API token and store it locally in your ~/.cargo/credentials.toml. Note that this token is a secret and should not be shared with anyone else. If it leaks for any reason, you should revoke it immediately.

Note: The cargo logout command can be used to remove the token from credentials.toml. This can be useful if you no longer need it stored on the local machine.

Before publishing a new crate

Keep in mind that crate names on crates.io are allocated on a first-come-first-serve basis. Once a crate name is taken, it cannot be used for another crate.

Check out the metadata you can specify in Cargo.toml to ensure your crate can be discovered more easily! Before publishing, make sure you have filled out the following fields:

• license or license-file
• description
• homepage
• repository
• readme

It would also be a good idea to include some keywords and categories, though they are not required.

If you are publishing a library, you may also want to consult the Rust API Guidelines.

Packaging a crate

The next step is to package up your crate and upload it to crates.io. For this we’ll use the cargo publish subcommand. This command performs the following steps:

1. Perform some verification checks on your package.
2. Compress your source code into a .crate file.
3. Extract the .crate file into a temporary directory and verify that it compiles.
4. Upload the .crate file to crates.io.
5. The registry will perform some additional checks on the uploaded package before adding it.

It is recommended that you first run cargo publish --dry-run (or cargo package which is equivalent) to ensure there aren’t any warnings or errors before publishing. This will perform the first three steps listed above.

$ cargo publish --dry-run

You can inspect the generated .crate file in the target/package directory. crates.io currently has a 10MB size limit on the .crate file. You may want to check the size of the .crate file to ensure you didn’t accidentally package up large assets that are not required to build your package, such as test data, website documentation, or code generation. You can check which files are included with the following command:

$ cargo package --list

Cargo will automatically ignore files ignored by your version control system when packaging, but if you want to specify an extra set of files to ignore you can use the exclude key in the manifest:

[package]
# ...
exclude = [
    "public/assets/*",
    "videos/*",
]

If you’d rather explicitly list the files to include, Cargo also supports an include key, which if set, overrides the exclude key:

[package]
# ...
include = [
    "**/*.rs",
    "Cargo.toml",
]

Uploading the crate

When you are ready to publish, use the cargo publish command to upload to crates.io:

$ cargo publish

And that’s it, you’ve now published your first crate!

Publishing a new version of an existing crate

In order to release a new version, change the version value specified in your Cargo.toml manifest. Keep in mind the SemVer rules which provide guidelines on what is a compatible change. Then run cargo publish as described above to upload the new version.

Recommendation: Consider the full release process and automate what you can.

Each version should include:

• A changelog entry, preferably manually curated though a generated one is better than nothing
• A git tag pointing to the published commit

Examples of third-party tools that are representative of different workflows include (in alphabetical order):

• cargo-release
• cargo-smart-release
• release-plz

For more, see crates.io.

Managing a crates.io-based crate

Management of crates is primarily done through the command line cargo tool rather than the crates.io web interface. For this, there are a few subcommands to manage a crate.

cargo yank

Occasions may arise where you publish a version of a crate that actually ends up being broken for one reason or another (syntax error, forgot to include a file, etc.). For situations such as this, Cargo supports a “yank” of a version of a crate.

$ cargo yank --version 1.0.1
$ cargo yank --version 1.0.1 --undo

A yank does not delete any code. This feature is not intended for deleting accidentally uploaded secrets, for example. If that happens, you must reset those secrets immediately.

The semantics of a yanked version are that no new dependencies can be created against that version, but all existing dependencies continue to work. One of the major goals of crates.io is to act as a permanent archive of crates that does not change over time, and allowing deletion of a version would go against this goal. Essentially a yank means that all packages with a Cargo.lock will not break, while any future Cargo.lock files generated will not list the yanked version.

cargo owner

A crate is often developed by more than one person, or the primary maintainer may change over time! The owner of a crate is the only person allowed to publish new versions of the crate, but an owner may designate additional owners.

$ cargo owner --add github-handle
$ cargo owner --remove github-handle
$ cargo owner --add github:rust-lang:owners
$ cargo owner --remove github:rust-lang:owners

The owner IDs given to these commands must be GitHub user names or GitHub teams.

If a user name is given to --add, that user is invited as a “named” owner, with full rights to the crate. In addition to being able to publish or yank versions of the crate, they have the ability to add or remove owners, including the owner that made them an owner. Needless to say, you shouldn’t make people you don’t fully trust into a named owner. In order to become a named owner, a user must have logged into crates.io previously.

If a team name is given to --add, that team is invited as a “team” owner, with restricted right to the crate. While they have permission to publish or yank versions of the crate, they do not have the ability to add or remove owners. In addition to being more convenient for managing groups of owners, teams are just a bit more secure against owners becoming malicious.

The syntax for teams is currently github:org:team (see examples above). In order to invite a team as an owner one must be a member of that team. No such restriction applies to removing a team as an owner.

GitHub permissions

Team membership is not something GitHub provides simple public access to, and it is likely for you to encounter the following message when working with them:

It looks like you don’t have permission to query a necessary property from GitHub to complete this request. You may need to re-authenticate on crates.io to grant permission to read GitHub org memberships.

This is basically a catch-all for “you tried to query a team, and one of the five levels of membership access control denied this”. That is not an exaggeration. GitHub’s support for team access control is Enterprise Grade.

The most likely cause of this is simply that you last logged in before this feature was added. We originally requested no permissions from GitHub when authenticating users, because we didn’t actually ever use the user’s token for anything other than logging them in. However to query team membership on your behalf, we now require the read:org scope.

You are free to deny us this scope, and everything that worked before teams were introduced will keep working. However you will never be able to add a team as an owner, or publish a crate as a team owner. If you ever attempt to do this, you will get the error above. You may also see this error if you ever try to publish a crate that you don’t own at all, but otherwise happens to have a team.

If you ever change your mind, or just aren’t sure if crates.io has sufficient permission, you can always go to https://crates.io/ and re-authenticate, which will prompt you for permission if crates.io doesn’t have all the scopes it would like to.

An additional barrier to querying GitHub is that the organization may be actively denying third party access. To check this, you can go to:

https://github.com/organizations/:org/settings/oauth_application_policy

where :org is the name of the organization (e.g., rust-lang). You may see something like:

Where you may choose to explicitly remove crates.io from your organization’s blacklist, or simply press the “Remove Restrictions” button to allow all third party applications to access this data.

Alternatively, when crates.io requested the read:org scope, you could have explicitly whitelisted crates.io querying the org in question by pressing the “Grant Access” button next to its name:

Troubleshooting GitHub team access errors

When trying to add a GitHub team as crate owner, you may see an error like:

error: failed to invite owners to crate <crate_name>: api errors (status 200 OK): could not find the github team org/repo

In that case, you should go to the GitHub Application settings page and check if crates.io is listed in the Authorized OAuth Apps tab. If it isn’t, you should go to https://crates.io/ and authorize it. Then go back to the Application Settings page on GitHub, click on the crates.io application in the list, and make sure you or your organization is listed in the “Organization access” list with a green check mark. If there’s a button labeled Grant or Request, you should grant the access or request the org owner to do so.

Cargo Home

The “Cargo home” functions as a download and source cache. When building a crate, Cargo stores downloaded build dependencies in the Cargo home. You can alter the location of the Cargo home by setting the CARGO_HOME environmental variable. The home crate provides an API for getting this location if you need this information inside your Rust crate. By default, the Cargo home is located in $HOME/.cargo/.

Please note that the internal structure of the Cargo home is not stabilized and may be subject to change at any time.

The Cargo home consists of following components:

Files:

• config.toml Cargo’s global configuration file, see the config entry in the reference.

• credentials.toml Private login credentials from cargo login in order to log in to a registry.

• .crates.toml, .crates2.json These hidden files contain package information of crates installed via cargo install. Do NOT edit by hand!

Directories:

• bin The bin directory contains executables of crates that were installed via cargo install or rustup. To be able to make these binaries accessible, add the path of the directory to your $PATH environment variable.

• git Git sources are stored here:

  • git/db When a crate depends on a git repository, Cargo clones the repo as a bare repo into this directory and updates it if necessary.

  • git/checkouts If a git source is used, the required commit of the repo is checked out from the bare repo inside git/db into this directory. This provides the compiler with the actual files contained in the repo of the commit specified for that dependency. Multiple checkouts of different commits of the same repo are possible.

• registry Packages and metadata of crate registries (such as crates.io) are located here.

  • registry/index The index is a bare git repository which contains the metadata (versions, dependencies etc) of all available crates of a registry.

  • registry/cache Downloaded dependencies are stored in the cache. The crates are compressed gzip archives named with a .crate extension.

  • registry/src If a downloaded .crate archive is required by a package, it is unpacked into registry/src folder where rustc will find the .rs files.

Caching the Cargo home in CI

To avoid redownloading all crate dependencies during continuous integration, you can cache the $CARGO_HOME directory. However, caching the entire directory is often inefficient as it will contain downloaded sources twice. If we depend on a crate such as serde 1.0.92 and cache the entire $CARGO_HOME we would actually cache the sources twice, the serde-1.0.92.crate inside registry/cache and the extracted .rs files of serde inside registry/src. That can unnecessarily slow down the build as downloading, extracting, recompressing and reuploading the cache to the CI servers can take some time.

If you wish to cache binaries installed with cargo install, you need to cache the bin/ folder and the .crates.toml and .crates2.json files.

It should be sufficient to cache the following files and directories across builds:

• .crates.toml
• .crates2.json
• bin/
• registry/index/
• registry/cache/
• git/db/

Vendoring all dependencies of a project

See the cargo vendor subcommand.

Clearing the cache

In theory, you can always remove any part of the cache and Cargo will do its best to restore sources if a crate needs them either by reextracting an archive or checking out a bare repo or by simply redownloading the sources from the web.

Alternatively, the cargo-cache crate provides a simple CLI tool to only clear selected parts of the cache or show sizes of its components in your command-line.

Cargo Reference

The reference covers the details of various areas of Cargo.

• Specifying Dependencies
  • Overriding Dependencies
• The Manifest Format
  • Cargo Targets
• Workspaces
• Features
  • Features Examples
• Profiles
• Configuration
• Environment Variables
• Build Scripts
  • Build Script Examples
• Publishing on crates.io
• Package ID Specifications
• Source Replacement
• External Tools
• Registries
  • Registry Authentication
    • Credential Provider Protocol
  • Running a Registry
    • Registry Index
    • Registry Web API
• Dependency Resolution
• SemVer Compatibility
• Future incompat report
• Reporting build timings
• Lints
• Unstable Features

The Manifest Format

The Cargo.toml file for each package is called its manifest. It is written in the TOML format. It contains metadata that is needed to compile the package. Checkout the cargo locate-project section for more detail on how cargo finds the manifest file.

Every manifest file consists of the following sections:

• cargo-features — Unstable, nightly-only features.
• [package] — Defines a package.
  • name — The name of the package.
  • version — The version of the package.
  • authors — The authors of the package.
  • edition — The Rust edition.
  • rust-version — The minimal supported Rust version.
  • description — A description of the package.
  • documentation — URL of the package documentation.
  • readme — Path to the package’s README file.
  • homepage — URL of the package homepage.
  • repository — URL of the package source repository.
  • license — The package license.
  • license-file — Path to the text of the license.
  • keywords — Keywords for the package.
  • categories — Categories of the package.
  • workspace — Path to the workspace for the package.
  • build — Path to the package build script.
  • links — Name of the native library the package links with.
  • exclude — Files to exclude when publishing.
  • include — Files to include when publishing.
  • publish — Can be used to prevent publishing the package.
  • metadata — Extra settings for external tools.
  • default-run — The default binary to run by cargo run.
  • autolib — Disables library auto discovery.
  • autobins — Disables binary auto discovery.
  • autoexamples — Disables example auto discovery.
  • autotests — Disables test auto discovery.
  • autobenches — Disables bench auto discovery.
  • resolver — Sets the dependency resolver to use.
• Target tables: (see configuration for settings)
  • [lib] — Library target settings.
  • [[bin]] — Binary target settings.
  • [[example]] — Example target settings.
  • [[test]] — Test target settings.
  • [[bench]] — Benchmark target settings.
• Dependency tables:
  • [dependencies] — Package library dependencies.
  • [dev-dependencies] — Dependencies for examples, tests, and benchmarks.
  • [build-dependencies] — Dependencies for build scripts.
  • [target] — Platform-specific dependencies.
• [badges] — Badges to display on a registry.
• [features] — Conditional compilation features.
• [lints] — Configure linters for this package.
• [patch] — Override dependencies.
• [replace] — Override dependencies (deprecated).
• [profile] — Compiler settings and optimizations.
• [workspace] — The workspace definition.

The [package] section

The first section in a Cargo.toml is [package].

[package]
name = "hello_world" # the name of the package
version = "0.1.0"    # the current version, obeying semver
authors = ["Alice <a@example.com>", "Bob <b@example.com>"]

The only field required by Cargo is name. If publishing to a registry, the registry may require additional fields. See the notes below and the publishing chapter for requirements for publishing to crates.io.

The name field

The package name is an identifier used to refer to the package. It is used when listed as a dependency in another package, and as the default name of inferred lib and bin targets.

The name must use only alphanumeric characters or - or _, and cannot be empty.

Note that cargo new and cargo init impose some additional restrictions on the package name, such as enforcing that it is a valid Rust identifier and not a keyword. crates.io imposes even more restrictions, such as:

• Only ASCII characters are allowed.
• Do not use reserved names.
• Do not use special Windows names such as “nul”.
• Use a maximum of 64 characters of length.

The version field

The version field is formatted according to the SemVer specification:

Versions must have three numeric parts, the major version, the minor version, and the patch version.

A pre-release part can be added after a dash such as 1.0.0-alpha. The pre-release part may be separated with periods to distinguish separate components. Numeric components will use numeric comparison while everything else will be compared lexicographically. For example, 1.0.0-alpha.11 is higher than 1.0.0-alpha.4.

A metadata part can be added after a plus, such as 1.0.0+21AF26D3. This is for informational purposes only and is generally ignored by Cargo.

Cargo bakes in the concept of Semantic Versioning, so versions are considered considered compatible if their left-most non-zero major/minor/patch component is the same. See the Resolver chapter for more information on how Cargo uses versions to resolve dependencies.

This field is optional and defaults to 0.0.0. The field is required for publishing packages.

MSRV: Before 1.75, this field was required

The authors field

The optional authors field lists in an array the people or organizations that are considered the “authors” of the package. The exact meaning is open to interpretation — it may list the original or primary authors, current maintainers, or owners of the package. An optional email address may be included within angled brackets at the end of each author entry.

[package]
# ...
authors = ["Graydon Hoare", "Fnu Lnu <no-reply@rust-lang.org>"]

This field is only surfaced in package metadata and in the CARGO_PKG_AUTHORS environment variable within build.rs. It is not displayed in the crates.io user interface.

Warning: Package manifests cannot be changed once published, so this field cannot be changed or removed in already-published versions of a package.

The edition field

The edition key is an optional key that affects which Rust Edition your package is compiled with. Setting the edition key in [package] will affect all targets/crates in the package, including test suites, benchmarks, binaries, examples, etc.

[package]
# ...
edition = '2021'

Most manifests have the edition field filled in automatically by cargo new with the latest stable edition. By default cargo new creates a manifest with the 2021 edition currently.

If the edition field is not present in Cargo.toml, then the 2015 edition is assumed for backwards compatibility. Note that all manifests created with cargo new will not use this historical fallback because they will have edition explicitly specified to a newer value.

The rust-version field

The rust-version field tells cargo what version of the Rust toolchain you support for your package. See the Rust version chapter for more detail.

The description field

The description is a short blurb about the package. crates.io will display this with your package. This should be plain text (not Markdown).

[package]
# ...
description = "A short description of my package"

Note: crates.io requires the description to be set.

The documentation field

The documentation field specifies a URL to a website hosting the crate’s documentation. If no URL is specified in the manifest file, crates.io will automatically link your crate to the corresponding docs.rs page when the documentation has been built and is available (see docs.rs queue).

[package]
# ...
documentation = "https://docs.rs/bitflags"

The readme field

The readme field should be the path to a file in the package root (relative to this Cargo.toml) that contains general information about the package. This file will be transferred to the registry when you publish. crates.io will interpret it as Markdown and render it on the crate’s page.

[package]
# ...
readme = "README.md"

If no value is specified for this field, and a file named README.md, README.txt or README exists in the package root, then the name of that file will be used. You can suppress this behavior by setting this field to false. If the field is set to true, a default value of README.md will be assumed.

The homepage field

The homepage field should be a URL to a site that is the home page for your package.

[package]
# ...
homepage = "https://serde.rs"

A value should only be set for homepage if there is a dedicated website for the crate other than the source repository or API documentation. Do not make homepage redundant with either the documentation or repository values.

The repository field

The repository field should be a URL to the source repository for your package.

[package]
# ...
repository = "https://github.com/rust-lang/cargo"

The license and license-file fields

The license field contains the name of the software license that the package is released under. The license-file field contains the path to a file containing the text of the license (relative to this Cargo.toml).

crates.io interprets the license field as an SPDX 2.3 license expression. The name must be a known license from the SPDX license list 3.20. See the SPDX site for more information.

SPDX license expressions support AND and OR operators to combine multiple licenses.¹

[package]
# ...
license = "MIT OR Apache-2.0"

Using OR indicates the user may choose either license. Using AND indicates the user must comply with both licenses simultaneously. The WITH operator indicates a license with a special exception. Some examples:

• MIT OR Apache-2.0
• LGPL-2.1-only AND MIT AND BSD-2-Clause
• GPL-2.0-or-later WITH Bison-exception-2.2

If a package is using a nonstandard license, then the license-file field may be specified in lieu of the license field.

[package]
# ...
license-file = "LICENSE.txt"

Note: crates.io requires either license or license-file to be set.

The keywords field

The keywords field is an array of strings that describe this package. This can help when searching for the package on a registry, and you may choose any words that would help someone find this crate.

[package]
# ...
keywords = ["gamedev", "graphics"]

Note: crates.io allows a maximum of 5 keywords. Each keyword must be ASCII text, have at most 20 characters, start with an alphanumeric character, and only contain letters, numbers, _, - or +.

The categories field

The categories field is an array of strings of the categories this package belongs to.

categories = ["command-line-utilities", "development-tools::cargo-plugins"]

Note: crates.io has a maximum of 5 categories. Each category should match one of the strings available at https://crates.io/category_slugs, and must match exactly.

The workspace field

The workspace field can be used to configure the workspace that this package will be a member of. If not specified this will be inferred as the first Cargo.toml with [workspace] upwards in the filesystem. Setting this is useful if the member is not inside a subdirectory of the workspace root.

[package]
# ...
workspace = "path/to/workspace/root"

This field cannot be specified if the manifest already has a [workspace] table defined. That is, a crate cannot both be a root crate in a workspace (contain [workspace]) and also be a member crate of another workspace (contain package.workspace).

For more information, see the workspaces chapter.

The build field

The build field specifies a file in the package root which is a build script for building native code. More information can be found in the build script guide.

[package]
# ...
build = "build.rs"

The default is "build.rs", which loads the script from a file named build.rs in the root of the package. Use build = "custom_build_name.rs" to specify a path to a different file or build = false to disable automatic detection of the build script.

The links field

The links field specifies the name of a native library that is being linked to. More information can be found in the links section of the build script guide.

For example, a crate that links a native library called “git2” (e.g. libgit2.a on Linux) may specify:

[package]
# ...
links = "git2"

The exclude and include fields

The exclude and include fields can be used to explicitly specify which files are included when packaging a project to be published, and certain kinds of change tracking (described below). The patterns specified in the exclude field identify a set of files that are not included, and the patterns in include specify files that are explicitly included. You may run cargo package --list to verify which files will be included in the package.

[package]
# ...
exclude = ["/ci", "images/", ".*"]

[package]
# ...
include = ["/src", "COPYRIGHT", "/examples", "!/examples/big_example"]

The default if neither field is specified is to include all files from the root of the package, except for the exclusions listed below.

If include is not specified, then the following files will be excluded:

• If the package is not in a git repository, all “hidden” files starting with a dot will be skipped.
• If the package is in a git repository, any files that are ignored by the gitignore rules of the repository and global git configuration will be skipped.

Regardless of whether exclude or include is specified, the following files are always excluded:

• Any sub-packages will be skipped (any subdirectory that contains a Cargo.toml file).
• A directory named target in the root of the package will be skipped.

The following files are always included:

• The Cargo.toml file of the package itself is always included, it does not need to be listed in include.
• A minimized Cargo.lock is automatically included if the package contains a binary or example target, see cargo package for more information.
• If a license-file is specified, it is always included.

The options are mutually exclusive; setting include will override an exclude. If you need to have exclusions to a set of include files, use the ! operator described below.

The patterns should be gitignore-style patterns. Briefly:

• foo matches any file or directory with the name foo anywhere in the package. This is equivalent to the pattern **/foo.
• /foo matches any file or directory with the name foo only in the root of the package.
• foo/ matches any directory with the name foo anywhere in the package.
• Common glob patterns like *, ?, and [] are supported:
  • * matches zero or more characters except /. For example, *.html matches any file or directory with the .html extension anywhere in the package.
  • ? matches any character except /. For example, foo? matches food, but not foo.
  • [] allows for matching a range of characters. For example, [ab] matches either a or b. [a-z] matches letters a through z.
• **/ prefix matches in any directory. For example, **/foo/bar matches the file or directory bar anywhere that is directly under directory foo.
• /** suffix matches everything inside. For example, foo/** matches all files inside directory foo, including all files in subdirectories below foo.
• /**/ matches zero or more directories. For example, a/**/b matches a/b, a/x/b, a/x/y/b, and so on.
• ! prefix negates a pattern. For example, a pattern of src/*.rs and !foo.rs would match all files with the .rs extension inside the src directory, except for any file named foo.rs.

The include/exclude list is also used for change tracking in some situations. For targets built with rustdoc, it is used to determine the list of files to track to determine if the target should be rebuilt. If the package has a build script that does not emit any rerun-if-* directives, then the include/exclude list is used for tracking if the build script should be re-run if any of those files change.

The publish field

The publish field can be used to control which registries names the package may be published to:

[package]
# ...
publish = ["some-registry-name"]

To prevent a package from being published to a registry (like crates.io) by mistake, for instance to keep a package private in a company, you can omit the version field. If you’d like to be more explicit, you can disable publishing:

[package]
# ...
publish = false

If publish array contains a single registry, cargo publish command will use it when --registry flag is not specified.

The metadata table

Cargo by default will warn about unused keys in Cargo.toml to assist in detecting typos and such. The package.metadata table, however, is completely ignored by Cargo and will not be warned about. This section can be used for tools which would like to store package configuration in Cargo.toml. For example:

[package]
name = "..."
# ...

# Metadata used when generating an Android APK, for example.
[package.metadata.android]
package-name = "my-awesome-android-app"
assets = "path/to/static"

You’ll need to look in the documentation for your tool to see how to use this field. For Rust Projects that use package.metadata tables, see:

• docs.rs

There is a similar table at the workspace level at workspace.metadata. While cargo does not specify a format for the content of either of these tables, it is suggested that external tools may wish to use them in a consistent fashion, such as referring to the data in workspace.metadata if data is missing from package.metadata, if that makes sense for the tool in question.

The default-run field

The default-run field in the [package] section of the manifest can be used to specify a default binary picked by cargo run. For example, when there is both src/bin/a.rs and src/bin/b.rs:

[package]
default-run = "a"

The [lints] section

Override the default level of lints from different tools by assigning them to a new level in a table, for example:

[lints.rust]
unsafe_code = "forbid"

This is short-hand for:

[lints.rust]
unsafe_code = { level = "forbid", priority = 0 }

level corresponds to the lint levels in rustc:

• forbid
• deny
• warn
• allow

priority is a signed integer that controls which lints or lint groups override other lint groups:

• lower (particularly negative) numbers have lower priority, being overridden by higher numbers, and show up first on the command-line to tools like rustc

To know which table under [lints] a particular lint belongs under, it is the part before :: in the lint name. If there isn’t a ::, then the tool is rust. For example a warning about unsafe_code would be lints.rust.unsafe_code but a lint about clippy::enum_glob_use would be lints.clippy.enum_glob_use.

For example:

[lints.rust]
unsafe_code = "forbid"

[lints.clippy]
enum_glob_use = "deny"

Generally, these will only affect local development of the current package. Cargo only applies these to the current package and not to dependencies. As for dependents, Cargo suppresses lints from non-path dependencies with features like --cap-lints.

MSRV: Respected as of 1.74

The [badges] section

The [badges] section is for specifying status badges that can be displayed on a registry website when the package is published.

Note: crates.io previously displayed badges next to a crate on its website, but that functionality has been removed. Packages should place badges in its README file which will be displayed on crates.io (see the readme field).

[badges]
# The `maintenance` table indicates the status of the maintenance of
# the crate. This may be used by a registry, but is currently not
# used by crates.io. See https://github.com/rust-lang/crates.io/issues/2437
# and https://github.com/rust-lang/crates.io/issues/2438 for more details.
#
# The `status` field is required. Available options are:
# - `actively-developed`: New features are being added and bugs are being fixed.
# - `passively-maintained`: There are no plans for new features, but the maintainer intends to
#   respond to issues that get filed.
# - `as-is`: The crate is feature complete, the maintainer does not intend to continue working on
#   it or providing support, but it works for the purposes it was designed for.
# - `experimental`: The author wants to share it with the community but is not intending to meet
#   anyone's particular use case.
# - `looking-for-maintainer`: The current maintainer would like to transfer the crate to someone
#   else.
# - `deprecated`: The maintainer does not recommend using this crate (the description of the crate
#   can describe why, there could be a better solution available or there could be problems with
#   the crate that the author does not want to fix).
# - `none`: Displays no badge on crates.io, since the maintainer has not chosen to specify
#   their intentions, potential crate users will need to investigate on their own.
maintenance = { status = "..." }

Dependency sections

See the specifying dependencies page for information on the [dependencies], [dev-dependencies], [build-dependencies], and target-specific [target.*.dependencies] sections.

The [profile.*] sections

The [profile] tables provide a way to customize compiler settings such as optimizations and debug settings. See the Profiles chapter for more detail.

Cargo Targets

Cargo packages consist of targets which correspond to source files which can be compiled into a crate. Packages can have library, binary, example, test, and benchmark targets. The list of targets can be configured in the Cargo.toml manifest, often inferred automatically by the directory layout of the source files.

See Configuring a target below for details on configuring the settings for a target.

Library

The library target defines a “library” that can be used and linked by other libraries and executables. The filename defaults to src/lib.rs, and the name of the library defaults to the name of the package, with any dashes replaced with underscores. A package can have only one library. The settings for the library can be customized in the [lib] table in Cargo.toml.

# Example of customizing the library in Cargo.toml.
[lib]
crate-type = ["cdylib"]
bench = false

Binaries

Binary targets are executable programs that can be run after being compiled. A binary’s source can be src/main.rs and/or stored in the src/bin/ directory. For src/main.rs, the default binary name is the package name. The settings for each binary can be customized in the[[bin]] tables in Cargo.toml.

Binaries can use the public API of the package’s library. They are also linked with the [dependencies] defined in Cargo.toml.

You can run individual binaries with the cargo run command with the --bin <bin-name> option. cargo install can be used to copy the executable to a common location.

# Example of customizing binaries in Cargo.toml.
[[bin]]
name = "cool-tool"
test = false
bench = false

[[bin]]
name = "frobnicator"
required-features = ["frobnicate"]

Examples

Files located under the examples directory are example uses of the functionality provided by the library. When compiled, they are placed in the target/debug/examples directory.

Examples can use the public API of the package’s library. They are also linked with the [dependencies] and [dev-dependencies] defined in Cargo.toml.

By default, examples are executable binaries (with a main() function). You can specify the crate-type field to make an example be compiled as a library:

[[example]]
name = "foo"
crate-type = ["staticlib"]

You can run individual executable examples with the cargo run command with the --example <example-name> option. Library examples can be built with cargo build with the --example <example-name> option. cargo install with the --example <example-name> option can be used to copy executable binaries to a common location. Examples are compiled by cargo test by default to protect them from bit-rotting. Set the test field to true if you have #[test] functions in the example that you want to run with cargo test.

Tests

There are two styles of tests within a Cargo project:

• Unit tests which are functions marked with the #[test] attribute located within your library or binaries (or any target enabled with the test field). These tests have access to private APIs located within the target they are defined in.
• Integration tests which is a separate executable binary, also containing #[test] functions, which is linked with the project’s library and has access to its public API.

Tests are run with the cargo test command. By default, Cargo and rustc use the libtest harness which is responsible for collecting functions annotated with the #[test] attribute and executing them in parallel, reporting the success and failure of each test. See the harness field if you want to use a different harness or test strategy.

Note: There is another special style of test in Cargo: documentation tests. They are handled by rustdoc and have a slightly different execution model. For more information, please see cargo test.

Integration tests

Files located under the tests directory are integration tests. When you run cargo test, Cargo will compile each of these files as a separate crate, and execute them.

Integration tests can use the public API of the package’s library. They are also linked with the [dependencies] and [dev-dependencies] defined in Cargo.toml.

If you want to share code among multiple integration tests, you can place it in a separate module such as tests/common/mod.rs and then put mod common; in each test to import it.

Each integration test results in a separate executable binary, and cargo test will run them serially. In some cases this can be inefficient, as it can take longer to compile, and may not make full use of multiple CPUs when running the tests. If you have a lot of integration tests, you may want to consider creating a single integration test, and split the tests into multiple modules. The libtest harness will automatically find all of the #[test] annotated functions and run them in parallel. You can pass module names to cargo test to only run the tests within that module.

Binary targets are automatically built if there is an integration test. This allows an integration test to execute the binary to exercise and test its behavior. The CARGO_BIN_EXE_<name> environment variable is set when the integration test is built so that it can use the env macro to locate the executable.

Benchmarks

Benchmarks provide a way to test the performance of your code using the cargo bench command. They follow the same structure as tests, with each benchmark function annotated with the #[bench] attribute. Similarly to tests:

• Benchmarks are placed in the benches directory.
• Benchmark functions defined in libraries and binaries have access to the private API within the target they are defined in. Benchmarks in the benches directory may use the public API.
• The bench field can be used to define which targets are benchmarked by default.
• The harness field can be used to disable the built-in harness.

Note: The #[bench] attribute is currently unstable and only available on the nightly channel. There are some packages available on crates.io that may help with running benchmarks on the stable channel, such as Criterion.

Configuring a target

All of the [lib], [[bin]], [[example]], [[test]], and [[bench]] sections in Cargo.toml support similar configuration for specifying how a target should be built. The double-bracket sections like [[bin]] are array-of-table of TOML, which means you can write more than one [[bin]] section to make several executables in your crate. You can only specify one library, so [lib] is a normal TOML table.

The following is an overview of the TOML settings for each target, with each field described in detail below.

[lib]
name = "foo"           # The name of the target.
path = "src/lib.rs"    # The source file of the target.
test = true            # Is tested by default.
doctest = true         # Documentation examples are tested by default.
bench = true           # Is benchmarked by default.
doc = true             # Is documented by default.
proc-macro = false     # Set to `true` for a proc-macro library.
harness = true         # Use libtest harness.
edition = "2015"       # The edition of the target.
crate-type = ["lib"]   # The crate types to generate.
required-features = [] # Features required to build this target (N/A for lib).

The name field

The name field specifies the name of the target, which corresponds to the filename of the artifact that will be generated. For a library, this is the crate name that dependencies will use to reference it.

For the library target, this defaults to the name of the package , with any dashes replaced with underscores. For the default binary (src/main.rs), it also defaults to the name of the package, with no replacement for dashes. For auto discovered targets, it defaults to the directory or file name.

This is required for all targets except [lib].

The path field

The path field specifies where the source for the crate is located, relative to the Cargo.toml file.

If not specified, the inferred path is used based on the target name.

The test field

The test field indicates whether or not the target is tested by default by cargo test. The default is true for lib, bins, and tests.

Note: Examples are built by cargo test by default to ensure they continue to compile, but they are not tested by default. Setting test = true for an example will also build it as a test and run any #[test] functions defined in the example.

The doctest field

The doctest field indicates whether or not documentation examples are tested by default by cargo test. This is only relevant for libraries, it has no effect on other sections. The default is true for the library.

The bench field

The bench field indicates whether or not the target is benchmarked by default by cargo bench. The default is true for lib, bins, and benchmarks.

The doc field

The doc field indicates whether or not the target is included in the documentation generated by cargo doc by default. The default is true for libraries and binaries.

Note: The binary will be skipped if its name is the same as the lib target.

The plugin field

This option is deprecated and unused.

The proc-macro field

The proc-macro field indicates that the library is a procedural macro (reference). This is only valid for the [lib] target.

The harness field

The harness field indicates that the --test flag will be passed to rustc which will automatically include the libtest library which is the driver for collecting and running tests marked with the #[test] attribute or benchmarks with the #[bench] attribute. The default is true for all targets.

If set to false, then you are responsible for defining a main() function to run tests and benchmarks.

Tests have the cfg(test) conditional expression enabled whether or not the harness is enabled.

The edition field

The edition field defines the Rust edition the target will use. If not specified, it defaults to the edition field for the [package]. This field should usually not be set, and is only intended for advanced scenarios such as incrementally transitioning a large package to a new edition.

The crate-type field

The crate-type field defines the crate types that will be generated by the target. It is an array of strings, allowing you to specify multiple crate types for a single target. This can only be specified for libraries and examples. Binaries, tests, and benchmarks are always the “bin” crate type. The defaults are:

The available options are bin, lib, rlib, dylib, cdylib, staticlib, and proc-macro. You can read more about the different crate types in the Rust Reference Manual.

The required-features field

The required-features field specifies which features the target needs in order to be built. If any of the required features are not enabled, the target will be skipped. This is only relevant for the [[bin]], [[bench]], [[test]], and [[example]] sections, it has no effect on [lib].

[features]
# ...
postgres = []
sqlite = []
tools = []

[[bin]]
name = "my-pg-tool"
required-features = ["postgres", "tools"]

Target auto-discovery

By default, Cargo automatically determines the targets to build based on the layout of the files on the filesystem. The target configuration tables, such as [lib], [[bin]], [[test]], [[bench]], or [[example]], can be used to add additional targets that don’t follow the standard directory layout.

The automatic target discovery can be disabled so that only manually configured targets will be built. Setting the keys autolib, autobins, autoexamples, autotests, or autobenches to false in the [package] section will disable auto-discovery of the corresponding target type.

[package]
# ...
autolib = false
autobins = false
autoexamples = false
autotests = false
autobenches = false

Disabling automatic discovery should only be needed for specialized situations. For example, if you have a library where you want a module named bin, this would present a problem because Cargo would usually attempt to compile anything in the bin directory as an executable. Here is a sample layout of this scenario:

├── Cargo.toml
└── src
    ├── lib.rs
    └── bin
        └── mod.rs

To prevent Cargo from inferring src/bin/mod.rs as an executable, set autobins = false in Cargo.toml to disable auto-discovery:

[package]
# …
autobins = false

Note: For packages with the 2015 edition, the default for auto-discovery is false if at least one target is manually defined in Cargo.toml. Beginning with the 2018 edition, the default is always true.

MSRV: Respected as of 1.27 for autobins, autoexamples, autotests, and autobenches

MSRV: Respected as of 1.83 for autolib

Rust Version

The rust-version field is an optional key that tells cargo what version of the Rust toolchain you support for your package.

[package]
# ...
rust-version = "1.56"

The Rust version must be a bare version number with at least one component; it cannot include semver operators or pre-release identifiers. Compiler pre-release identifiers such as -nightly will be ignored while checking the Rust version.

MSRV: Respected as of 1.56

Uses

Diagnostics:

When your package is compiled on an unsupported toolchain, Cargo will provide clearer diagnostics about the insufficient toolchain version rather than reporting invalid syntax or missing functionality in the standard library. This affects all Cargo targets in the package, including binaries, examples, test suites, benchmarks, etc.

Development aid:

cargo add will auto-select the dependency’s version requirement to be the latest version compatible with your rust-version. If that isn’t the latest version, cargo add will inform users so they can make the choice on whether to keep it or update your rust-version.

The resolver may take Rust version into account when picking dependencies.

Other tools may also take advantage of it, like cargo clippy’s incompatible_msrv lint.

Note: The rust-version may be ignored using the --ignore-rust-version option.

Support Expectations

These are general expectations; some packages may document when they do not follow these.

Complete:

All functionality, including binaries and API, are available on the supported Rust versions under every feature.

Verified:

A package’s functionality is verified on its supported Rust versions, including automated testing. See also our Rust version CI guide.

Patchable:

When licenses allow it, users can override their local dependency with a fork of your package. In this situation, Cargo may load the entire workspace for the patched dependency which should work on the supported Rust versions, even if other packages in the workspace have different supported Rust versions.

Dependency Support:

In support of the above, it is expected that each dependency’s version-requirement supports at least one version compatible with your rust-version. However, it is not expected that the dependency specification excludes versions incompatible with your rust-version. In fact, supporting both allows you to balance the needs of users that support older Rust versions with those that don’t.

Setting and Updating Rust Version

What Rust versions to support is a trade off between

• Costs for the maintainer in not using newer features of the Rust toolchain or their dependencies
• Costs to users who would benefit from a package using newer features of a toolchain, e.g. reducing build times by migrating to a feature in the standard library from a polyfill
• Availability of a package to users supporting older Rust versions

Note: Changing rust-version is assumed to be a minor incompatibility

Recommendation: Choose a policy for what Rust versions to support and when that is changed so users can compare it with their own policy and, if it isn’t compatible, decide whether the loss of general improvements or the risk of a blocking bug that won’t be fixed is acceptable or not.

The simplest policy to support is to always use the latest Rust version.

Depending on your risk profile, the next simplest approach is to continue to support old major or minor versions of your package that support older Rust versions.

Selecting supported Rust versions

Users of your package are most likely to track their supported Rust versions to:

• Their Rust toolchain vendor’s support policy, e.g. The Rust Project or a Linux distribution
  • Note: the Rust Project only offers bug fixes and security updates for the latest version.
• A fixed schedule for users to re-verify their packages with the new toolchain, e.g. the first release of the year, every

In addition, users are unlikely to be using the new Rust version immediately but need time to notice and re-verify or might not be aligned on the exact same schedule..

Example version policies:

• “N-2”, meaning “latest version with a 2 release grace window for updating”
• Every even release with a 2 release grace window for updating
• Every version from this calendar year with a one year grace window for updating

Note: To find the minimum rust-version compatible with your project as-is, you can use third-party tools like cargo-msrv.

Update timeline

When your policy specifies you no longer need to support a Rust version, you can update rust-version immediately or when needed.

By allowing rust-version to drift from your policy, you offer users more of a grace window for upgrading. However, this is too unpredictable to be relied on for aligning with the Rust version users track.

The further rust-version drifts from your specified policy, the more likely users are to infer a policy you did not intend, leading to frustration at the unmet expectations.

When drift is allowed, there is the question of what is “justifiable enough” to drop supported Versions. Each person can come to a reasonably different justification; working through that discussion can be frustrating for the involved parties. This will disempower those who would want to avoid that type of conflict, which is particularly the case for new or casual contributors who either feel that they are not in a position to raise the question or that the conflict may hurt the chance of their change being merged.

Multiple Policies in a Workspace

Cargo allows supporting multiple policies within one workspace.

Verifying specific packages under specific Rust versions can get complicated. Tools like cargo-hack can help.

For any dependency shared across policies, the lowest common versions must be used as Cargo unifies SemVer-compatible versions, potentially limiting access to features of the shared dependency for the workspace member with the higher rust-version.

To allow users to patch a dependency on one of your workspace members, every package in the workspace would need to be loadable in the oldest Rust version supported by the workspace.

When using incompatible-rust-versions = "fallback", the Rust version of one package can affect dependency versions selected for another package with a different Rust version. See the resolver chapter for more details.

One or More Policies

One way to mitigate the downsides of supporting older Rust versions is to apply your policy to older major or minor versions of your package that you continue to support. You likely still need a policy for what Rust versions the development branch support compared to the release branches for those major or minor versions.

Only updating the development branch when “needed”’ can help reduce the number of supported release branches.

There is the question of what can be backported into these release branches. By backporting new functionality between minor versions, the next available version would be missing it which could be considered a breaking change, violating SemVer. Backporting changes also comes with the risk of introducing bugs.

Supporting older versions comes at a cost. This cost is dependent on the risk and impact of bugs within the package and what is acceptable for backporting. Creating the release branches on-demand and putting the backport burden on the community are ways to balance this cost.

There is not yet a way for dependency management tools to report that a non-latest version is still supported, shifting the responsibility to users to notice this in documentation.

For example, a Rust version support policy could look like:

• The development branch tracks to the latest stable release from the Rust Project, updated when needed
  • The minor version will be raised when changing rust-version
• The project supports every version for this calendar year, with another year grace window
  • The last minor version that supports a supported Rust version will receive community provided bug fixes
  • Fixes must be backported to all supported minor releases between the development branch and the needed supported Rust version

Workspaces

A workspace is a collection of one or more packages, called workspace members, that are managed together.

The key points of workspaces are:

• Common commands can run across all workspace members, like cargo check --workspace.
• All packages share a common Cargo.lock file which resides in the workspace root.
• All packages share a common output directory, which defaults to a directory named target in the workspace root.
• Sharing package metadata, like with workspace.package.
• The [patch], [replace] and [profile.*] sections in Cargo.toml are only recognized in the root manifest, and ignored in member crates’ manifests.

The root Cargo.toml of a workspace supports the following sections:

• [workspace] — Defines a workspace.
  • resolver — Sets the dependency resolver to use.
  • members — Packages to include in the workspace.
  • exclude — Packages to exclude from the workspace.
  • default-members — Packages to operate on when a specific package wasn’t selected.
  • package — Keys for inheriting in packages.
  • dependencies — Keys for inheriting in package dependencies.
  • lints — Keys for inheriting in package lints.
  • metadata — Extra settings for external tools.
• [patch] — Override dependencies.
• [replace] — Override dependencies (deprecated).
• [profile] — Compiler settings and optimizations.

The [workspace] section

To create a workspace, you add the [workspace] table to a Cargo.toml:

[workspace]
# ...

At minimum, a workspace has to have a member, either with a root package or as a virtual manifest.

Root package

If the [workspace] section is added to a Cargo.toml that already defines a [package], the package is the root package of the workspace. The workspace root is the directory where the workspace’s Cargo.toml is located.

[workspace]

[package]
name = "hello_world" # the name of the package
version = "0.1.0"    # the current version, obeying semver
authors = ["Alice <a@example.com>", "Bob <b@example.com>"]

Virtual workspace

Alternatively, a Cargo.toml file can be created with a [workspace] section but without a [package] section. This is called a virtual manifest. This is typically useful when there isn’t a “primary” package, or you want to keep all the packages organized in separate directories.

# [PROJECT_DIR]/Cargo.toml
[workspace]
members = ["hello_world"]
resolver = "2"

# [PROJECT_DIR]/hello_world/Cargo.toml
[package]
name = "hello_world" # the name of the package
version = "0.1.0"    # the current version, obeying semver
edition = "2021"     # the edition, will have no effect on a resolver used in the workspace
authors = ["Alice <a@example.com>", "Bob <b@example.com>"]

By having a workspace without a root package,

• resolver must be set explicitly in virtual workspaces as they have no package.edition to infer it from resolver version.
• Commands run in the workspace root will run against all workspace members by default, see default-members.

The members and exclude fields

The members and exclude fields define which packages are members of the workspace:

[workspace]
members = ["member1", "path/to/member2", "crates/*"]
exclude = ["crates/foo", "path/to/other"]

All path dependencies residing in the workspace directory automatically become members. Additional members can be listed with the members key, which should be an array of strings containing directories with Cargo.toml files.

The members list also supports globs to match multiple paths, using typical filename glob patterns like * and ?.

The exclude key can be used to prevent paths from being included in a workspace. This can be useful if some path dependencies aren’t desired to be in the workspace at all, or using a glob pattern and you want to remove a directory.

When inside a subdirectory within the workspace, Cargo will automatically search the parent directories for a Cargo.toml file with a [workspace] definition to determine which workspace to use. The package.workspace manifest key can be used in member crates to point at a workspace’s root to override this automatic search. The manual setting can be useful if the member is not inside a subdirectory of the workspace root.

Package selection

In a workspace, package-related Cargo commands like cargo build can use the -p / --package or --workspace command-line flags to determine which packages to operate on. If neither of those flags are specified, Cargo will use the package in the current working directory. However, if the current directory is a workspace root, the default-members will be used.

The default-members field

The default-members field specifies paths of members to operate on when in the workspace root and the package selection flags are not used:

[workspace]
members = ["path/to/member1", "path/to/member2", "path/to/member3/*"]
default-members = ["path/to/member2", "path/to/member3/foo"]

Note: when a root package is present, you can only operate on it using --package and --workspace flags.

When unspecified, the root package will be used. In the case of a virtual workspace, all members will be used (as if --workspace were specified on the command-line).

The package table

The workspace.package table is where you define keys that can be inherited by members of a workspace. These keys can be inherited by defining them in the member package with {key}.workspace = true.

Keys that are supported:

• license-file and readme are relative to the workspace root
• include and exclude are relative to your package root

Example:

# [PROJECT_DIR]/Cargo.toml
[workspace]
members = ["bar"]

[workspace.package]
version = "1.2.3"
authors = ["Nice Folks"]
description = "A short description of my package"
documentation = "https://example.com/bar"

# [PROJECT_DIR]/bar/Cargo.toml
[package]
name = "bar"
version.workspace = true
authors.workspace = true
description.workspace = true
documentation.workspace = true

MSRV: Requires 1.64+

The dependencies table

The workspace.dependencies table is where you define dependencies to be inherited by members of a workspace.

Specifying a workspace dependency is similar to package dependencies except:

• Dependencies from this table cannot be declared as optional
• features declared in this table are additive with the features from [dependencies]

You can then inherit the workspace dependency as a package dependency

Example:

# [PROJECT_DIR]/Cargo.toml
[workspace]
members = ["bar"]

[workspace.dependencies]
cc = "1.0.73"
rand = "0.8.5"
regex = { version = "1.6.0", default-features = false, features = ["std"] }

# [PROJECT_DIR]/bar/Cargo.toml
[package]
name = "bar"
version = "0.2.0"

[dependencies]
regex = { workspace = true, features = ["unicode"] }

[build-dependencies]
cc.workspace = true

[dev-dependencies]
rand.workspace = true

MSRV: Requires 1.64+

The lints table

The workspace.lints table is where you define lint configuration to be inherited by members of a workspace.

Specifying a workspace lint configuration is similar to package lints.

Example:

# [PROJECT_DIR]/Cargo.toml
[workspace]
members = ["crates/*"]

[workspace.lints.rust]
unsafe_code = "forbid"

# [PROJECT_DIR]/crates/bar/Cargo.toml
[package]
name = "bar"
version = "0.1.0"

[lints]
workspace = true

MSRV: Respected as of 1.74

The metadata table

The workspace.metadata table is ignored by Cargo and will not be warned about. This section can be used for tools that would like to store workspace configuration in Cargo.toml. For example:

[workspace]
members = ["member1", "member2"]

[workspace.metadata.webcontents]
root = "path/to/webproject"
tool = ["npm", "run", "build"]
# ...

There is a similar set of tables at the package level at package.metadata. While cargo does not specify a format for the content of either of these tables, it is suggested that external tools may wish to use them in a consistent fashion, such as referring to the data in workspace.metadata if data is missing from package.metadata, if that makes sense for the tool in question.

Specifying Dependencies

Your crates can depend on other libraries from crates.io or other registries, git repositories, or subdirectories on your local file system. You can also temporarily override the location of a dependency — for example, to be able to test out a bug fix in the dependency that you are working on locally. You can have different dependencies for different platforms, and dependencies that are only used during development. Let’s take a look at how to do each of these.

Specifying dependencies from crates.io

Cargo is configured to look for dependencies on crates.io by default. Only the name and a version string are required in this case. In the cargo guide, we specified a dependency on the time crate:

[dependencies]
time = "0.1.12"

The version string "0.1.12" is called a version requirement. It specifies a range of versions that can be selected from when resolving dependencies. In this case, "0.1.12" represents the version range >=0.1.12, <0.2.0. An update is allowed if it is within that range. In this case, if we ran cargo update time, cargo should update us to version 0.1.13 if it is the latest 0.1.z release, but would not update us to 0.2.0.

Version requirement syntax

Default requirements

Default requirements specify a minimum version with the ability to update to SemVer compatible versions. Versions are considered compatible if their left-most non-zero major/minor/patch component is the same. This is different from SemVer which considers all pre-1.0.0 packages to be incompatible.

1.2.3 is an example of a default requirement.

1.2.3  :=  >=1.2.3, <2.0.0
1.2    :=  >=1.2.0, <2.0.0
1      :=  >=1.0.0, <2.0.0
0.2.3  :=  >=0.2.3, <0.3.0
0.2    :=  >=0.2.0, <0.3.0
0.0.3  :=  >=0.0.3, <0.0.4
0.0    :=  >=0.0.0, <0.1.0
0      :=  >=0.0.0, <1.0.0

Caret requirements

Caret requirements are the default version requirement strategy. This version strategy allows SemVer compatible updates. They are specified as version requirements with a leading caret (^).

^1.2.3 is an example of a caret requirement.

Leaving off the caret is a simplified equivalent syntax to using caret requirements. While caret requirements are the default, it is recommended to use the simplified syntax when possible.

log = "^1.2.3" is exactly equivalent to log = "1.2.3".

Tilde requirements

Tilde requirements specify a minimal version with some ability to update. If you specify a major, minor, and patch version or only a major and minor version, only patch-level changes are allowed. If you only specify a major version, then minor- and patch-level changes are allowed.

~1.2.3 is an example of a tilde requirement.

~1.2.3  := >=1.2.3, <1.3.0
~1.2    := >=1.2.0, <1.3.0
~1      := >=1.0.0, <2.0.0

Wildcard requirements

Wildcard requirements allow for any version where the wildcard is positioned.

*, 1.* and 1.2.* are examples of wildcard requirements.

*     := >=0.0.0
1.*   := >=1.0.0, <2.0.0
1.2.* := >=1.2.0, <1.3.0

Note: crates.io does not allow bare * versions.

Comparison requirements

Comparison requirements allow manually specifying a version range or an exact version to depend on.

Here are some examples of comparison requirements:

>= 1.2.0
> 1
< 2
= 1.2.3

Multiple version requirements

As shown in the examples above, multiple version requirements can be separated with a comma, e.g., >= 1.2, < 1.5.

Pre-releases

Version requirements exclude pre-release versions, such as 1.0.0-alpha, unless specifically asked for. For example, if 1.0.0-alpha of package foo is published, then a requirement of foo = "1.0" will not match, and will return an error. The pre-release must be specified, such as foo = "1.0.0-alpha". Similarly cargo install will avoid pre-releases unless explicitly asked to install one.

Cargo allows “newer” pre-releases to be used automatically. For example, if 1.0.0-beta is published, then a requirement foo = "1.0.0-alpha" will allow updating to the beta version. Note that this only works on the same release version, foo = "1.0.0-alpha" will not allow updating to foo = "1.0.1-alpha" or foo = "1.0.1-beta".

Cargo will also upgrade automatically to semver-compatible released versions from prereleases. The requirement foo = "1.0.0-alpha" will allow updating to foo = "1.0.0" as well as foo = "1.2.0".

Beware that pre-release versions can be unstable, and as such care should be taken when using them. Some projects may choose to publish breaking changes between pre-release versions. It is recommended to not use pre-release dependencies in a library if your library is not also a pre-release. Care should also be taken when updating your Cargo.lock, and be prepared if a pre-release update causes issues.

Version metadata

Version metadata, such as 1.0.0+21AF26D3, is ignored and should not be used in version requirements.

Recommendation: When in doubt, use the default version requirement operator.

In rare circumstances, a package with a “public dependency” (re-exports the dependency or interoperates with it in its public API) that is compatible with multiple semver-incompatible versions (e.g. only uses a simple type that hasn’t changed between releases, like an Id) may support users choosing which version of the “public dependency” to use. In this case, a version requirement like ">=0.4, <2" may be of interest. However users of the package will likely run into errors and need to manually select a version of the “public dependency” via cargo update if they also depend on it as Cargo might pick different versions of the “public dependency” when resolving dependency versions (see #10599).

Avoid constraining the upper bound of a version to be anything less than the next semver incompatible version (e.g. avoid ">=2.0, <2.4") as other packages in the dependency tree may require a newer version, leading to an unresolvable error (see #9029). Consider whether controlling the version in your Cargo.lock would be more appropriate.

In some instances this won’t matter or the benefits might outweigh the cost, including:

• When no one else depends on your package e.g. it only has a [[bin]]
• When depending on a pre-release package and wishing to avoid breaking changes then a fully specified "=1.2.3-alpha.3" might be warranted (see #2222)
• When a library re-exports a proc-macro but the proc-macro generates code that calls into the re-exporting library then a fully specified =1.2.3 might be warranted to ensure the proc-macro isn’t newer than the re-exporting library and generating code that uses parts of the API that don’t exist within the current version

Specifying dependencies from other registries

To specify a dependency from a registry other than crates.io set the registry key to the name of the registry to use:

[dependencies]
some-crate = { version = "1.0", registry = "my-registry" }

where my-registry is the registry name configured in .cargo/config.toml file. See the registries documentation for more information.

Note: crates.io does not allow packages to be published with dependencies on code published outside of crates.io.

Specifying dependencies from git repositories

To depend on a library located in a git repository, the minimum information you need to specify is the location of the repository with the git key:

[dependencies]
regex = { git = "https://github.com/rust-lang/regex.git" }

Cargo fetches the git repository at that location and traverses the file tree to find Cargo.toml file for the requested crate anywhere inside the git repository. For example, regex-lite and regex-syntax are members of rust-lang/regex repo and can be referred to by the repo’s root URL (https://github.com/rust-lang/regex.git) regardless of where in the file tree they reside.

regex-lite   = { git = "https://github.com/rust-lang/regex.git" }
regex-syntax = { git = "https://github.com/rust-lang/regex.git" }

The above rule does not apply to path dependencies.

Choice of commit

Cargo assumes that we intend to use the latest commit on the default branch to build our package if we only specify the repo URL, as in the examples above.

You can combine the git key with the rev, tag, or branch keys to be more specific about which commit to use. Here’s an example of using the latest commit on a branch named next:

[dependencies]
regex = { git = "https://github.com/rust-lang/regex.git", branch = "next" }

Anything that is not a branch or a tag falls under rev key. This can be a commit hash like rev = "4c59b707", or a named reference exposed by the remote repository such as rev = "refs/pull/493/head".

What references are available for the rev key varies by where the repo is hosted.
GitHub exposes a reference to the most recent commit of every pull request as in the example above. Other git hosts may provide something equivalent under a different naming scheme.

More git dependency examples:

# .git suffix can be omitted if the host accepts such URLs - both examples work the same
regex = { git = "https://github.com/rust-lang/regex" }
regex = { git = "https://github.com/rust-lang/regex.git" }

# a commit with a particular tag
regex = { git = "https://github.com/rust-lang/regex.git", tag = "1.10.3" }

# a commit by its SHA1 hash
regex = { git = "https://github.com/rust-lang/regex.git", rev = "0c0990399270277832fbb5b91a1fa118e6f63dba" }

# HEAD commit of PR 493
regex = { git = "https://github.com/rust-lang/regex.git", rev = "refs/pull/493/head" }

# INVALID EXAMPLES

# specifying the commit after # ignores the commit ID and generates a warning
regex = { git = "https://github.com/rust-lang/regex.git#4c59b70" }

# git and path cannot be used at the same time
regex = { git = "https://github.com/rust-lang/regex.git#4c59b70", path = "../regex" }

Cargo locks the commits of git dependencies in Cargo.lock file at the time of their addition and checks for updates only when you run cargo update command.

The role of the version key

The version key always implies that the package is available in a registry, regardless of the presence of git or path keys.

The version key does not affect which commit is used when Cargo retrieves the git dependency, but Cargo checks the version information in the dependency’s Cargo.toml file against the version key and raises an error if the check fails.

In this example, Cargo retrieves the HEAD commit of the branch called next from Git and checks if the crate’s version is compatible with version = "1.10.3":

[dependencies]
regex = { version = "1.10.3", git = "https://github.com/rust-lang/regex.git", branch = "next" }

version, git, and path keys are considered separate locations for resolving the dependency. See Multiple locations section below for detailed explanations.

Note: crates.io does not allow packages to be published with dependencies on code published outside of crates.io itself (dev-dependencies are ignored). See the Multiple locations section for a fallback alternative for git and path dependencies.

Accessing private Git repositories

See Git Authentication for help with Git authentication for private repos.

Specifying path dependencies

Over time, our hello_world package from the guide has grown significantly in size! It’s gotten to the point that we probably want to split out a separate crate for others to use. To do this Cargo supports path dependencies which are typically sub-crates that live within one repository. Let’s start by making a new crate inside of our hello_world package:

# inside of hello_world/
$ cargo new hello_utils

This will create a new folder hello_utils inside of which a Cargo.toml and src folder are ready to be configured. To tell Cargo about this, open up hello_world/Cargo.toml and add hello_utils to your dependencies:

[dependencies]
hello_utils = { path = "hello_utils" }

This tells Cargo that we depend on a crate called hello_utils which is found in the hello_utils folder, relative to the Cargo.toml file it’s written in.

The next cargo build will automatically build hello_utils and all of its dependencies.

No local path traversal

The local paths must point to the exact folder with the dependency’s Cargo.toml. Unlike with git dependencies, Cargo does not traverse local paths. For example, if regex-lite and regex-syntax are members of a locally cloned rust-lang/regex repo, they have to be referred to by the full path:

# git key accepts the repo root URL and Cargo traverses the tree to find the crate
[dependencies]
regex-lite   = { git = "https://github.com/rust-lang/regex.git" }
regex-syntax = { git = "https://github.com/rust-lang/regex.git" }

# path key requires the member name to be included in the local path
[dependencies]
regex-lite   = { path = "../regex/regex-lite" }
regex-syntax = { path = "../regex/regex-syntax" }

Local paths in published crates

Crates that use dependencies specified with only a path are not permitted on crates.io.

If we wanted to publish our hello_world crate, we would need to publish a version of hello_utils to crates.io as a separate crate and specify its version in the dependencies line of hello_world:

[dependencies]
hello_utils = { path = "hello_utils", version = "0.1.0" }

The use of path and version keys together is explained in the Multiple locations section.

Note: crates.io does not allow packages to be published with dependencies on code outside of crates.io, except for dev-dependencies. See the Multiple locations section for a fallback alternative for git and path dependencies.

Multiple locations

It is possible to specify both a registry version and a git or path location. The git or path dependency will be used locally (in which case the version is checked against the local copy), and when published to a registry like crates.io, it will use the registry version. Other combinations are not allowed. Examples:

[dependencies]
# Uses `my-bitflags` when used locally, and uses
# version 1.0 from crates.io when published.
bitflags = { path = "my-bitflags", version = "1.0" }

# Uses the given git repo when used locally, and uses
# version 1.0 from crates.io when published.
smallvec = { git = "https://github.com/servo/rust-smallvec.git", version = "1.0" }

# N.B. that if a version doesn't match, Cargo will fail to compile!

One example where this can be useful is when you have split up a library into multiple packages within the same workspace. You can then use path dependencies to point to the local packages within the workspace to use the local version during development, and then use the crates.io version once it is published. This is similar to specifying an override, but only applies to this one dependency declaration.

Platform specific dependencies

Platform-specific dependencies take the same format, but are listed under a target section. Normally Rust-like #[cfg] syntax will be used to define these sections:

[target.'cfg(windows)'.dependencies]
winhttp = "0.4.0"

[target.'cfg(unix)'.dependencies]
openssl = "1.0.1"

[target.'cfg(target_arch = "x86")'.dependencies]
native-i686 = { path = "native/i686" }

[target.'cfg(target_arch = "x86_64")'.dependencies]
native-x86_64 = { path = "native/x86_64" }

Like with Rust, the syntax here supports the not, any, and all operators to combine various cfg name/value pairs.

If you want to know which cfg targets are available on your platform, run rustc --print=cfg from the command line. If you want to know which cfg targets are available for another platform, such as 64-bit Windows, run rustc --print=cfg --target=x86_64-pc-windows-msvc.

Unlike in your Rust source code, you cannot use [target.'cfg(feature = "fancy-feature")'.dependencies] to add dependencies based on optional features. Use the [features] section instead:

[dependencies]
foo = { version = "1.0", optional = true }
bar = { version = "1.0", optional = true }

[features]
fancy-feature = ["foo", "bar"]

The same applies to cfg(debug_assertions), cfg(test) and cfg(proc_macro). These values will not work as expected and will always have the default value returned by rustc --print=cfg. There is currently no way to add dependencies based on these configuration values.

In addition to #[cfg] syntax, Cargo also supports listing out the full target the dependencies would apply to:

[target.x86_64-pc-windows-gnu.dependencies]
winhttp = "0.4.0"

[target.i686-unknown-linux-gnu.dependencies]
openssl = "1.0.1"

Custom target specifications

If you’re using a custom target specification (such as --target foo/bar.json), use the base filename without the .json extension:

[target.bar.dependencies]
winhttp = "0.4.0"

[target.my-special-i686-platform.dependencies]
openssl = "1.0.1"
native = { path = "native/i686" }

Note: Custom target specifications are not usable on the stable channel.

Development dependencies

You can add a [dev-dependencies] section to your Cargo.toml whose format is equivalent to [dependencies]:

[dev-dependencies]
tempdir = "0.3"

Dev-dependencies are not used when compiling a package for building, but are used for compiling tests, examples, and benchmarks.

These dependencies are not propagated to other packages which depend on this package.

You can also have target-specific development dependencies by using dev-dependencies in the target section header instead of dependencies. For example:

[target.'cfg(unix)'.dev-dependencies]
mio = "0.0.1"

Note: When a package is published, only dev-dependencies that specify a version will be included in the published crate. For most use cases, dev-dependencies are not needed when published, though some users (like OS packagers) may want to run tests within a crate, so providing a version if possible can still be beneficial.

Build dependencies

You can depend on other Cargo-based crates for use in your build scripts. Dependencies are declared through the build-dependencies section of the manifest:

[build-dependencies]
cc = "1.0.3"

You can also have target-specific build dependencies by using build-dependencies in the target section header instead of dependencies. For example:

[target.'cfg(unix)'.build-dependencies]
cc = "1.0.3"

In this case, the dependency will only be built when the host platform matches the specified target.

The build script does not have access to the dependencies listed in the dependencies or dev-dependencies section. Build dependencies will likewise not be available to the package itself unless listed under the dependencies section as well. A package itself and its build script are built separately, so their dependencies need not coincide. Cargo is kept simpler and cleaner by using independent dependencies for independent purposes.

Choosing features

If a package you depend on offers conditional features, you can specify which to use:

[dependencies.awesome]
version = "1.3.5"
default-features = false # do not include the default features, and optionally
                         # cherry-pick individual features
features = ["secure-password", "civet"]

More information about features can be found in the features chapter.

Renaming dependencies in Cargo.toml

When writing a [dependencies] section in Cargo.toml the key you write for a dependency typically matches up to the name of the crate you import from in the code. For some projects, though, you may wish to reference the crate with a different name in the code regardless of how it’s published on crates.io. For example you may wish to:

• Avoid the need to use foo as bar in Rust source.
• Depend on multiple versions of a crate.
• Depend on crates with the same name from different registries.

To support this Cargo supports a package key in the [dependencies] section of which package should be depended on:

[package]
name = "mypackage"
version = "0.0.1"

[dependencies]
foo = "0.1"
bar = { git = "https://github.com/example/project.git", package = "foo" }
baz = { version = "0.1", registry = "custom", package = "foo" }

In this example, three crates are now available in your Rust code:

extern crate foo; // crates.io
extern crate bar; // git repository
extern crate baz; // registry `custom`

All three of these crates have the package name of foo in their own Cargo.toml, so we’re explicitly using the package key to inform Cargo that we want the foo package even though we’re calling it something else locally. The package key, if not specified, defaults to the name of the dependency being requested.

Note that if you have an optional dependency like:

[dependencies]
bar = { version = "0.1", package = 'foo', optional = true }

you’re depending on the crate foo from crates.io, but your crate has a bar feature instead of a foo feature. That is, names of features take after the name of the dependency, not the package name, when renamed.

Enabling transitive dependencies works similarly, for example we could add the following to the above manifest:

[features]
log-debug = ['bar/log-debug'] # using 'foo/log-debug' would be an error!

Inheriting a dependency from a workspace

Dependencies can be inherited from a workspace by specifying the dependency in the workspace’s [workspace.dependencies] table. After that, add it to the [dependencies] table with workspace = true.

Along with the workspace key, dependencies can also include these keys:

• optional: Note that the[workspace.dependencies] table is not allowed to specify optional.
• features: These are additive with the features declared in the [workspace.dependencies]

Other than optional and features, inherited dependencies cannot use any other dependency key (such as version or default-features).

Dependencies in the [dependencies], [dev-dependencies], [build-dependencies], and [target."...".dependencies] sections support the ability to reference the [workspace.dependencies] definition of dependencies.

[package]
name = "bar"
version = "0.2.0"

[dependencies]
regex = { workspace = true, features = ["unicode"] }

[build-dependencies]
cc.workspace = true

[dev-dependencies]
rand = { workspace = true, optional = true }

Overriding Dependencies

The desire to override a dependency can arise through a number of scenarios. Most of them, however, boil down to the ability to work with a crate before it’s been published to crates.io. For example:

• A crate you’re working on is also used in a much larger application you’re working on, and you’d like to test a bug fix to the library inside of the larger application.
• An upstream crate you don’t work on has a new feature or a bug fix on the master branch of its git repository which you’d like to test out.
• You’re about to publish a new major version of your crate, but you’d like to do integration testing across an entire package to ensure the new major version works.
• You’ve submitted a fix to an upstream crate for a bug you found, but you’d like to immediately have your application start depending on the fixed version of the crate to avoid blocking on the bug fix getting merged.

These scenarios can be solved with the [patch] manifest section.

This chapter walks through a few different use cases, and includes details on the different ways to override a dependency.

• Example use cases
  • Testing a bugfix
  • Working with an unpublished minor version
    • Overriding repository URL
  • Prepublishing a breaking change
  • Using [patch] with multiple versions
• Reference
  • The [patch] section
  • The [replace] section
  • paths overrides

Note: See also specifying a dependency with multiple locations, which can be used to override the source for a single dependency declaration in a local package.

Testing a bugfix

Let’s say you’re working with the uuid crate but while you’re working on it you discover a bug. You are, however, quite enterprising so you decide to also try to fix the bug! Originally your manifest will look like:

[package]
name = "my-library"
version = "0.1.0"

[dependencies]
uuid = "1.0"

First thing we’ll do is to clone the uuid repository locally via:

$ git clone https://github.com/uuid-rs/uuid.git

Next we’ll edit the manifest of my-library to contain:

[patch.crates-io]
uuid = { path = "../path/to/uuid" }

Here we declare that we’re patching the source crates-io with a new dependency. This will effectively add the local checked out version of uuid to the crates.io registry for our local package.

Next up we need to ensure that our lock file is updated to use this new version of uuid so our package uses the locally checked out copy instead of one from crates.io. The way [patch] works is that it’ll load the dependency at ../path/to/uuid and then whenever crates.io is queried for versions of uuid it’ll also return the local version.

This means that the version number of the local checkout is significant and will affect whether the patch is used. Our manifest declared uuid = "1.0" which means we’ll only resolve to >= 1.0.0, < 2.0.0, and Cargo’s greedy resolution algorithm also means that we’ll resolve to the maximum version within that range. Typically this doesn’t matter as the version of the git repository will already be greater or match the maximum version published on crates.io, but it’s important to keep this in mind!

In any case, typically all you need to do now is:

$ cargo build
   Compiling uuid v1.0.0 (.../uuid)
   Compiling my-library v0.1.0 (.../my-library)
    Finished dev [unoptimized + debuginfo] target(s) in 0.32 secs

And that’s it! You’re now building with the local version of uuid (note the path in parentheses in the build output). If you don’t see the local path version getting built then you may need to run cargo update uuid --precise $version where $version is the version of the locally checked out copy of uuid.

Once you’ve fixed the bug you originally found the next thing you’ll want to do is to likely submit that as a pull request to the uuid crate itself. Once you’ve done this then you can also update the [patch] section. The listing inside of [patch] is just like the [dependencies] section, so once your pull request is merged you could change your path dependency to:

[patch.crates-io]
uuid = { git = 'https://github.com/uuid-rs/uuid.git' }

Working with an unpublished minor version

Let’s now shift gears a bit from bug fixes to adding features. While working on my-library you discover that a whole new feature is needed in the uuid crate. You’ve implemented this feature, tested it locally above with [patch], and submitted a pull request. Let’s go over how you continue to use and test it before it’s actually published.

Let’s also say that the current version of uuid on crates.io is 1.0.0, but since then the master branch of the git repository has updated to 1.0.1. This branch includes your new feature you submitted previously. To use this repository we’ll edit our Cargo.toml to look like

[package]
name = "my-library"
version = "0.1.0"

[dependencies]
uuid = "1.0.1"

[patch.crates-io]
uuid = { git = 'https://github.com/uuid-rs/uuid.git' }

Note that our local dependency on uuid has been updated to 1.0.1 as it’s what we’ll actually require once the crate is published. This version doesn’t exist on crates.io, though, so we provide it with the [patch] section of the manifest.

Now when our library is built it’ll fetch uuid from the git repository and resolve to 1.0.1 inside the repository instead of trying to download a version from crates.io. Once 1.0.1 is published on crates.io the [patch] section can be deleted.

It’s also worth noting that [patch] applies transitively. Let’s say you use my-library in a larger package, such as:

[package]
name = "my-binary"
version = "0.1.0"

[dependencies]
my-library = { git = 'https://example.com/git/my-library' }
uuid = "1.0"

[patch.crates-io]
uuid = { git = 'https://github.com/uuid-rs/uuid.git' }

Remember that [patch] is applicable transitively but can only be defined at the top level so we consumers of my-library have to repeat the [patch] section if necessary. Here, though, the new uuid crate applies to both our dependency on uuid and the my-library -> uuid dependency. The uuid crate will be resolved to one version for this entire crate graph, 1.0.1, and it’ll be pulled from the git repository.

Overriding repository URL

In case the dependency you want to override isn’t loaded from crates.io, you’ll have to change a bit how you use [patch]. For example, if the dependency is a git dependency, you can override it to a local path with:

[patch."https://github.com/your/repository"]
my-library = { path = "../my-library/path" }

And that’s it!

Prepublishing a breaking change

Let’s take a look at working with a new major version of a crate, typically accompanied with breaking changes. Sticking with our previous crates, this means that we’re going to be creating version 2.0.0 of the uuid crate. After we’ve submitted all changes upstream we can update our manifest for my-library to look like:

[dependencies]
uuid = "2.0"

[patch.crates-io]
uuid = { git = "https://github.com/uuid-rs/uuid.git", branch = "2.0.0" }

And that’s it! Like with the previous example the 2.0.0 version doesn’t actually exist on crates.io but we can still put it in through a git dependency through the usage of the [patch] section. As a thought exercise let’s take another look at the my-binary manifest from above again as well:

[package]
name = "my-binary"
version = "0.1.0"

[dependencies]
my-library = { git = 'https://example.com/git/my-library' }
uuid = "1.0"

[patch.crates-io]
uuid = { git = 'https://github.com/uuid-rs/uuid.git', branch = '2.0.0' }

Note that this will actually resolve to two versions of the uuid crate. The my-binary crate will continue to use the 1.x.y series of the uuid crate but the my-library crate will use the 2.0.0 version of uuid. This will allow you to gradually roll out breaking changes to a crate through a dependency graph without being forced to update everything all at once.

Using [patch] with multiple versions

You can patch in multiple versions of the same crate with the package key used to rename dependencies. For example let’s say that the serde crate has a bugfix that we’d like to use to its 1.* series but we’d also like to prototype using a 2.0.0 version of serde we have in our git repository. To configure this we’d do:

[patch.crates-io]
serde = { git = 'https://github.com/serde-rs/serde.git' }
serde2 = { git = 'https://github.com/example/serde.git', package = 'serde', branch = 'v2' }

The first serde = ... directive indicates that serde 1.* should be used from the git repository (pulling in the bugfix we need) and the second serde2 = ... directive indicates that the serde package should also be pulled from the v2 branch of https://github.com/example/serde. We’re assuming here that Cargo.toml on that branch mentions version 2.0.0.

Note that when using the package key the serde2 identifier here is actually ignored. We simply need a unique name which doesn’t conflict with other patched crates.

The [patch] section

The [patch] section of Cargo.toml can be used to override dependencies with other copies. The syntax is similar to the [dependencies] section:

[patch.crates-io]
foo = { git = 'https://github.com/example/foo.git' }
bar = { path = 'my/local/bar' }

[dependencies.baz]
git = 'https://github.com/example/baz.git'

[patch.'https://github.com/example/baz']
baz = { git = 'https://github.com/example/patched-baz.git', branch = 'my-branch' }

Note: The [patch] table can also be specified as a configuration option, such as in a .cargo/config.toml file or a CLI option like --config 'patch.crates-io.rand.path="rand"'. This can be useful for local-only changes that you don’t want to commit, or temporarily testing a patch.

The [patch] table is made of dependency-like sub-tables. Each key after [patch] is a URL of the source that is being patched, or the name of a registry. The name crates-io may be used to override the default registry crates.io. The first [patch] in the example above demonstrates overriding crates.io, and the second [patch] demonstrates overriding a git source.

Each entry in these tables is a normal dependency specification, the same as found in the [dependencies] section of the manifest. The dependencies listed in the [patch] section are resolved and used to patch the source at the URL specified. The above manifest snippet patches the crates-io source (e.g. crates.io itself) with the foo crate and bar crate. It also patches the https://github.com/example/baz source with a my-branch that comes from elsewhere.

Sources can be patched with versions of crates that do not exist, and they can also be patched with versions of crates that already exist. If a source is patched with a crate version that already exists in the source, then the source’s original crate is replaced.

Cargo only looks at the patch settings in the Cargo.toml manifest at the root of the workspace. Patch settings defined in dependencies will be ignored.

The [replace] section

Note: [replace] is deprecated. You should use the [patch] table instead.

This section of Cargo.toml can be used to override dependencies with other copies. The syntax is similar to the [dependencies] section:

[replace]
"foo:0.1.0" = { git = 'https://github.com/example/foo.git' }
"bar:1.0.2" = { path = 'my/local/bar' }

Each key in the [replace] table is a package ID specification, which allows arbitrarily choosing a node in the dependency graph to override (the 3-part version number is required). The value of each key is the same as the [dependencies] syntax for specifying dependencies, except that you can’t specify features. Note that when a crate is overridden the copy it’s overridden with must have both the same name and version, but it can come from a different source (e.g., git or a local path).

Cargo only looks at the replace settings in the Cargo.toml manifest at the root of the workspace. Replace settings defined in dependencies will be ignored.

paths overrides

Sometimes you’re only temporarily working on a crate and you don’t want to have to modify Cargo.toml like with the [patch] section above. For this use case Cargo offers a much more limited version of overrides called path overrides.

Path overrides are specified through .cargo/config.toml instead of Cargo.toml. Inside of .cargo/config.toml you’ll specify a key called paths:

paths = ["/path/to/uuid"]

This array should be filled with directories that contain a Cargo.toml. In this instance, we’re just adding uuid, so it will be the only one that’s overridden. This path can be either absolute or relative to the directory that contains the .cargo folder.

Path overrides are more restricted than the [patch] section, however, in that they cannot change the structure of the dependency graph. When a path replacement is used then the previous set of dependencies must all match exactly to the new Cargo.toml specification. For example this means that path overrides cannot be used to test out adding a dependency to a crate, instead [patch] must be used in that situation. As a result usage of a path override is typically isolated to quick bug fixes rather than larger changes.

Note: using a local configuration to override paths will only work for crates that have been published to crates.io. You cannot use this feature to tell Cargo how to find local unpublished crates.

Source Replacement

This document is about replacing the crate index. You can read about overriding dependencies in the overriding dependencies section of this documentation.

A source is a provider that contains crates that may be included as dependencies for a package. Cargo supports the ability to replace one source with another to express strategies such as:

• Vendoring — custom sources can be defined which represent crates on the local filesystem. These sources are subsets of the source that they’re replacing and can be checked into packages if necessary.

• Mirroring — sources can be replaced with an equivalent version which acts as a cache for crates.io itself.

Cargo has a core assumption about source replacement that the source code is exactly the same from both sources. Note that this also means that a replacement source is not allowed to have crates which are not present in the original source.

As a consequence, source replacement is not appropriate for situations such as patching a dependency or a private registry. Cargo supports patching dependencies through the usage of the [patch] key, and private registry support is described in the Registries chapter.

When using source replacement, running commands like cargo publish that need to contact the registry require passing the --registry option. This helps avoid any ambiguity about which registry to contact, and will use the authentication token for the specified registry.

Configuration

Configuration of replacement sources is done through .cargo/config.toml and the full set of available keys are:

# The `source` table is where all keys related to source-replacement
# are stored.
[source]

# Under the `source` table are a number of other tables whose keys are a
# name for the relevant source. For example this section defines a new
# source, called `my-vendor-source`, which comes from a directory
# located at `vendor` relative to the directory containing this `.cargo/config.toml`
# file
[source.my-vendor-source]
directory = "vendor"

# The crates.io default source for crates is available under the name
# "crates-io", and here we use the `replace-with` key to indicate that it's
# replaced with our source above.
#
# The `replace-with` key can also reference an alternative registry name
# defined in the `[registries]` table.
[source.crates-io]
replace-with = "my-vendor-source"

# Each source has its own table where the key is the name of the source
[source.the-source-name]

# Indicate that `the-source-name` will be replaced with `another-source`,
# defined elsewhere
replace-with = "another-source"

# Several kinds of sources can be specified (described in more detail below):
registry = "https://example.com/path/to/index"
local-registry = "path/to/registry"
directory = "path/to/vendor"

# Git sources can optionally specify a branch/tag/rev as well
git = "https://example.com/path/to/repo"
# branch = "master"
# tag = "v1.0.1"
# rev = "313f44e8"

Registry Sources

A “registry source” is one that is the same as crates.io itself. That is, it has an index served in a git repository which matches the format of the crates.io index. That repository then has configuration indicating where to download crates from.

Currently there is not an already-available project for setting up a mirror of crates.io. Stay tuned though!

Local Registry Sources

A “local registry source” is intended to be a subset of another registry source, but available on the local filesystem (aka vendoring). Local registries are downloaded ahead of time, typically sync’d with a Cargo.lock, and are made up of a set of *.crate files and an index like the normal registry is.

The primary way to manage and create local registry sources is through the cargo-local-registry subcommand, available on crates.io and can be installed with cargo install cargo-local-registry.

Local registries are contained within one directory and contain a number of *.crate files downloaded from crates.io as well as an index directory with the same format as the crates.io-index project (populated with just entries for the crates that are present).

Directory Sources

A “directory source” is similar to a local registry source where it contains a number of crates available on the local filesystem, suitable for vendoring dependencies. Directory sources are primarily managed by the cargo vendor subcommand.

Directory sources are distinct from local registries though in that they contain the unpacked version of *.crate files, making it more suitable in some situations to check everything into source control. A directory source is just a directory containing a number of other directories which contain the source code for crates (the unpacked version of *.crate files). Currently no restriction is placed on the name of each directory.

Each crate in a directory source also has an associated metadata file indicating the checksum of each file in the crate to protect against accidental modifications.

Dependency Resolution

One of Cargo’s primary tasks is to determine the versions of dependencies to use based on the version requirements specified in each package. This process is called “dependency resolution” and is performed by the “resolver”. The result of the resolution is stored in the Cargo.lock file which “locks” the dependencies to specific versions, and keeps them fixed over time. The cargo tree command can be used to visualize the result of the resolver.

Constraints and Heuristics

In many cases there is no single “best” dependency resolution. The resolver operates under various constraints and heuristics to find a generally applicable resolution. To understand how these interact, it is helpful to have a coarse understanding of how dependency resolution works.

This pseudo-code approximates what Cargo’s resolver does:

#![allow(unused)]
fn main() {
pub fn resolve(workspace: &[Package], policy: Policy) -> Option<ResolveGraph> {
    let dep_queue = Queue::new(workspace);
    let resolved = ResolveGraph::new();
    resolve_next(pkq_queue, resolved, policy)
}

fn resolve_next(dep_queue: Queue, resolved: ResolveGraph, policy: Policy) -> Option<ResolveGraph> {
    let Some(dep_spec) = policy.pick_next_dep(dep_queue) else {
        // Done
        return Some(resolved);
    };

    if let Some(resolved) = policy.try_unify_version(dep_spec, resolved.clone()) {
        return Some(resolved);
    }

    let dep_versions = dep_spec.lookup_versions()?;
    let mut dep_versions = policy.filter_versions(dep_spec, dep_versions);
    while let Some(dep_version) = policy.pick_next_version(&mut dep_versions) {
        if policy.needs_version_unification(dep_version, &resolved) {
            continue;
        }

        let mut dep_queue = dep_queue.clone();
        dep_queue.enqueue(dep_version.dependencies);
        let mut resolved = resolved.clone();
        resolved.register(dep_version);
        if let Some(resolved) = resolve_next(dep_queue, resolved) {
            return Some(resolved);
        }
    }

    // No valid solution found, backtrack and `pick_next_version`
    None
}
}

Key steps:

• Walking dependencies (pick_next_dep): The order dependencies are walked can affect how related version requirements for the same dependency get resolved, see unifying versions, and how much the resolver backtracks, affecting resolver performance,
• Unifying versions (try_unify_version, needs_version_unification): Cargo reuses versions where possible to reduce build times and allow types from common dependencies to be passed between APIs. If multiple versions would have been unified if it wasn’t for conflicts in their dependency specifications, Cargo will backtrack, erroring if no solution is found, rather than selecting multiple versions. A dependency specification or Cargo may decide that a version is undesirable, preferring to backtrack or error rather than use it.
• Preferring versions (pick_next_version): Cargo may decide that it should prefer a specific version, falling back to the next version when backtracking.

Version numbers

Generally, Cargo prefers the highest version currently available.

For example, if you had a package in the resolve graph with:

[dependencies]
bitflags = "*"

If at the time the Cargo.lock file is generated, the greatest version of bitflags is 1.2.1, then the package will use 1.2.1.

For an example of a possible exception, see Rust version.

Version requirements

Package specify what versions they support, rejecting all others, through version requirements.

For example, if you had a package in the resolve graph with:

[dependencies]
bitflags = "1.0"  # meaning `>=1.0.0,<2.0.0`

If at the time the Cargo.lock file is generated, the greatest version of bitflags is 1.2.1, then the package will use 1.2.1 because it is the greatest within the compatibility range. If 2.0.0 is published, it will still use 1.2.1 because 2.0.0 is considered incompatible.

SemVer compatibility

Cargo assumes packages follow SemVer and will unify dependency versions if they are SemVer compatible according to the Caret version requirements. If two compatible versions cannot be unified because of conflicting version requirements, Cargo will error.

See the SemVer Compatibility chapter for guidance on what is considered a “compatible” change.

Examples:

The following two packages will have their dependencies on bitflags unified because any version picked will be compatible with each other.

# Package A
[dependencies]
bitflags = "1.0"  # meaning `>=1.0.0,<2.0.0`

# Package B
[dependencies]
bitflags = "1.1"  # meaning `>=1.1.0,<2.0.0`

The following packages will error because the version requirements conflict, selecting two distinct compatible versions.

# Package A
[dependencies]
log = "=0.4.11"

# Package B
[dependencies]
log = "=0.4.8"

The following two packages will not have their dependencies on rand unified because only incompatible versions are available for each. Instead, two different versions (e.g. 0.6.5 and 0.7.3) will be resolved and built. This can lead to potential problems, see the Version-incompatibility hazards section for more details.

# Package A
[dependencies]
rand = "0.7"  # meaning `>=0.7.0,<0.8.0`

# Package B
[dependencies]
rand = "0.6"  # meaning `>=0.6.0,<0.7.0`

Generally, the following two packages will not have their dependencies unified because incompatible versions are available that satisfy the version requirements: Instead, two different versions (e.g. 0.6.5 and 0.7.3) will be resolved and built. The application of other constraints or heuristics may cause these to be unified, picking one version (e.g. 0.6.5).

# Package A
[dependencies]
rand = ">=0.6,<0.8.0"

# Package B
[dependencies]
rand = "0.6"  # meaning `>=0.6.0,<0.7.0`

Version-incompatibility hazards

When multiple versions of a crate appear in the resolve graph, this can cause problems when types from those crates are exposed by the crates using them. This is because the types and items are considered different by the Rust compiler, even if they have the same name. Libraries should take care when publishing a SemVer-incompatible version (for example, publishing 2.0.0 after 1.0.0 has been in use), particularly for libraries that are widely used.

The “semver trick” is a workaround for this problem of publishing a breaking change while retaining compatibility with older versions. The linked page goes into detail about what the problem is and how to address it. In short, when a library wants to publish a SemVer-breaking release, publish the new release, and also publish a point release of the previous version that reexports the types from the newer version.

These incompatibilities usually manifest as a compile-time error, but sometimes they will only appear as a runtime misbehavior. For example, let’s say there is a common library named foo that ends up appearing with both version 1.0.0 and 2.0.0 in the resolve graph. If downcast_ref is used on a object created by a library using version 1.0.0, and the code calling downcast_ref is downcasting to a type from version 2.0.0, the downcast will fail at runtime.

It is important to make sure that if you have multiple versions of a library that you are properly using them, especially if it is ever possible for the types from different versions to be used together. The cargo tree -d command can be used to identify duplicate versions and where they come from. Similarly, it is important to consider the impact on the ecosystem if you publish a SemVer-incompatible version of a popular library.

Rust version

To support developing software with a minimum supported Rust version, the resolver can take into account a dependency version’s compatibility with your Rust version. This is controlled by the config field resolver.incompatible-rust-versions.

With the fallback setting, the resolver will prefer packages with a Rust version that is equal to or greater than your own Rust version. For example, you are using Rust 1.85 to develop the following package:

[package]
name = "my-cli"
rust-version = "1.62"

[dependencies]
clap = "4.0"  # resolves to 4.0.32

The resolver would pick version 4.0.32 because it has a Rust version of 1.60.0.

• 4.0.0 is not picked because it is a lower version number despite it also having a Rust version of 1.60.0.
• 4.5.20 is not picked because it is incompatible with my-cli’s Rust version of 1.62 despite having a much higher version and it has a Rust version of 1.74.0 which is compatible with your 1.85 toolchain.

If a version requirement does not include a Rust version compatible dependency version, the resolver won’t error but will instead pick a version, even if its potentially suboptimal. For example, you change the dependency on clap:

[package]
name = "my-cli"
rust-version = "1.62"

[dependencies]
clap = "4.2"  # resolves to 4.5.20

No version of clap matches that version requirement that is compatible with Rust version 1.62. The resolver will then pick an incompatible version, like 4.5.20 despite it having a Rust version of 1.74.

When the resolver selects a dependency version of a package, it does not know all the workspace members that will eventually have a transitive dependency on that version and so it cannot take into account only the Rust versions relevant for that dependency. The resolver has heuristics to find a “good enough” solution when workspace members have different Rust versions. This applies even for packages in a workspace without a Rust version.

When a workspace has members with different Rust versions, the resolver may pick a lower dependency version than necessary. For example, you have the following workspace members:

[package]
name = "a"
rust-version = "1.62"

[package]
name = "b"

[dependencies]
clap = "4.2"  # resolves to 4.5.20

Though package b does not have a Rust version and could use a higher version like 4.5.20, 4.0.32 will be selected because of package a’s Rust version of 1.62.

Or the resolver may pick too high of a version. For example, you have the following workspace members:

[package]
name = "a"
rust-version = "1.62"

[dependencies]
clap = "4.2"  # resolves to 4.5.20

[package]
name = "b"

[dependencies]
clap = "4.5"  # resolves to 4.5.20

Though each package has a version requirement for clap that would meet its own Rust version, because of version unification, the resolver will need to pick one version that works in both cases and that would be a version like 4.5.20.

Features

For the purpose of generating Cargo.lock, the resolver builds the dependency graph as-if all features of all workspace members are enabled. This ensures that any optional dependencies are available and properly resolved with the rest of the graph when features are added or removed with the --features command-line flag. The resolver runs a second time to determine the actual features used when compiling a crate, based on the features selected on the command-line.

Dependencies are resolved with the union of all features enabled on them. For example, if one package depends on the im package with the serde dependency enabled and another package depends on it with the rayon dependency enabled, then im will be built with both features enabled, and the serde and rayon crates will be included in the resolve graph. If no packages depend on im with those features, then those optional dependencies will be ignored, and they will not affect resolution.

When building multiple packages in a workspace (such as with --workspace or multiple -p flags), the features of the dependencies of all of those packages are unified. If you have a circumstance where you want to avoid that unification for different workspace members, you will need to build them via separate cargo invocations.

The resolver will skip over versions of packages that are missing required features. For example, if a package depends on version ^1 of regex with the perf feature, then the oldest version it can select is 1.3.0, because versions prior to that did not contain the perf feature. Similarly, if a feature is removed from a new release, then packages that require that feature will be stuck on the older releases that contain that feature. It is discouraged to remove features in a SemVer-compatible release. Beware that optional dependencies also define an implicit feature, so removing an optional dependency or making it non-optional can cause problems, see removing an optional dependency.

Feature resolver version 2

When resolver = "2" is specified in Cargo.toml (see resolver versions below), a different feature resolver is used which uses a different algorithm for unifying features. The version "1" resolver will unify features for a package no matter where it is specified. The version "2" resolver will avoid unifying features in the following situations:

• Features for target-specific dependencies are not enabled if the target is not currently being built. For example:

  [dependencies.common]
  version = "1.0"
  features = ["f1"]
  
  [target.'cfg(windows)'.dependencies.common]
  version = "1.0"
  features = ["f2"]
  

  When building this example for a non-Windows platform, the f2 feature will not be enabled.

• Features enabled on build-dependencies or proc-macros will not be unified when those same dependencies are used as a normal dependency. For example:

  [dependencies]
  log = "0.4"
  
  [build-dependencies]
  log = {version = "0.4", features=['std']}
  

  When building the build script, the log crate will be built with the std feature. When building the library of your package, it will not enable the feature.

• Features enabled on dev-dependencies will not be unified when those same dependencies are used as a normal dependency, unless those dev-dependencies are currently being built. For example:

  [dependencies]
  serde = {version = "1.0", default-features = false}
  
  [dev-dependencies]
  serde = {version = "1.0", features = ["std"]}
  

  In this example, the library will normally link against serde without the std feature. However, when built as a test or example, it will include the std feature. For example, cargo test or cargo build --all-targets will unify these features. Note that dev-dependencies in dependencies are always ignored, this is only relevant for the top-level package or workspace members.

links

The links field is used to ensure only one copy of a native library is linked into a binary. The resolver will attempt to find a graph where there is only one instance of each links name. If it is unable to find a graph that satisfies that constraint, it will return an error.

For example, it is an error if one package depends on libgit2-sys version 0.11 and another depends on 0.12, because Cargo is unable to unify those, but they both link to the git2 native library. Due to this requirement, it is encouraged to be very careful when making SemVer-incompatible releases with the links field if your library is in common use.

Yanked versions

Yanked releases are those that are marked that they should not be used. When the resolver is building the graph, it will ignore all yanked releases unless they already exist in the Cargo.lock file or are explicitly requested by the --precise flag of cargo update (nightly only).

Dependency updates

Dependency resolution is automatically performed by all Cargo commands that need to know about the dependency graph. For example, cargo build will run the resolver to discover all the dependencies to build. After the first time it runs, the result is stored in the Cargo.lock file. Subsequent commands will run the resolver, keeping dependencies locked to the versions in Cargo.lock if it can.

If the dependency list in Cargo.toml has been modified, for example changing the version of a dependency from 1.0 to 2.0, then the resolver will select a new version for that dependency that matches the new requirements. If that new dependency introduces new requirements, those new requirements may also trigger additional updates. The Cargo.lock file will be updated with the new result. The --locked or --frozen flags can be used to change this behavior to prevent automatic updates when requirements change, and return an error instead.

cargo update can be used to update the entries in Cargo.lock when new versions are published. Without any options, it will attempt to update all packages in the lock file. The -p flag can be used to target the update for a specific package, and other flags such as --recursive or --precise can be used to control how versions are selected.

Overrides

Cargo has several mechanisms to override dependencies within the graph. The Overriding Dependencies chapter goes into detail on how to use overrides. The overrides appear as an overlay to a registry, replacing the patched version with the new entry. Otherwise, resolution is performed like normal.

Dependency kinds

There are three kinds of dependencies in a package: normal, build, and dev. For the most part these are all treated the same from the perspective of the resolver. One difference is that dev-dependencies for non-workspace members are always ignored, and do not influence resolution.

Platform-specific dependencies with the [target] table are resolved as-if all platforms are enabled. In other words, the resolver ignores the platform or cfg expression.

dev-dependency cycles

Usually the resolver does not allow cycles in the graph, but it does allow them for dev-dependencies. For example, project “foo” has a dev-dependency on “bar”, which has a normal dependency on “foo” (usually as a “path” dependency). This is allowed because there isn’t really a cycle from the perspective of the build artifacts. In this example, the “foo” library is built (which does not need “bar” because “bar” is only used for tests), and then “bar” can be built depending on “foo”, then the “foo” tests can be built linking to “bar”.

Beware that this can lead to confusing errors. In the case of building library unit tests, there are actually two copies of the library linked into the final test binary: the one that was linked with “bar”, and the one built that contains the unit tests. Similar to the issues highlighted in the Version-incompatibility hazards section, the types between the two are not compatible. Be careful when exposing types of “foo” from “bar” in this situation, since the “foo” unit tests won’t treat them the same as the local types.

If possible, try to split your package into multiple packages and restructure it so that it remains strictly acyclic.

Resolver versions

Different resolver behavior can be specified through the resolver version in Cargo.toml like this:

[package]
name = "my-package"
version = "1.0.0"
resolver = "2"

• "1" (default)
• "2" (edition = "2021" default): Introduces changes in feature unification. See the features chapter for more details.
• "3" (requires Rust 1.84+): Change the default for resolver.incompatible-rust-versions from allow to fallback

The resolver is a global option that affects the entire workspace. The resolver version in dependencies is ignored, only the value in the top-level package will be used. If using a virtual workspace, the version should be specified in the [workspace] table, for example:

[workspace]
members = ["member1", "member2"]
resolver = "2"

MSRV: Requires 1.51+

Recommendations

The following are some recommendations for setting the version within your package, and for specifying dependency requirements. These are general guidelines that should apply to common situations, but of course some situations may require specifying unusual requirements.

• Follow the SemVer guidelines when deciding how to update your version number, and whether or not you will need to make a SemVer-incompatible version change.

• Use caret requirements for dependencies, such as "1.2.3", for most situations. This ensures that the resolver can be maximally flexible in choosing a version while maintaining build compatibility.

  • Specify all three components with the version you are currently using. This helps set the minimum version that will be used, and ensures that other users won’t end up with an older version of the dependency that might be missing something that your package requires.
  • Avoid * requirements, as they are not allowed on crates.io, and they can pull in SemVer-breaking changes during a normal cargo update.
  • Avoid overly broad version requirements. For example, >=2.0.0 can pull in any SemVer-incompatible version, like version 5.0.0, which can result in broken builds in the future.
  • Avoid overly narrow version requirements if possible. For example, if you specify a tilde requirement like bar="~1.3", and another package specifies a requirement of bar="1.4", this will fail to resolve, even though minor releases should be compatible.

• Try to keep the dependency versions up-to-date with the actual minimum versions that your library requires. For example, if you have a requirement of bar="1.0.12", and then in a future release you start using new features added in the 1.1.0 release of “bar”, update your dependency requirement to bar="1.1.0".

  If you fail to do this, it may not be immediately obvious because Cargo can opportunistically choose the newest version when you run a blanket cargo update. However, if another user depends on your library, and runs cargo update your-library, it will not automatically update “bar” if it is locked in their Cargo.lock. It will only update “bar” in that situation if the dependency declaration is also updated. Failure to do so can cause confusing build errors for the user using cargo update your-library.

• If two packages are tightly coupled, then an = dependency requirement may help ensure that they stay in sync. For example, a library with a companion proc-macro library will sometimes make assumptions between the two libraries that won’t work well if the two are out of sync (and it is never expected to use the two libraries independently). The parent library can use an = requirement on the proc-macro, and re-export the macros for easy access.

• 0.0.x versions can be used for packages that are permanently unstable.

In general, the stricter you make the dependency requirements, the more likely it will be for the resolver to fail. Conversely, if you use requirements that are too loose, it may be possible for new versions to be published that will break the build.

Troubleshooting

The following illustrates some problems you may experience, and some possible solutions.

Why was a dependency included?

Say you see dependency rand in the cargo check output but don’t think it’s needed and want to understand why it’s being pulled in.

You can run

$ cargo tree --workspace --target all --all-features --invert rand
rand v0.8.5
└── ...

rand v0.8.5
└── ...

Why was that feature on this dependency enabled?

You might identify that it was an activated feature that caused rand to show up. To figure out which package activated the feature, you can add the --edges features

$ cargo tree --workspace --target all --all-features --edges features --invert rand
rand v0.8.5
└── ...

rand v0.8.5
└── ...

Unexpected dependency duplication

You see multiple instances of rand when you run

$ cargo tree --workspace --target all --all-features --duplicates
rand v0.7.3
└── ...

rand v0.8.5
└── ...

The resolver algorithm has converged on a solution that includes two copies of a dependency when one would suffice. For example:

# Package A
[dependencies]
rand = "0.7"

# Package B
[dependencies]
rand = ">=0.6"  # note: open requirements such as this are discouraged

In this example, Cargo may build two copies of the rand crate, even though a single copy at version 0.7.3 would meet all requirements. This is because the resolver’s algorithm favors building the latest available version of rand for Package B, which is 0.8.5 at the time of this writing, and that is incompatible with Package A’s specification. The resolver’s algorithm does not currently attempt to “deduplicate” in this situation.

The use of open-ended version requirements like >=0.6 is discouraged in Cargo. But, if you run into this situation, the cargo update command with the --precise flag can be used to manually remove such duplications.

Why wasn’t a newer version selected?

Say you noticed that the latest version of a dependency wasn’t selected when you ran:

$ cargo update

You can enable some extra logging to see why this happened:

$ env CARGO_LOG=cargo::core::resolver=trace cargo update

Note: Cargo log targets and levels may change over time.

SemVer-breaking patch release breaks the build

Sometimes a project may inadvertently publish a point release with a SemVer-breaking change. When users update with cargo update, they will pick up this new release, and then their build may break. In this situation, it is recommended that the project should yank the release, and either remove the SemVer-breaking change, or publish it as a new SemVer-major version increase.

If the change happened in a third-party project, if possible try to (politely!) work with the project to resolve the issue.

While waiting for the release to be yanked, some workarounds depend on the circumstances:

• If your project is the end product (such as a binary executable), just avoid updating the offending package in Cargo.lock. This can be done with the --precise flag in cargo update.
• If you publish a binary on crates.io, then you can temporarily add an = requirement to force the dependency to a specific good version.
  • Binary projects can alternatively recommend users to use the --locked flag with cargo install to use the original Cargo.lock that contains the known good version.
• Libraries may also consider publishing a temporary new release with stricter requirements that avoid the troublesome dependency. You may want to consider using range requirements (instead of =) to avoid overly-strict requirements that may conflict with other packages using the same dependency. Once the problem has been resolved, you can publish another point release that relaxes the dependency back to a caret requirement.
• If it looks like the third-party project is unable or unwilling to yank the release, then one option is to update your code to be compatible with the changes, and update the dependency requirement to set the minimum version to the new release. You will also need to consider if this is a SemVer-breaking change of your own library, for example if it exposes types from the dependency.

Features

Cargo “features” provide a mechanism to express conditional compilation and optional dependencies. A package defines a set of named features in the [features] table of Cargo.toml, and each feature can either be enabled or disabled. Features for the package being built can be enabled on the command-line with flags such as --features. Features for dependencies can be enabled in the dependency declaration in Cargo.toml.

Note: New crates or versions published on crates.io are now limited to a maximum of 300 features. Exceptions are granted on a case-by-case basis. See this blog post for details. Participation in solution discussions is encouraged via the crates.io Zulip stream.

See also the Features Examples chapter for some examples of how features can be used.

The [features] section

Features are defined in the [features] table in Cargo.toml. Each feature specifies an array of other features or optional dependencies that it enables. The following examples illustrate how features could be used for a 2D image processing library where support for different image formats can be optionally included:

[features]
# Defines a feature named `webp` that does not enable any other features.
webp = []

With this feature defined, cfg expressions can be used to conditionally include code to support the requested feature at compile time. For example, inside lib.rs of the package could include this:

#![allow(unused)]
fn main() {
// This conditionally includes a module which implements WEBP support.
#[cfg(feature = "webp")]
pub mod webp;
}

Cargo sets features in the package using the rustc --cfg flag, and code can test for their presence with the cfg attribute or the cfg macro.

Features can list other features to enable. For example, the ICO image format can contain BMP and PNG images, so when it is enabled, it should make sure those other features are enabled, too:

[features]
bmp = []
png = []
ico = ["bmp", "png"]
webp = []

Feature names may include characters from the Unicode XID standard (which includes most letters), and additionally allows starting with _ or digits 0 through 9, and after the first character may also contain -, +, or ..

Note: crates.io imposes additional constraints on feature name syntax that they must only be ASCII alphanumeric characters or _, -, or +.

The default feature

By default, all features are disabled unless explicitly enabled. This can be changed by specifying the default feature:

[features]
default = ["ico", "webp"]
bmp = []
png = []
ico = ["bmp", "png"]
webp = []

When the package is built, the default feature is enabled which in turn enables the listed features. This behavior can be changed by:

• The --no-default-features command-line flag disables the default features of the package.
• The default-features = false option can be specified in a dependency declaration.

Note: Be careful about choosing the default feature set. The default features are a convenience that make it easier to use a package without forcing the user to carefully select which features to enable for common use, but there are some drawbacks. Dependencies automatically enable default features unless default-features = false is specified. This can make it difficult to ensure that the default features are not enabled, especially for a dependency that appears multiple times in the dependency graph. Every package must ensure that default-features = false is specified to avoid enabling them.

Another issue is that it can be a SemVer incompatible change to remove a feature from the default set, so you should be confident that you will keep those features.

Optional dependencies

Dependencies can be marked “optional”, which means they will not be compiled by default. For example, let’s say that our 2D image processing library uses an external package to handle GIF images. This can be expressed like this:

[dependencies]
gif = { version = "0.11.1", optional = true }

By default, this optional dependency implicitly defines a feature that looks like this:

[features]
gif = ["dep:gif"]

This means that this dependency will only be included if the gif feature is enabled. The same cfg(feature = "gif") syntax can be used in the code, and the dependency can be enabled just like any feature such as --features gif (see Command-line feature options below).

In some cases, you may not want to expose a feature that has the same name as the optional dependency. For example, perhaps the optional dependency is an internal detail, or you want to group multiple optional dependencies together, or you just want to use a better name. If you specify the optional dependency with the dep: prefix anywhere in the [features] table, that disables the implicit feature.

Note: The dep: syntax is only available starting with Rust 1.60. Previous versions can only use the implicit feature name.

For example, let’s say in order to support the AVIF image format, our library needs two other dependencies to be enabled:

[dependencies]
ravif = { version = "0.6.3", optional = true }
rgb = { version = "0.8.25", optional = true }

[features]
avif = ["dep:ravif", "dep:rgb"]

In this example, the avif feature will enable the two listed dependencies. This also avoids creating the implicit ravif and rgb features, since we don’t want users to enable those individually as they are internal details to our crate.

Note: Another way to optionally include a dependency is to use platform-specific dependencies. Instead of using features, these are conditional based on the target platform.

Dependency features

Features of dependencies can be enabled within the dependency declaration. The features key indicates which features to enable:

[dependencies]
# Enables the `derive` feature of serde.
serde = { version = "1.0.118", features = ["derive"] }

The default features can be disabled using default-features = false:

[dependencies]
flate2 = { version = "1.0.3", default-features = false, features = ["zlib"] }

Note: This may not ensure the default features are disabled. If another dependency includes flate2 without specifying default-features = false, then the default features will be enabled. See feature unification below for more details.

Features of dependencies can also be enabled in the [features] table. The syntax is "package-name/feature-name". For example:

[dependencies]
jpeg-decoder = { version = "0.1.20", default-features = false }

[features]
# Enables parallel processing support by enabling the "rayon" feature of jpeg-decoder.
parallel = ["jpeg-decoder/rayon"]

The "package-name/feature-name" syntax will also enable package-name if it is an optional dependency. Often this is not what you want. You can add a ? as in "package-name?/feature-name" which will only enable the given feature if something else enables the optional dependency.

Note: The ? syntax is only available starting with Rust 1.60.

For example, let’s say we have added some serialization support to our library, and it requires enabling a corresponding feature in some optional dependencies. That can be done like this:

[dependencies]
serde = { version = "1.0.133", optional = true }
rgb = { version = "0.8.25", optional = true }

[features]
serde = ["dep:serde", "rgb?/serde"]

In this example, enabling the serde feature will enable the serde dependency. It will also enable the serde feature for the rgb dependency, but only if something else has enabled the rgb dependency.

Command-line feature options

The following command-line flags can be used to control which features are enabled:

• --features FEATURES: Enables the listed features. Multiple features may be separated with commas or spaces. If using spaces, be sure to use quotes around all the features if running Cargo from a shell (such as --features "foo bar"). If building multiple packages in a workspace, the package-name/feature-name syntax can be used to specify features for specific workspace members.

• --all-features: Activates all features of all packages selected on the command-line.

• --no-default-features: Does not activate the default feature of the selected packages.

Feature unification

Features are unique to the package that defines them. Enabling a feature on a package does not enable a feature of the same name on other packages.

When a dependency is used by multiple packages, Cargo will use the union of all features enabled on that dependency when building it. This helps ensure that only a single copy of the dependency is used. See the features section of the resolver documentation for more details.

For example, let’s look at the winapi package which uses a large number of features. If your package depends on a package foo which enables the “fileapi” and “handleapi” features of winapi, and another dependency bar which enables the “std” and “winnt” features of winapi, then winapi will be built with all four of those features enabled.

A consequence of this is that features should be additive. That is, enabling a feature should not disable functionality, and it should usually be safe to enable any combination of features. A feature should not introduce a SemVer-incompatible change.

For example, if you want to optionally support no_std environments, do not use a no_std feature. Instead, use a std feature that enables std. For example:

#![allow(unused)]
#![no_std]

fn main() {
#[cfg(feature = "std")]
extern crate std;

#[cfg(feature = "std")]
pub fn function_that_requires_std() {
    // ...
}
}

Mutually exclusive features

There are rare cases where features may be mutually incompatible with one another. This should be avoided if at all possible, because it requires coordinating all uses of the package in the dependency graph to cooperate to avoid enabling them together. If it is not possible, consider adding a compile error to detect this scenario. For example:

#[cfg(all(feature = "foo", feature = "bar"))]
compile_error!("feature \"foo\" and feature \"bar\" cannot be enabled at the same time");

Instead of using mutually exclusive features, consider some other options:

• Split the functionality into separate packages.
• When there is a conflict, choose one feature over another. The cfg-if package can help with writing more complex cfg expressions.
• Architect the code to allow the features to be enabled concurrently, and use runtime options to control which is used. For example, use a config file, command-line argument, or environment variable to choose which behavior to enable.

Inspecting resolved features

In complex dependency graphs, it can sometimes be difficult to understand how different features get enabled on various packages. The cargo tree command offers several options to help inspect and visualize which features are enabled. Some options to try:

• cargo tree -e features: This will show features in the dependency graph. Each feature will appear showing which package enabled it.
• cargo tree -f "{p} {f}": This is a more compact view that shows a comma-separated list of features enabled on each package.
• cargo tree -e features -i foo: This will invert the tree, showing how features flow into the given package “foo”. This can be useful because viewing the entire graph can be quite large and overwhelming. Use this when you are trying to figure out which features are enabled on a specific package and why. See the example at the bottom of the cargo tree page on how to read this.

Feature resolver version 2

A different feature resolver can be specified with the resolver field in Cargo.toml, like this:

[package]
name = "my-package"
version = "1.0.0"
resolver = "2"

See the resolver versions section for more detail on specifying resolver versions.

The version "2" resolver avoids unifying features in a few situations where that unification can be unwanted. The exact situations are described in the resolver chapter, but in short, it avoids unifying in these situations:

• Features enabled on platform-specific dependencies for target architectures not currently being built are ignored.
• Build-dependencies and proc-macros do not share features with normal dependencies.
• Dev-dependencies do not activate features unless building a Cargo target that needs them (like tests or examples).

Avoiding the unification is necessary for some situations. For example, if a build-dependency enables a std feature, and the same dependency is used as a normal dependency for a no_std environment, enabling std would break the build.

However, one drawback is that this can increase build times because the dependency is built multiple times (each with different features). When using the version "2" resolver, it is recommended to check for dependencies that are built multiple times to reduce overall build time. If it is not required to build those duplicated packages with separate features, consider adding features to the features list in the dependency declaration so that the duplicates end up with the same features (and thus Cargo will build it only once). You can detect these duplicate dependencies with the cargo tree --duplicates command. It will show which packages are built multiple times; look for any entries listed with the same version. See Inspecting resolved features for more on fetching information on the resolved features. For build dependencies, this is not necessary if you are cross-compiling with the --target flag because build dependencies are always built separately from normal dependencies in that scenario.

Resolver version 2 command-line flags

The resolver = "2" setting also changes the behavior of the --features and --no-default-features command-line options.

With version "1", you can only enable features for the package in the current working directory. For example, in a workspace with packages foo and bar, and you are in the directory for package foo, and ran the command cargo build -p bar --features bar-feat, this would fail because the --features flag only allowed enabling features on foo.

With resolver = "2", the features flags allow enabling features for any of the packages selected on the command-line with -p and --workspace flags. For example:

# This command is allowed with resolver = "2", regardless of which directory
# you are in.
cargo build -p foo -p bar --features foo-feat,bar-feat

# This explicit equivalent works with any resolver version:
cargo build -p foo -p bar --features foo/foo-feat,bar/bar-feat

Additionally, with resolver = "1", the --no-default-features flag only disables the default feature for the package in the current directory. With version “2”, it will disable the default features for all workspace members.

Build scripts

Build scripts can detect which features are enabled on the package by inspecting the CARGO_FEATURE_<name> environment variable, where <name> is the feature name converted to uppercase and - converted to _.

Required features

The required-features field can be used to disable specific Cargo targets if a feature is not enabled. See the linked documentation for more details.

SemVer compatibility

Enabling a feature should not introduce a SemVer-incompatible change. For example, the feature shouldn’t change an existing API in a way that could break existing uses. More details about what changes are compatible can be found in the SemVer Compatibility chapter.

Care should be taken when adding and removing feature definitions and optional dependencies, as these can sometimes be backwards-incompatible changes. More details can be found in the Cargo section of the SemVer Compatibility chapter. In short, follow these rules:

• The following is usually safe to do in a minor release:
  • Add a new feature or optional dependency.
  • Change the features used on a dependency.
• The following should usually not be done in a minor release:
  • Remove a feature or optional dependency.
  • Moving existing public code behind a feature.
  • Remove a feature from a feature list.

See the links for caveats and examples.

Feature documentation and discovery

You are encouraged to document which features are available in your package. This can be done by adding doc comments at the top of lib.rs. As an example, see the regex crate source, which when rendered can be viewed on docs.rs. If you have other documentation, such as a user guide, consider adding the documentation there (for example, see serde.rs). If you have a binary project, consider documenting the features in the README or other documentation for the project (for example, see sccache).

Clearly documenting the features can set expectations about features that are considered “unstable” or otherwise shouldn’t be used. For example, if there is an optional dependency, but you don’t want users to explicitly list that optional dependency as a feature, exclude it from the documented list.

Documentation published on docs.rs can use metadata in Cargo.toml to control which features are enabled when the documentation is built. See docs.rs metadata documentation for more details.

Note: Rustdoc has experimental support for annotating the documentation to indicate which features are required to use certain APIs. See the doc_cfg documentation for more details. An example is the syn documentation, where you can see colored boxes which note which features are required to use it.

Discovering features

When features are documented in the library API, this can make it easier for your users to discover which features are available and what they do. If the feature documentation for a package isn’t readily available, you can look at the Cargo.toml file, but sometimes it can be hard to track it down. The crate page on crates.io has a link to the source repository if available. Tools like cargo vendor or cargo-clone-crate can be used to download the source and inspect it.

Feature combinations

Because features are a form of conditional compilation, they require an exponential number of configurations and test cases to be 100% covered. By default, tests, docs, and other tooling such as Clippy will only run with the default set of features.

We encourage you to consider your strategy and tooling in regards to different feature combinations — Every project will have different requirements in conjunction with time, resources, and the cost-benefit of covering specific scenarios. Common configurations may be with / without default features, specific combinations of features, or all combinations of features.

Features Examples

The following illustrates some real-world examples of features in action.

Minimizing build times and file sizes

Some packages use features so that if the features are not enabled, it reduces the size of the crate and reduces compile time. Some examples are:

• syn is a popular crate for parsing Rust code. Since it is so popular, it is helpful to reduce compile times since it affects so many projects. It has a clearly documented list of features which can be used to minimize the amount of code it contains.
• regex has a several features that are well documented. Cutting out Unicode support can reduce the resulting file size as it can remove some large tables.
• winapi has a large number of features that limit which Windows API bindings it supports.
• web-sys is another example similar to winapi that provides a huge surface area of API bindings that are limited by using features.

Extending behavior

The serde_json package has a preserve_order feature which changes the behavior of JSON maps to preserve the order that keys are inserted. Notice that it enables an optional dependency indexmap to implement the new behavior.

When changing behavior like this, be careful to make sure the changes are SemVer compatible. That is, enabling the feature should not break code that usually builds with the feature off.

no_std support

Some packages want to support both no_std and std environments. This is useful for supporting embedded and resource-constrained platforms, but still allowing extended capabilities for platforms that support the full standard library.

The wasm-bindgen package defines a std feature that is enabled by default. At the top of the library, it unconditionally enables the no_std attribute. This ensures that std and the std prelude are not automatically in scope. Then, in various places in the code (example1, example2), it uses #[cfg(feature = "std")] attributes to conditionally enable extra functionality that requires std.

Re-exporting dependency features

It can be convenient to re-export the features from a dependency. This allows the user depending on the crate to control those features without needing to specify those dependencies directly. For example, regex re-exports the features from the regex_syntax package. Users of regex don’t need to know about the regex_syntax package, but they can still access the features it contains.

Vendoring of C libraries

Some packages provide bindings to common C libraries (sometimes referred to as “sys” crates). Sometimes these packages give you the choice to use the C library installed on the system, or to build it from source. For example, the openssl package has a vendored feature which enables the corresponding vendored feature of openssl-sys. The openssl-sys build script has some conditional logic which causes it to build from a local copy of the OpenSSL source code instead of using the version from the system.

The curl-sys package is another example where the static-curl feature causes it to build libcurl from source. Notice that it also has a force-system-lib-on-osx feature which forces it to use the system libcurl, overriding the static-curl setting.

Feature precedence

Some packages may have mutually-exclusive features. One option to handle this is to prefer one feature over another. The log package is an example. It has several features for choosing the maximum logging level at compile-time described here. It uses cfg-if to choose a precedence. If multiple features are enabled, the higher “max” levels will be preferred over the lower levels.

Proc-macro companion package

Some packages have a proc-macro that is intimately tied with it. However, not all users will need to use the proc-macro. By making the proc-macro an optional-dependency, this allows you to conveniently choose whether or not it is included. This is helpful, because sometimes the proc-macro version must stay in sync with the parent package, and you don’t want to force the users to have to specify both dependencies and keep them in sync.

An example is serde which has a derive feature which enables the serde_derive proc-macro. The serde_derive crate is very tightly tied to serde, so it uses an equals version requirement to ensure they stay in sync.

Nightly-only features

Some packages want to experiment with APIs or language features that are only available on the Rust nightly channel. However, they may not want to require their users to also use the nightly channel. An example is wasm-bindgen which has a nightly feature which enables an extended API that uses the Unsize marker trait that is only available on the nightly channel at the time of this writing.

Note that at the root of the crate it uses cfg_attr to enable the nightly feature. Keep in mind that the feature attribute is unrelated to Cargo features, and is used to opt-in to experimental language features.

The simd_support feature of the rand package is another example, which relies on a dependency that only builds on the nightly channel.

Experimental features

Some packages have new functionality that they may want to experiment with, without having to commit to the stability of those APIs. The features are usually documented that they are experimental, and thus may change or break in the future, even during a minor release. An example is the async-std package, which has an unstable feature, which gates new APIs that people can opt-in to using, but may not be completely ready to be relied upon.

Profiles

Profiles provide a way to alter the compiler settings, influencing things like optimizations and debugging symbols.

Cargo has 4 built-in profiles: dev, release, test, and bench. The profile is automatically chosen based on which command is being run if a profile is not specified on the command-line. In addition to the built-in profiles, custom user-defined profiles can also be specified.

Profile settings can be changed in Cargo.toml with the [profile] table. Within each named profile, individual settings can be changed with key/value pairs like this:

[profile.dev]
opt-level = 1               # Use slightly better optimizations.
overflow-checks = false     # Disable integer overflow checks.

Cargo only looks at the profile settings in the Cargo.toml manifest at the root of the workspace. Profile settings defined in dependencies will be ignored.

Additionally, profiles can be overridden from a config definition. Specifying a profile in a config file or environment variable will override the settings from Cargo.toml.

Profile settings

The following is a list of settings that can be controlled in a profile.

opt-level

The opt-level setting controls the -C opt-level flag which controls the level of optimization. Higher optimization levels may produce faster runtime code at the expense of longer compiler times. Higher levels may also change and rearrange the compiled code which may make it harder to use with a debugger.

The valid options are:

• 0: no optimizations
• 1: basic optimizations
• 2: some optimizations
• 3: all optimizations
• "s": optimize for binary size
• "z": optimize for binary size, but also turn off loop vectorization.

It is recommended to experiment with different levels to find the right balance for your project. There may be surprising results, such as level 3 being slower than 2, or the "s" and "z" levels not being necessarily smaller. You may also want to reevaluate your settings over time as newer versions of rustc change optimization behavior.

See also Profile Guided Optimization for more advanced optimization techniques.

debug

The debug setting controls the -C debuginfo flag which controls the amount of debug information included in the compiled binary.

The valid options are:

• 0, false, or "none": no debug info at all, default for release
• "line-directives-only": line info directives only. For the nvptx* targets this enables profiling. For other use cases, line-tables-only is the better, more compatible choice.
• "line-tables-only": line tables only. Generates the minimal amount of debug info for backtraces with filename/line number info, but not anything else, i.e. no variable or function parameter info.
• 1 or "limited": debug info without type or variable-level information. Generates more detailed module-level info than line-tables-only.
• 2, true, or "full": full debug info, default for dev

For more information on what each option does see rustc’s docs on debuginfo.

You may wish to also configure the split-debuginfo option depending on your needs as well.

MSRV: 1.71 is required for none, limited, full, line-directives-only, and line-tables-only

split-debuginfo

The split-debuginfo setting controls the -C split-debuginfo flag which controls whether debug information, if generated, is either placed in the executable itself or adjacent to it.

This option is a string and acceptable values are the same as those the compiler accepts. The default value for this option is unpacked on macOS for profiles that have debug information otherwise enabled. Otherwise the default for this option is documented with rustc and is platform-specific. Some options are only available on the nightly channel. The Cargo default may change in the future once more testing has been performed, and support for DWARF is stabilized.

Be aware that Cargo and rustc have different defaults for this option. This option exists to allow Cargo to experiment on different combinations of flags thus providing better debugging and developer experience.

strip

The strip option controls the -C strip flag, which directs rustc to strip either symbols or debuginfo from a binary. This can be enabled like so:

[package]
# ...

[profile.release]
strip = "debuginfo"

Possible string values of strip are "none", "debuginfo", and "symbols". The default is "none".

You can also configure this option with the boolean values true or false. strip = true is equivalent to strip = "symbols". strip = false is equivalent to strip = "none" and disables strip completely.

debug-assertions

The debug-assertions setting controls the -C debug-assertions flag which turns cfg(debug_assertions) conditional compilation on or off. Debug assertions are intended to include runtime validation which is only available in debug/development builds. These may be things that are too expensive or otherwise undesirable in a release build. Debug assertions enables the debug_assert! macro in the standard library.

The valid options are:

• true: enabled
• false: disabled

overflow-checks

The overflow-checks setting controls the -C overflow-checks flag which controls the behavior of runtime integer overflow. When overflow-checks are enabled, a panic will occur on overflow.

The valid options are:

• true: enabled
• false: disabled

lto

The lto setting controls rustc’s -C lto, -C linker-plugin-lto, and -C embed-bitcode options, which control LLVM’s link time optimizations. LTO can produce better optimized code, using whole-program analysis, at the cost of longer linking time.

The valid options are:

• false: Performs “thin local LTO” which performs “thin” LTO on the local crate only across its codegen units. No LTO is performed if codegen units is 1 or opt-level is 0.
• true or "fat": Performs “fat” LTO which attempts to perform optimizations across all crates within the dependency graph.
• "thin": Performs “thin” LTO. This is similar to “fat”, but takes substantially less time to run while still achieving performance gains similar to “fat”.
• "off": Disables LTO.

See the linker-plugin-lto chapter if you are interested in cross-language LTO. This is not yet supported natively in Cargo, but can be performed via RUSTFLAGS.

panic

The panic setting controls the -C panic flag which controls which panic strategy to use.

The valid options are:

• "unwind": Unwind the stack upon panic.
• "abort": Terminate the process upon panic.

When set to "unwind", the actual value depends on the default of the target platform. For example, the NVPTX platform does not support unwinding, so it always uses "abort".

Tests, benchmarks, build scripts, and proc macros ignore the panic setting. The rustc test harness currently requires unwind behavior. See the panic-abort-tests unstable flag which enables abort behavior.

Additionally, when using the abort strategy and building a test, all of the dependencies will also be forced to build with the unwind strategy.

incremental

The incremental setting controls the -C incremental flag which controls whether or not incremental compilation is enabled. Incremental compilation causes rustc to save additional information to disk which will be reused when recompiling the crate, improving re-compile times. The additional information is stored in the target directory.

The valid options are:

• true: enabled
• false: disabled

Incremental compilation is only used for workspace members and “path” dependencies.

The incremental value can be overridden globally with the CARGO_INCREMENTAL environment variable or the build.incremental config variable.

codegen-units

The codegen-units setting controls the -C codegen-units flag which controls how many “code generation units” a crate will be split into. More code generation units allows more of a crate to be processed in parallel possibly reducing compile time, but may produce slower code.

This option takes an integer greater than 0.

The default is 256 for incremental builds, and 16 for non-incremental builds.

rpath

The rpath setting controls the -C rpath flag which controls whether or not rpath is enabled.

Default profiles

dev

The dev profile is used for normal development and debugging. It is the default for build commands like cargo build, and is used for cargo install --debug.

The default settings for the dev profile are:

[profile.dev]
opt-level = 0
debug = true
split-debuginfo = '...'  # Platform-specific.
strip = "none"
debug-assertions = true
overflow-checks = true
lto = false
panic = 'unwind'
incremental = true
codegen-units = 256
rpath = false

release

The release profile is intended for optimized artifacts used for releases and in production. This profile is used when the --release flag is used, and is the default for cargo install.

The default settings for the release profile are:

[profile.release]
opt-level = 3
debug = false
split-debuginfo = '...'  # Platform-specific.
strip = "none"
debug-assertions = false
overflow-checks = false
lto = false
panic = 'unwind'
incremental = false
codegen-units = 16
rpath = false

test

The test profile is the default profile used by cargo test. The test profile inherits the settings from the dev profile.

bench

The bench profile is the default profile used by cargo bench. The bench profile inherits the settings from the release profile.

Build Dependencies

To compile quickly, all profiles, by default, do not optimize build dependencies (build scripts, proc macros, and their dependencies), and avoid computing debug info when a build dependency is not used as a runtime dependency. The default settings for build overrides are:

[profile.dev.build-override]
opt-level = 0
codegen-units = 256
debug = false # when possible

[profile.release.build-override]
opt-level = 0
codegen-units = 256

However, if errors occur while running build dependencies, turning full debug info on will improve backtraces and debuggability when needed:

debug = true

Build dependencies otherwise inherit settings from the active profile in use, as described in Profile selection.

Custom profiles

In addition to the built-in profiles, additional custom profiles can be defined. These may be useful for setting up multiple workflows and build modes. When defining a custom profile, you must specify the inherits key to specify which profile the custom profile inherits settings from when the setting is not specified.

For example, let’s say you want to compare a normal release build with a release build with LTO optimizations, you can specify something like the following in Cargo.toml:

[profile.release-lto]
inherits = "release"
lto = true

The --profile flag can then be used to choose this custom profile:

cargo build --profile release-lto

The output for each profile will be placed in a directory of the same name as the profile in the target directory. As in the example above, the output would go into the target/release-lto directory.

Profile selection

The profile used depends on the command, the command-line flags like --release or --profile, and the package (in the case of overrides). The default profile if none is specified is:

You can switch to a different profile using the --profile=NAME option which will used the given profile. The --release flag is equivalent to --profile=release.

The selected profile applies to all Cargo targets, including library, binary, example, test, and benchmark.

The profile for specific packages can be specified with overrides, described below.

Overrides

Profile settings can be overridden for specific packages and build-time crates. To override the settings for a specific package, use the package table to change the settings for the named package:

# The `foo` package will use the -Copt-level=3 flag.
[profile.dev.package.foo]
opt-level = 3

The package name is actually a Package ID Spec, so you can target individual versions of a package with syntax such as [profile.dev.package."foo:2.1.0"].

To override the settings for all dependencies (but not any workspace member), use the "*" package name:

# Set the default for dependencies.
[profile.dev.package."*"]
opt-level = 2

To override the settings for build scripts, proc macros, and their dependencies, use the build-override table:

# Set the settings for build scripts and proc-macros.
[profile.dev.build-override]
opt-level = 3

Note: When a dependency is both a normal dependency and a build dependency, Cargo will try to only build it once when --target is not specified. When using build-override, the dependency may need to be built twice, once as a normal dependency and once with the overridden build settings. This may increase initial build times.

The precedence for which value is used is done in the following order (first match wins):

1. [profile.dev.package.name] — A named package.
2. [profile.dev.package."*"] — For any non-workspace member.
3. [profile.dev.build-override] — Only for build scripts, proc macros, and their dependencies.
4. [profile.dev] — Settings in Cargo.toml.
5. Default values built-in to Cargo.

Overrides cannot specify the panic, lto, or rpath settings.

Overrides and generics

The location where generic code is instantiated will influence the optimization settings used for that generic code. This can cause subtle interactions when using profile overrides to change the optimization level of a specific crate. If you attempt to raise the optimization level of a dependency which defines generic functions, those generic functions may not be optimized when used in your local crate. This is because the code may be generated in the crate where it is instantiated, and thus may use the optimization settings of that crate.

For example, nalgebra is a library which defines vectors and matrices making heavy use of generic parameters. If your local code defines concrete nalgebra types like Vector4<f64> and uses their methods, the corresponding nalgebra code will be instantiated and built within your crate. Thus, if you attempt to increase the optimization level of nalgebra using a profile override, it may not result in faster performance.

Further complicating the issue, rustc has some optimizations where it will attempt to share monomorphized generics between crates. If the opt-level is 2 or 3, then a crate will not use monomorphized generics from other crates, nor will it export locally defined monomorphized items to be shared with other crates. When experimenting with optimizing dependencies for development, consider trying opt-level 1, which will apply some optimizations while still allowing monomorphized items to be shared.

Configuration

This document explains how Cargo’s configuration system works, as well as available keys or configuration. For configuration of a package through its manifest, see the manifest format.

Hierarchical structure

Cargo allows local configuration for a particular package as well as global configuration. It looks for configuration files in the current directory and all parent directories. If, for example, Cargo were invoked in /projects/foo/bar/baz, then the following configuration files would be probed for and unified in this order:

• /projects/foo/bar/baz/.cargo/config.toml
• /projects/foo/bar/.cargo/config.toml
• /projects/foo/.cargo/config.toml
• /projects/.cargo/config.toml
• /.cargo/config.toml
• $CARGO_HOME/config.toml which defaults to:
  • Windows: %USERPROFILE%\.cargo\config.toml
  • Unix: $HOME/.cargo/config.toml

With this structure, you can specify configuration per-package, and even possibly check it into version control. You can also specify personal defaults with a configuration file in your home directory.

If a key is specified in multiple config files, the values will get merged together. Numbers, strings, and booleans will use the value in the deeper config directory taking precedence over ancestor directories, where the home directory is the lowest priority. Arrays will be joined together with higher precedence items being placed later in the merged array.

At present, when being invoked from a workspace, Cargo does not read config files from crates within the workspace. i.e. if a workspace has two crates in it, named /projects/foo/bar/baz/mylib and /projects/foo/bar/baz/mybin, and there are Cargo configs at /projects/foo/bar/baz/mylib/.cargo/config.toml and /projects/foo/bar/baz/mybin/.cargo/config.toml, Cargo does not read those configuration files if it is invoked from the workspace root (/projects/foo/bar/baz/).

Note: Cargo also reads config files without the .toml extension, such as .cargo/config. Support for the .toml extension was added in version 1.39 and is the preferred form. If both files exist, Cargo will use the file without the extension.

Configuration format

Configuration files are written in the TOML format (like the manifest), with simple key-value pairs inside of sections (tables). The following is a quick overview of all settings, with detailed descriptions found below.

paths = ["/path/to/override"] # path dependency overrides

[alias]     # command aliases
b = "build"
c = "check"
t = "test"
r = "run"
rr = "run --release"
recursive_example = "rr --example recursions"
space_example = ["run", "--release", "--", "\"command list\""]

[build]
jobs = 1                      # number of parallel jobs, defaults to # of CPUs
rustc = "rustc"               # the rust compiler tool
rustc-wrapper = "…"           # run this wrapper instead of `rustc`
rustc-workspace-wrapper = "…" # run this wrapper instead of `rustc` for workspace members
rustdoc = "rustdoc"           # the doc generator tool
target = "triple"             # build for the target triple (ignored by `cargo install`)
target-dir = "target"         # path of where to place all generated artifacts
rustflags = ["…", "…"]        # custom flags to pass to all compiler invocations
rustdocflags = ["…", "…"]     # custom flags to pass to rustdoc
incremental = true            # whether or not to enable incremental compilation
dep-info-basedir = "…"        # path for the base directory for targets in depfiles

[credential-alias]
# Provides a way to define aliases for credential providers.
my-alias = ["/usr/bin/cargo-credential-example", "--argument", "value", "--flag"]

[doc]
browser = "chromium"          # browser to use with `cargo doc --open`,
                              # overrides the `BROWSER` environment variable

[env]
# Set ENV_VAR_NAME=value for any process run by Cargo
ENV_VAR_NAME = "value"
# Set even if already present in environment
ENV_VAR_NAME_2 = { value = "value", force = true }
# Value is relative to .cargo directory containing `config.toml`, make absolute
ENV_VAR_NAME_3 = { value = "relative/path", relative = true }

[future-incompat-report]
frequency = 'always' # when to display a notification about a future incompat report

[cargo-new]
vcs = "none"              # VCS to use ('git', 'hg', 'pijul', 'fossil', 'none')

[http]
debug = false               # HTTP debugging
proxy = "host:port"         # HTTP proxy in libcurl format
ssl-version = "tlsv1.3"     # TLS version to use
ssl-version.max = "tlsv1.3" # maximum TLS version
ssl-version.min = "tlsv1.1" # minimum TLS version
timeout = 30                # timeout for each HTTP request, in seconds
low-speed-limit = 10        # network timeout threshold (bytes/sec)
cainfo = "cert.pem"         # path to Certificate Authority (CA) bundle
check-revoke = true         # check for SSL certificate revocation
multiplexing = true         # HTTP/2 multiplexing
user-agent = "…"            # the user-agent header

[install]
root = "/some/path"         # `cargo install` destination directory

[net]
retry = 3                   # network retries
git-fetch-with-cli = true   # use the `git` executable for git operations
offline = true              # do not access the network

[net.ssh]
known-hosts = ["..."]       # known SSH host keys

[patch.<registry>]
# Same keys as for [patch] in Cargo.toml

[profile.<name>]         # Modify profile settings via config.
inherits = "dev"         # Inherits settings from [profile.dev].
opt-level = 0            # Optimization level.
debug = true             # Include debug info.
split-debuginfo = '...'  # Debug info splitting behavior.
strip = "none"           # Removes symbols or debuginfo.
debug-assertions = true  # Enables debug assertions.
overflow-checks = true   # Enables runtime integer overflow checks.
lto = false              # Sets link-time optimization.
panic = 'unwind'         # The panic strategy.
incremental = true       # Incremental compilation.
codegen-units = 16       # Number of code generation units.
rpath = false            # Sets the rpath linking option.
[profile.<name>.build-override]  # Overrides build-script settings.
# Same keys for a normal profile.
[profile.<name>.package.<name>]  # Override profile for a package.
# Same keys for a normal profile (minus `panic`, `lto`, and `rpath`).

[resolver]
incompatible-rust-versions = "allow"  # Specifies how resolver reacts to these

[registries.<name>]  # registries other than crates.io
index = "…"          # URL of the registry index
token = "…"          # authentication token for the registry
credential-provider = "cargo:token" # The credential provider for this registry.

[registries.crates-io]
protocol = "sparse"  # The protocol to use to access crates.io.

[registry]
default = "…"        # name of the default registry
token = "…"          # authentication token for crates.io
credential-provider = "cargo:token"           # The credential provider for crates.io.
global-credential-providers = ["cargo:token"] # The credential providers to use by default.

[source.<name>]      # source definition and replacement
replace-with = "…"   # replace this source with the given named source
directory = "…"      # path to a directory source
registry = "…"       # URL to a registry source
local-registry = "…" # path to a local registry source
git = "…"            # URL of a git repository source
branch = "…"         # branch name for the git repository
tag = "…"            # tag name for the git repository
rev = "…"            # revision for the git repository

[target.<triple>]
linker = "…"              # linker to use
runner = "…"              # wrapper to run executables
rustflags = ["…", "…"]    # custom flags for `rustc`
rustdocflags = ["…", "…"] # custom flags for `rustdoc`

[target.<cfg>]
runner = "…"            # wrapper to run executables
rustflags = ["…", "…"]  # custom flags for `rustc`

[target.<triple>.<links>] # `links` build script override
rustc-link-lib = ["foo"]
rustc-link-search = ["/path/to/foo"]
rustc-flags = "-L /some/path"
rustc-cfg = ['key="value"']
rustc-env = {key = "value"}
rustc-cdylib-link-arg = ["…"]
metadata_key1 = "value"
metadata_key2 = "value"

[term]
quiet = false          # whether cargo output is quiet
verbose = false        # whether cargo provides verbose output
color = 'auto'         # whether cargo colorizes output
hyperlinks = true      # whether cargo inserts links into output
unicode = true         # whether cargo can render output using non-ASCII unicode characters
progress.when = 'auto' # whether cargo shows progress bar
progress.width = 80    # width of progress bar

Environment variables

Cargo can also be configured through environment variables in addition to the TOML configuration files. For each configuration key of the form foo.bar the environment variable CARGO_FOO_BAR can also be used to define the value. Keys are converted to uppercase, dots and dashes are converted to underscores. For example the target.x86_64-unknown-linux-gnu.runner key can also be defined by the CARGO_TARGET_X86_64_UNKNOWN_LINUX_GNU_RUNNER environment variable.

Environment variables will take precedence over TOML configuration files. Currently only integer, boolean, string and some array values are supported to be defined by environment variables. Descriptions below indicate which keys support environment variables and otherwise they are not supported due to technical issues.

In addition to the system above, Cargo recognizes a few other specific environment variables.

Command-line overrides

Cargo also accepts arbitrary configuration overrides through the --config command-line option. The argument should be in TOML syntax of KEY=VALUE or provided as a path to an extra configuration file:

# With `KEY=VALUE` in TOML syntax
cargo --config net.git-fetch-with-cli=true fetch

# With a path to a configuration file
cargo --config ./path/to/my/extra-config.toml fetch

The --config option may be specified multiple times, in which case the values are merged in left-to-right order, using the same merging logic that is used when multiple configuration files apply. Configuration values specified this way take precedence over environment variables, which take precedence over configuration files.

When the --config option is provided as an extra configuration file, The configuration file loaded this way follow the same precedence rules as other options specified directly with --config.

Some examples of what it looks like using Bourne shell syntax:

# Most shells will require escaping.
cargo --config http.proxy=\"http://example.com\" …

# Spaces may be used.
cargo --config "net.git-fetch-with-cli = true" …

# TOML array example. Single quotes make it easier to read and write.
cargo --config 'build.rustdocflags = ["--html-in-header", "header.html"]' …

# Example of a complex TOML key.
cargo --config "target.'cfg(all(target_arch = \"arm\", target_os = \"none\"))'.runner = 'my-runner'" …

# Example of overriding a profile setting.
cargo --config profile.dev.package.image.opt-level=3 …

Config-relative paths

Paths in config files may be absolute, relative, or a bare name without any path separators. Paths for executables without a path separator will use the PATH environment variable to search for the executable. Paths for non-executables will be relative to where the config value is defined.

In particular, rules are:

• For environment variables, paths are relative to the current working directory.
• For config values loaded directly from the --config KEY=VALUE option, paths are relative to the current working directory.
• For config files, paths are relative to the parent directory of the directory where the config files were defined, no matter those files are from either the hierarchical probing or the --config <path> option.

Note: To maintain consistency with existing .cargo/config.toml probing behavior, it is by design that a path in a config file passed via --config <path> is also relative to two levels up from the config file itself.

To avoid unexpected results, the rule of thumb is putting your extra config files at the same level of discovered .cargo/config.toml in your project. For instance, given a project /my/project, it is recommended to put config files under /my/project/.cargo or a new directory at the same level, such as /my/project/.config.

# Relative path examples.

[target.x86_64-unknown-linux-gnu]
runner = "foo"  # Searches `PATH` for `foo`.

[source.vendored-sources]
# Directory is relative to the parent where `.cargo/config.toml` is located.
# For example, `/my/project/.cargo/config.toml` would result in `/my/project/vendor`.
directory = "vendor"

Executable paths with arguments

Some Cargo commands invoke external programs, which can be configured as a path and some number of arguments.

The value may be an array of strings like ['/path/to/program', 'somearg'] or a space-separated string like '/path/to/program somearg'. If the path to the executable contains a space, the list form must be used.

If Cargo is passing other arguments to the program such as a path to open or run, they will be passed after the last specified argument in the value of an option of this format. If the specified program does not have path separators, Cargo will search PATH for its executable.

Credentials

Configuration values with sensitive information are stored in the $CARGO_HOME/credentials.toml file. This file is automatically created and updated by cargo login and cargo logout when using the cargo:token credential provider.

Tokens are used by some Cargo commands such as cargo publish for authenticating with remote registries. Care should be taken to protect the tokens and to keep them secret.

It follows the same format as Cargo config files.

[registry]
token = "…"   # Access token for crates.io

[registries.<name>]
token = "…"   # Access token for the named registry

As with most other config values, tokens may be specified with environment variables. The token for crates.io may be specified with the CARGO_REGISTRY_TOKEN environment variable. Tokens for other registries may be specified with environment variables of the form CARGO_REGISTRIES_<name>_TOKEN where <name> is the name of the registry in all capital letters.

Note: Cargo also reads and writes credential files without the .toml extension, such as .cargo/credentials. Support for the .toml extension was added in version 1.39. In version 1.68, Cargo writes to the file with the extension by default. However, for backward compatibility reason, when both files exist, Cargo will read and write the file without the extension.

Configuration keys

This section documents all configuration keys. The description for keys with variable parts are annotated with angled brackets like target.<triple> where the <triple> part can be any target triple like target.x86_64-pc-windows-msvc.

paths

• Type: array of strings (paths)
• Default: none
• Environment: not supported

An array of paths to local packages which are to be used as overrides for dependencies. For more information see the Overriding Dependencies guide.

[alias]

• Type: string or array of strings
• Default: see below
• Environment: CARGO_ALIAS_<name>

The [alias] table defines CLI command aliases. For example, running cargo b is an alias for running cargo build. Each key in the table is the subcommand, and the value is the actual command to run. The value may be an array of strings, where the first element is the command and the following are arguments. It may also be a string, which will be split on spaces into subcommand and arguments. The following aliases are built-in to Cargo:

[alias]
b = "build"
c = "check"
d = "doc"
t = "test"
r = "run"
rm = "remove"

Aliases are not allowed to redefine existing built-in commands.

Aliases are recursive:

[alias]
rr = "run --release"
recursive_example = "rr --example recursions"

[build]

The [build] table controls build-time operations and compiler settings.

build.jobs

• Type: integer or string
• Default: number of logical CPUs
• Environment: CARGO_BUILD_JOBS

Sets the maximum number of compiler processes to run in parallel. If negative, it sets the maximum number of compiler processes to the number of logical CPUs plus provided value. Should not be 0. If a string default is provided, it sets the value back to defaults.

Can be overridden with the --jobs CLI option.

build.rustc

• Type: string (program path)
• Default: "rustc"
• Environment: CARGO_BUILD_RUSTC or RUSTC

Sets the executable to use for rustc.

build.rustc-wrapper

• Type: string (program path)
• Default: none
• Environment: CARGO_BUILD_RUSTC_WRAPPER or RUSTC_WRAPPER

Sets a wrapper to execute instead of rustc. The first argument passed to the wrapper is the path to the actual executable to use (i.e., build.rustc, if that is set, or "rustc" otherwise).

build.rustc-workspace-wrapper

• Type: string (program path)
• Default: none
• Environment: CARGO_BUILD_RUSTC_WORKSPACE_WRAPPER or RUSTC_WORKSPACE_WRAPPER

Sets a wrapper to execute instead of rustc, for workspace members only. When building a single-package project without workspaces, that package is considered to be the workspace. The first argument passed to the wrapper is the path to the actual executable to use (i.e., build.rustc, if that is set, or "rustc" otherwise). It affects the filename hash so that artifacts produced by the wrapper are cached separately.

If both rustc-wrapper and rustc-workspace-wrapper are set, then they will be nested: the final invocation is $RUSTC_WRAPPER $RUSTC_WORKSPACE_WRAPPER $RUSTC.

build.rustdoc

• Type: string (program path)
• Default: "rustdoc"
• Environment: CARGO_BUILD_RUSTDOC or RUSTDOC

Sets the executable to use for rustdoc.

build.target

• Type: string or array of strings
• Default: host platform
• Environment: CARGO_BUILD_TARGET

The default target platform triples to compile to.

This allows passing either a string or an array of strings. Each string value is a target platform triple. The selected build targets will be built for each of the selected architectures.

The string value may also be a relative path to a .json target spec file.

Can be overridden with the --target CLI option.

[build]
target = ["x86_64-unknown-linux-gnu", "i686-unknown-linux-gnu"]

build.target-dir

• Type: string (path)
• Default: "target"
• Environment: CARGO_BUILD_TARGET_DIR or CARGO_TARGET_DIR

The path to where all compiler output is placed. The default if not specified is a directory named target located at the root of the workspace.

Can be overridden with the --target-dir CLI option.

build.rustflags

• Type: string or array of strings
• Default: none
• Environment: CARGO_BUILD_RUSTFLAGS or CARGO_ENCODED_RUSTFLAGS or RUSTFLAGS

Extra command-line flags to pass to rustc. The value may be an array of strings or a space-separated string.

There are four mutually exclusive sources of extra flags. They are checked in order, with the first one being used:

1. CARGO_ENCODED_RUSTFLAGS environment variable.
2. RUSTFLAGS environment variable.
3. All matching target.<triple>.rustflags and target.<cfg>.rustflags config entries joined together.
4. build.rustflags config value.

Additional flags may also be passed with the cargo rustc command.

If the --target flag (or build.target) is used, then the flags will only be passed to the compiler for the target. Things being built for the host, such as build scripts or proc macros, will not receive the args. Without --target, the flags will be passed to all compiler invocations (including build scripts and proc macros) because dependencies are shared. If you have args that you do not want to pass to build scripts or proc macros and are building for the host, pass --target with the host triple.

It is not recommended to pass in flags that Cargo itself usually manages. For example, the flags driven by profiles are best handled by setting the appropriate profile setting.

Caution: Due to the low-level nature of passing flags directly to the compiler, this may cause a conflict with future versions of Cargo which may issue the same or similar flags on its own which may interfere with the flags you specify. This is an area where Cargo may not always be backwards compatible.

build.rustdocflags

• Type: string or array of strings
• Default: none
• Environment: CARGO_BUILD_RUSTDOCFLAGS or CARGO_ENCODED_RUSTDOCFLAGS or RUSTDOCFLAGS

Extra command-line flags to pass to rustdoc. The value may be an array of strings or a space-separated string.

There are four mutually exclusive sources of extra flags. They are checked in order, with the first one being used:

1. CARGO_ENCODED_RUSTDOCFLAGS environment variable.
2. RUSTDOCFLAGS environment variable.
3. All matching target.<triple>.rustdocflags config entries joined together.
4. build.rustdocflags config value.

Additional flags may also be passed with the cargo rustdoc command.

Caution: Due to the low-level nature of passing flags directly to the compiler, this may cause a conflict with future versions of Cargo which may issue the same or similar flags on its own which may interfere with the flags you specify. This is an area where Cargo may not always be backwards compatible.

build.incremental

• Type: bool
• Default: from profile
• Environment: CARGO_BUILD_INCREMENTAL or CARGO_INCREMENTAL

Whether or not to perform incremental compilation. The default if not set is to use the value from the profile. Otherwise this overrides the setting of all profiles.

The CARGO_INCREMENTAL environment variable can be set to 1 to force enable incremental compilation for all profiles, or 0 to disable it. This env var overrides the config setting.

build.dep-info-basedir

• Type: string (path)
• Default: none
• Environment: CARGO_BUILD_DEP_INFO_BASEDIR

Strips the given path prefix from dep info file paths. This config setting is intended to convert absolute paths to relative paths for tools that require relative paths.

The setting itself is a config-relative path. So, for example, a value of "." would strip all paths starting with the parent directory of the .cargo directory.

build.pipelining

This option is deprecated and unused. Cargo always has pipelining enabled.

[credential-alias]

• Type: string or array of strings
• Default: empty
• Environment: CARGO_CREDENTIAL_ALIAS_<name>

The [credential-alias] table defines credential provider aliases. These aliases can be referenced as an element of the registry.global-credential-providers array, or as a credential provider for a specific registry under registries.<NAME>.credential-provider.

If specified as a string, the value will be split on spaces into path and arguments.

For example, to define an alias called my-alias:

[credential-alias]
my-alias = ["/usr/bin/cargo-credential-example", "--argument", "value", "--flag"]

See Registry Authentication for more information.

[doc]

The [doc] table defines options for the cargo doc command.

doc.browser

• Type: string or array of strings (program path with args)
• Default: BROWSER environment variable, or, if that is missing, opening the link in a system specific way

This option sets the browser to be used by cargo doc, overriding the BROWSER environment variable when opening documentation with the --open option.

[cargo-new]

The [cargo-new] table defines defaults for the cargo new command.

cargo-new.name

This option is deprecated and unused.

cargo-new.email

This option is deprecated and unused.

cargo-new.vcs

• Type: string
• Default: "git" or "none"
• Environment: CARGO_CARGO_NEW_VCS

Specifies the source control system to use for initializing a new repository. Valid values are git, hg (for Mercurial), pijul, fossil or none to disable this behavior. Defaults to git, or none if already inside a VCS repository. Can be overridden with the --vcs CLI option.

[env]

The [env] section allows you to set additional environment variables for build scripts, rustc invocations, cargo run and cargo build.

[env]
OPENSSL_DIR = "/opt/openssl"

By default, the variables specified will not override values that already exist in the environment. This behavior can be changed by setting the force flag.

Setting the relative flag evaluates the value as a config-relative path that is relative to the parent directory of the .cargo directory that contains the config.toml file. The value of the environment variable will be the full absolute path.

[env]
TMPDIR = { value = "/home/tmp", force = true }
OPENSSL_DIR = { value = "vendor/openssl", relative = true }

[future-incompat-report]

The [future-incompat-report] table controls setting for future incompat reporting

future-incompat-report.frequency

• Type: string
• Default: "always"
• Environment: CARGO_FUTURE_INCOMPAT_REPORT_FREQUENCY

Controls how often we display a notification to the terminal when a future incompat report is available. Possible values:

• always (default): Always display a notification when a command (e.g. cargo build) produces a future incompat report
• never: Never display a notification

[http]

The [http] table defines settings for HTTP behavior. This includes fetching crate dependencies and accessing remote git repositories.

http.debug

• Type: boolean
• Default: false
• Environment: CARGO_HTTP_DEBUG

If true, enables debugging of HTTP requests. The debug information can be seen by setting the CARGO_LOG=network=debug environment variable (or use network=trace for even more information).

Be wary when posting logs from this output in a public location. The output may include headers with authentication tokens which you don’t want to leak! Be sure to review logs before posting them.

http.proxy

• Type: string
• Default: none
• Environment: CARGO_HTTP_PROXY or HTTPS_PROXY or https_proxy or http_proxy

Sets an HTTP and HTTPS proxy to use. The format is in libcurl format as in [protocol://]host[:port]. If not set, Cargo will also check the http.proxy setting in your global git configuration. If none of those are set, the HTTPS_PROXY or https_proxy environment variables set the proxy for HTTPS requests, and http_proxy sets it for HTTP requests.

http.timeout

• Type: integer
• Default: 30
• Environment: CARGO_HTTP_TIMEOUT or HTTP_TIMEOUT

Sets the timeout for each HTTP request, in seconds.

http.cainfo

• Type: string (path)
• Default: none
• Environment: CARGO_HTTP_CAINFO

Path to a Certificate Authority (CA) bundle file, used to verify TLS certificates. If not specified, Cargo attempts to use the system certificates.

http.check-revoke

• Type: boolean
• Default: true (Windows) false (all others)
• Environment: CARGO_HTTP_CHECK_REVOKE

This determines whether or not TLS certificate revocation checks should be performed. This only works on Windows.

http.ssl-version

• Type: string or min/max table
• Default: none
• Environment: CARGO_HTTP_SSL_VERSION

This sets the minimum TLS version to use. It takes a string, with one of the possible values of "default", "tlsv1", "tlsv1.0", "tlsv1.1", "tlsv1.2", or "tlsv1.3".

This may alternatively take a table with two keys, min and max, which each take a string value of the same kind that specifies the minimum and maximum range of TLS versions to use.

The default is a minimum version of "tlsv1.0" and a max of the newest version supported on your platform, typically "tlsv1.3".

http.low-speed-limit

• Type: integer
• Default: 10
• Environment: CARGO_HTTP_LOW_SPEED_LIMIT

This setting controls timeout behavior for slow connections. If the average transfer speed in bytes per second is below the given value for http.timeout seconds (default 30 seconds), then the connection is considered too slow and Cargo will abort and retry.

http.multiplexing

• Type: boolean
• Default: true
• Environment: CARGO_HTTP_MULTIPLEXING

When true, Cargo will attempt to use the HTTP2 protocol with multiplexing. This allows multiple requests to use the same connection, usually improving performance when fetching multiple files. If false, Cargo will use HTTP 1.1 without pipelining.

http.user-agent

• Type: string
• Default: Cargo’s version
• Environment: CARGO_HTTP_USER_AGENT

Specifies a custom user-agent header to use. The default if not specified is a string that includes Cargo’s version.

[install]

The [install] table defines defaults for the cargo install command.

install.root

• Type: string (path)
• Default: Cargo’s home directory
• Environment: CARGO_INSTALL_ROOT

Sets the path to the root directory for installing executables for cargo install. Executables go into a bin directory underneath the root.

To track information of installed executables, some extra files, such as .crates.toml and .crates2.json, are also created under this root.

The default if not specified is Cargo’s home directory (default .cargo in your home directory).

Can be overridden with the --root command-line option.

[net]

The [net] table controls networking configuration.

net.retry

• Type: integer
• Default: 3
• Environment: CARGO_NET_RETRY

Number of times to retry possibly spurious network errors.

net.git-fetch-with-cli

• Type: boolean
• Default: false
• Environment: CARGO_NET_GIT_FETCH_WITH_CLI

If this is true, then Cargo will use the git executable to fetch registry indexes and git dependencies. If false, then it uses a built-in git library.

Setting this to true can be helpful if you have special authentication requirements that Cargo does not support. See Git Authentication for more information about setting up git authentication.

net.offline

• Type: boolean
• Default: false
• Environment: CARGO_NET_OFFLINE

If this is true, then Cargo will avoid accessing the network, and attempt to proceed with locally cached data. If false, Cargo will access the network as needed, and generate an error if it encounters a network error.

Can be overridden with the --offline command-line option.

net.ssh

The [net.ssh] table contains settings for SSH connections.

net.ssh.known-hosts

• Type: array of strings
• Default: see description
• Environment: not supported

The known-hosts array contains a list of SSH host keys that should be accepted as valid when connecting to an SSH server (such as for SSH git dependencies). Each entry should be a string in a format similar to OpenSSH known_hosts files. Each string should start with one or more hostnames separated by commas, a space, the key type name, a space, and the base64-encoded key. For example:

[net.ssh]
known-hosts = [
    "example.com ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIFO4Q5T0UV0SQevair9PFwoxY9dl4pQl3u5phoqJH3cF"
]

Cargo will attempt to load known hosts keys from common locations supported in OpenSSH, and will join those with any listed in a Cargo configuration file. If any matching entry has the correct key, the connection will be allowed.

Cargo comes with the host keys for github.com built-in. If those ever change, you can add the new keys to the config or known_hosts file.

See Git Authentication for more details.

[patch]

Just as you can override dependencies using [patch] in Cargo.toml, you can override them in the cargo configuration file to apply those patches to any affected build. The format is identical to the one used in Cargo.toml.

Since .cargo/config.toml files are not usually checked into source control, you should prefer patching using Cargo.toml where possible to ensure that other developers can compile your crate in their own environments. Patching through cargo configuration files is generally only appropriate when the patch section is automatically generated by an external build tool.

If a given dependency is patched both in a cargo configuration file and a Cargo.toml file, the patch in the configuration file is used. If multiple configuration files patch the same dependency, standard cargo configuration merging is used, which prefers the value defined closest to the current directory, with $HOME/.cargo/config.toml taking the lowest precedence.

Relative path dependencies in such a [patch] section are resolved relative to the configuration file they appear in.

[profile]

The [profile] table can be used to globally change profile settings, and override settings specified in Cargo.toml. It has the same syntax and options as profiles specified in Cargo.toml. See the Profiles chapter for details about the options.

[profile.<name>.build-override]

• Environment: CARGO_PROFILE_<name>_BUILD_OVERRIDE_<key>

The build-override table overrides settings for build scripts, proc macros, and their dependencies. It has the same keys as a normal profile. See the overrides section for more details.

[profile.<name>.package.<name>]

• Environment: not supported

The package table overrides settings for specific packages. It has the same keys as a normal profile, minus the panic, lto, and rpath settings. See the overrides section for more details.

profile.<name>.codegen-units

• Type: integer
• Default: See profile docs.
• Environment: CARGO_PROFILE_<name>_CODEGEN_UNITS

See codegen-units.

profile.<name>.debug

• Type: integer or boolean
• Default: See profile docs.
• Environment: CARGO_PROFILE_<name>_DEBUG

See debug.

profile.<name>.split-debuginfo

• Type: string
• Default: See profile docs.
• Environment: CARGO_PROFILE_<name>_SPLIT_DEBUGINFO

See split-debuginfo.

profile.<name>.debug-assertions

• Type: boolean
• Default: See profile docs.
• Environment: CARGO_PROFILE_<name>_DEBUG_ASSERTIONS

See debug-assertions.

profile.<name>.incremental

• Type: boolean
• Default: See profile docs.
• Environment: CARGO_PROFILE_<name>_INCREMENTAL

See incremental.

profile.<name>.lto

• Type: string or boolean
• Default: See profile docs.
• Environment: CARGO_PROFILE_<name>_LTO

See lto.

profile.<name>.overflow-checks

• Type: boolean
• Default: See profile docs.
• Environment: CARGO_PROFILE_<name>_OVERFLOW_CHECKS

See overflow-checks.

profile.<name>.opt-level

• Type: integer or string
• Default: See profile docs.
• Environment: CARGO_PROFILE_<name>_OPT_LEVEL

See opt-level.

profile.<name>.panic

• Type: string
• Default: See profile docs.
• Environment: CARGO_PROFILE_<name>_PANIC

See panic.

profile.<name>.rpath

• Type: boolean
• Default: See profile docs.
• Environment: CARGO_PROFILE_<name>_RPATH

See rpath.

profile.<name>.strip

• Type: string or boolean
• Default: See profile docs.
• Environment: CARGO_PROFILE_<name>_STRIP

See strip.

[resolver]

The [resolver] table overrides dependency resolution behavior for local development (e.g. excludes cargo install).

resolver.incompatible-rust-versions

• Type: string
• Default: See resolver docs
• Environment: CARGO_RESOLVER_INCOMPATIBLE_RUST_VERSIONS

When resolving which version of a dependency to use, select how versions with incompatible package.rust-versions are treated. Values include:

• allow: treat rust-version-incompatible versions like any other version
• fallback: only consider rust-version-incompatible versions if no other version matched

Can be overridden with

• --ignore-rust-version CLI option
• Setting the dependency’s version requirement higher than any version with a compatible rust-version
• Specifying the version to cargo update with --precise

See the resolver chapter for more details.

MSRV:

• allow is supported on any version
• fallback is respected as of 1.84

[registries]

The [registries] table is used for specifying additional registries. It consists of a sub-table for each named registry.

registries.<name>.index

• Type: string (url)
• Default: none
• Environment: CARGO_REGISTRIES_<name>_INDEX

Specifies the URL of the index for the registry.

registries.<name>.token

• Type: string
• Default: none
• Environment: CARGO_REGISTRIES_<name>_TOKEN

Specifies the authentication token for the given registry. This value should only appear in the credentials file. This is used for registry commands like cargo publish that require authentication.

Can be overridden with the --token command-line option.

registries.<name>.credential-provider

• Type: string or array of path and arguments
• Default: none
• Environment: CARGO_REGISTRIES_<name>_CREDENTIAL_PROVIDER

Specifies the credential provider for the given registry. If not set, the providers in registry.global-credential-providers will be used.

If specified as a string, path and arguments will be split on spaces. For paths or arguments that contain spaces, use an array.

If the value exists in the [credential-alias] table, the alias will be used.

See Registry Authentication for more information.

registries.crates-io.protocol

• Type: string
• Default: "sparse"
• Environment: CARGO_REGISTRIES_CRATES_IO_PROTOCOL

Specifies the protocol used to access crates.io. Allowed values are git or sparse.

git causes Cargo to clone the entire index of all packages ever published to crates.io from https://github.com/rust-lang/crates.io-index/. This can have performance implications due to the size of the index. sparse is a newer protocol which uses HTTPS to download only what is necessary from https://index.crates.io/. This can result in a significant performance improvement for resolving new dependencies in most situations.

More information about registry protocols may be found in the Registries chapter.

[registry]

The [registry] table controls the default registry used when one is not specified.

registry.index

This value is no longer accepted and should not be used.

registry.default

• Type: string
• Default: "crates-io"
• Environment: CARGO_REGISTRY_DEFAULT

The name of the registry (from the registries table) to use by default for registry commands like cargo publish.

Can be overridden with the --registry command-line option.

registry.credential-provider

• Type: string or array of path and arguments
• Default: none
• Environment: CARGO_REGISTRY_CREDENTIAL_PROVIDER

Specifies the credential provider for crates.io. If not set, the providers in registry.global-credential-providers will be used.

If specified as a string, path and arguments will be split on spaces. For paths or arguments that contain spaces, use an array.

If the value exists in the [credential-alias] table, the alias will be used.

See Registry Authentication for more information.

registry.token

• Type: string
• Default: none
• Environment: CARGO_REGISTRY_TOKEN

Specifies the authentication token for crates.io. This value should only appear in the credentials file. This is used for registry commands like cargo publish that require authentication.

Can be overridden with the --token command-line option.

registry.global-credential-providers

• Type: array
• Default: ["cargo:token"]
• Environment: CARGO_REGISTRY_GLOBAL_CREDENTIAL_PROVIDERS

Specifies the list of global credential providers. If credential provider is not set for a specific registry using registries.<name>.credential-provider, Cargo will use the credential providers in this list. Providers toward the end of the list have precedence.

Path and arguments are split on spaces. If the path or arguments contains spaces, the credential provider should be defined in the [credential-alias] table and referenced here by its alias.

See Registry Authentication for more information.

[source]

The [source] table defines the registry sources available. See Source Replacement for more information. It consists of a sub-table for each named source. A source should only define one kind (directory, registry, local-registry, or git).

source.<name>.replace-with

• Type: string
• Default: none
• Environment: not supported

If set, replace this source with the given named source or named registry.

source.<name>.directory

• Type: string (path)
• Default: none
• Environment: not supported

Sets the path to a directory to use as a directory source.

source.<name>.registry

• Type: string (url)
• Default: none
• Environment: not supported

Sets the URL to use for a registry source.

source.<name>.local-registry

• Type: string (path)
• Default: none
• Environment: not supported

Sets the path to a directory to use as a local registry source.

source.<name>.git

• Type: string (url)
• Default: none
• Environment: not supported

Sets the URL to use for a git repository source.

source.<name>.branch

• Type: string
• Default: none
• Environment: not supported

Sets the branch name to use for a git repository.

If none of branch, tag, or rev is set, defaults to the master branch.

source.<name>.tag

• Type: string
• Default: none
• Environment: not supported

Sets the tag name to use for a git repository.

If none of branch, tag, or rev is set, defaults to the master branch.

source.<name>.rev

• Type: string
• Default: none
• Environment: not supported

Sets the revision to use for a git repository.

If none of branch, tag, or rev is set, defaults to the master branch.

[target]

The [target] table is used for specifying settings for specific platform targets. It consists of a sub-table which is either a platform triple or a cfg() expression. The given values will be used if the target platform matches either the <triple> value or the <cfg> expression.

[target.thumbv7m-none-eabi]
linker = "arm-none-eabi-gcc"
runner = "my-emulator"
rustflags = ["…", "…"]

[target.'cfg(all(target_arch = "arm", target_os = "none"))']
runner = "my-arm-wrapper"
rustflags = ["…", "…"]

cfg values come from those built-in to the compiler (run rustc --print=cfg to view) and extra --cfg flags passed to rustc (such as those defined in RUSTFLAGS). Do not try to match on debug_assertions, test, Cargo features like feature="foo", or values set by build scripts.

If using a target spec JSON file, the <triple> value is the filename stem. For example --target foo/bar.json would match [target.bar].

target.<triple>.ar

This option is deprecated and unused.

target.<triple>.linker

• Type: string (program path)
• Default: none
• Environment: CARGO_TARGET_<triple>_LINKER

Specifies the linker which is passed to rustc (via -C linker) when the <triple> is being compiled for. By default, the linker is not overridden.

target.<cfg>.linker

This is similar to the target linker, but using a cfg() expression. If both a <triple> and <cfg> runner match, the <triple> will take precedence. It is an error if more than one <cfg> runner matches the current target.

target.<triple>.runner

• Type: string or array of strings (program path with args)
• Default: none
• Environment: CARGO_TARGET_<triple>_RUNNER

If a runner is provided, executables for the target <triple> will be executed by invoking the specified runner with the actual executable passed as an argument. This applies to cargo run, cargo test and cargo bench commands. By default, compiled executables are executed directly.

target.<cfg>.runner

This is similar to the target runner, but using a cfg() expression. If both a <triple> and <cfg> runner match, the <triple> will take precedence. It is an error if more than one <cfg> runner matches the current target.

target.<triple>.rustflags

• Type: string or array of strings
• Default: none
• Environment: CARGO_TARGET_<triple>_RUSTFLAGS

Passes a set of custom flags to the compiler for this <triple>. The value may be an array of strings or a space-separated string.

See build.rustflags for more details on the different ways to specific extra flags.

target.<cfg>.rustflags

This is similar to the target rustflags, but using a cfg() expression. If several <cfg> and <triple> entries match the current target, the flags are joined together.

target.<triple>.rustdocflags

• Type: string or array of strings
• Default: none
• Environment: CARGO_TARGET_<triple>_RUSTDOCFLAGS

Passes a set of custom flags to the compiler for this <triple>. The value may be an array of strings or a space-separated string.

See build.rustdocflags for more details on the different ways to specific extra flags.

target.<triple>.<links>

The links sub-table provides a way to override a build script. When specified, the build script for the given links library will not be run, and the given values will be used instead.

[target.x86_64-unknown-linux-gnu.foo]
rustc-link-lib = ["foo"]
rustc-link-search = ["/path/to/foo"]
rustc-flags = "-L /some/path"
rustc-cfg = ['key="value"']
rustc-env = {key = "value"}
rustc-cdylib-link-arg = ["…"]
metadata_key1 = "value"
metadata_key2 = "value"

[term]

The [term] table controls terminal output and interaction.

term.quiet

• Type: boolean
• Default: false
• Environment: CARGO_TERM_QUIET

Controls whether or not log messages are displayed by Cargo.

Specifying the --quiet flag will override and force quiet output. Specifying the --verbose flag will override and disable quiet output.

term.verbose

• Type: boolean
• Default: false
• Environment: CARGO_TERM_VERBOSE

Controls whether or not extra detailed messages are displayed by Cargo.

Specifying the --quiet flag will override and disable verbose output. Specifying the --verbose flag will override and force verbose output.

term.color

• Type: string
• Default: "auto"
• Environment: CARGO_TERM_COLOR

Controls whether or not colored output is used in the terminal. Possible values:

• auto (default): Automatically detect if color support is available on the terminal.
• always: Always display colors.
• never: Never display colors.

Can be overridden with the --color command-line option.

term.hyperlinks

• Type: bool
• Default: auto-detect
• Environment: CARGO_TERM_HYPERLINKS

Controls whether or not hyperlinks are used in the terminal.

term.unicode

• Type: bool
• Default: auto-detect
• Environment: CARGO_TERM_UNICODE

Control whether output can be rendered using non-ASCII unicode characters.

term.progress.when

• Type: string
• Default: "auto"
• Environment: CARGO_TERM_PROGRESS_WHEN

Controls whether or not progress bar is shown in the terminal. Possible values:

• auto (default): Intelligently guess whether to show progress bar.
• always: Always show progress bar.
• never: Never show progress bar.

term.progress.width

• Type: integer
• Default: none
• Environment: CARGO_TERM_PROGRESS_WIDTH

Sets the width for progress bar.

Environment Variables

Cargo sets and reads a number of environment variables which your code can detect or override. Here is a list of the variables Cargo sets, organized by when it interacts with them:

Environment variables Cargo reads

You can override these environment variables to change Cargo’s behavior on your system:

• CARGO_LOG — Cargo uses the tracing crate to display debug log messages. The CARGO_LOG environment variable can be set to enable debug logging, with a value such as trace, debug, or warn. Usually it is only used during debugging. For more details refer to the Debug logging.
• CARGO_HOME — Cargo maintains a local cache of the registry index and of git checkouts of crates. By default these are stored under $HOME/.cargo (%USERPROFILE%\.cargo on Windows), but this variable overrides the location of this directory. Once a crate is cached it is not removed by the clean command. For more details refer to the guide.
• CARGO_TARGET_DIR — Location of where to place all generated artifacts, relative to the current working directory. See build.target-dir to set via config.
• CARGO — If set, Cargo will forward this value instead of setting it to its own auto-detected path when it builds crates and when it executes build scripts and external subcommands. This value is not directly executed by Cargo, and should always point at a command that behaves exactly like cargo, as that’s what users of the variable will be expecting.
• RUSTC — Instead of running rustc, Cargo will execute this specified compiler instead. See build.rustc to set via config.
• RUSTC_WRAPPER — Instead of simply running rustc, Cargo will execute this specified wrapper, passing as its command-line arguments the rustc invocation, with the first argument being the path to the actual rustc. Useful to set up a build cache tool such as sccache. See build.rustc-wrapper to set via config. Setting this to the empty string overwrites the config and resets cargo to not use a wrapper.
• RUSTC_WORKSPACE_WRAPPER — Instead of simply running rustc, for workspace members Cargo will execute this specified wrapper, passing as its command-line arguments the rustc invocation, with the first argument being the path to the actual rustc. When building a single-package project without workspaces, that package is considered to be the workspace. It affects the filename hash so that artifacts produced by the wrapper are cached separately. See build.rustc-workspace-wrapper to set via config. Setting this to the empty string overwrites the config and resets cargo to not use a wrapper for workspace members. If both RUSTC_WRAPPER and RUSTC_WORKSPACE_WRAPPER are set, then they will be nested: the final invocation is $RUSTC_WRAPPER $RUSTC_WORKSPACE_WRAPPER $RUSTC.
• RUSTDOC — Instead of running rustdoc, Cargo will execute this specified rustdoc instance instead. See build.rustdoc to set via config.
• RUSTDOCFLAGS — A space-separated list of custom flags to pass to all rustdoc invocations that Cargo performs. In contrast with cargo rustdoc, this is useful for passing a flag to all rustdoc instances. See build.rustdocflags for some more ways to set flags. This string is split by whitespace; for a more robust encoding of multiple arguments, see CARGO_ENCODED_RUSTDOCFLAGS.
• CARGO_ENCODED_RUSTDOCFLAGS — A list of custom flags separated by 0x1f (ASCII Unit Separator) to pass to all rustdoc invocations that Cargo performs.
• RUSTFLAGS — A space-separated list of custom flags to pass to all compiler invocations that Cargo performs. In contrast with cargo rustc, this is useful for passing a flag to all compiler instances. See build.rustflags for some more ways to set flags. This string is split by whitespace; for a more robust encoding of multiple arguments, see CARGO_ENCODED_RUSTFLAGS.
• CARGO_ENCODED_RUSTFLAGS — A list of custom flags separated by 0x1f (ASCII Unit Separator) to pass to all compiler invocations that Cargo performs.
• CARGO_INCREMENTAL — If this is set to 1 then Cargo will force incremental compilation to be enabled for the current compilation, and when set to 0 it will force disabling it. If this env var isn’t present then cargo’s defaults will otherwise be used. See also build.incremental config value.
• CARGO_CACHE_RUSTC_INFO — If this is set to 0 then Cargo will not try to cache compiler version information.
• HTTPS_PROXY or https_proxy or http_proxy — The HTTP proxy to use, see http.proxy for more detail.
• HTTP_TIMEOUT — The HTTP timeout in seconds, see http.timeout for more detail.
• TERM — If this is set to dumb, it disables the progress bar.
• BROWSER — The web browser to execute to open documentation with cargo doc’s’ --open flag, see doc.browser for more details.
• RUSTFMT — Instead of running rustfmt, cargo fmt will execute this specified rustfmt instance instead.

Configuration environment variables

Cargo reads environment variables for some configuration values. See the configuration chapter for more details. In summary, the supported environment variables are:

• CARGO_ALIAS_<name> — Command aliases, see alias.
• CARGO_BUILD_JOBS — Number of parallel jobs, see build.jobs.
• CARGO_BUILD_RUSTC — The rustc executable, see build.rustc.
• CARGO_BUILD_RUSTC_WRAPPER — The rustc wrapper, see build.rustc-wrapper.
• CARGO_BUILD_RUSTC_WORKSPACE_WRAPPER — The rustc wrapper for workspace members only, see build.rustc-workspace-wrapper.
• CARGO_BUILD_RUSTDOC — The rustdoc executable, see build.rustdoc.
• CARGO_BUILD_TARGET — The default target platform, see build.target.
• CARGO_BUILD_TARGET_DIR — The default output directory, see build.target-dir.
• CARGO_BUILD_RUSTFLAGS — Extra rustc flags, see build.rustflags.
• CARGO_BUILD_RUSTDOCFLAGS — Extra rustdoc flags, see build.rustdocflags.
• CARGO_BUILD_INCREMENTAL — Incremental compilation, see build.incremental.
• CARGO_BUILD_DEP_INFO_BASEDIR — Dep-info relative directory, see build.dep-info-basedir.
• CARGO_CARGO_NEW_VCS — The default source control system with cargo new, see cargo-new.vcs.
• CARGO_FUTURE_INCOMPAT_REPORT_FREQUENCY — How often we should generate a future incompat report notification, see future-incompat-report.frequency.
• CARGO_HTTP_DEBUG — Enables HTTP debugging, see http.debug.
• CARGO_HTTP_PROXY — Enables HTTP proxy, see http.proxy.
• CARGO_HTTP_TIMEOUT — The HTTP timeout, see http.timeout.
• CARGO_HTTP_CAINFO — The TLS certificate Certificate Authority file, see http.cainfo.
• CARGO_HTTP_CHECK_REVOKE — Disables TLS certificate revocation checks, see http.check-revoke.
• CARGO_HTTP_SSL_VERSION — The TLS version to use, see http.ssl-version.
• CARGO_HTTP_LOW_SPEED_LIMIT — The HTTP low-speed limit, see http.low-speed-limit.
• CARGO_HTTP_MULTIPLEXING — Whether HTTP/2 multiplexing is used, see http.multiplexing.
• CARGO_HTTP_USER_AGENT — The HTTP user-agent header, see http.user-agent.
• CARGO_INSTALL_ROOT — The default directory for cargo install, see install.root.
• CARGO_NET_RETRY — Number of times to retry network errors, see net.retry.
• CARGO_NET_GIT_FETCH_WITH_CLI — Enables the use of the git executable to fetch, see net.git-fetch-with-cli.
• CARGO_NET_OFFLINE — Offline mode, see net.offline.
• CARGO_PROFILE_<name>_BUILD_OVERRIDE_<key> — Override build script profile, see profile.<name>.build-override.
• CARGO_PROFILE_<name>_CODEGEN_UNITS — Set code generation units, see profile.<name>.codegen-units.
• CARGO_PROFILE_<name>_DEBUG — What kind of debug info to include, see profile.<name>.debug.
• CARGO_PROFILE_<name>_DEBUG_ASSERTIONS — Enable/disable debug assertions, see profile.<name>.debug-assertions.
• CARGO_PROFILE_<name>_INCREMENTAL — Enable/disable incremental compilation, see profile.<name>.incremental.
• CARGO_PROFILE_<name>_LTO — Link-time optimization, see profile.<name>.lto.
• CARGO_PROFILE_<name>_OVERFLOW_CHECKS — Enable/disable overflow checks, see profile.<name>.overflow-checks.
• CARGO_PROFILE_<name>_OPT_LEVEL — Set the optimization level, see profile.<name>.opt-level.
• CARGO_PROFILE_<name>_PANIC — The panic strategy to use, see profile.<name>.panic.
• CARGO_PROFILE_<name>_RPATH — The rpath linking option, see profile.<name>.rpath.
• CARGO_PROFILE_<name>_SPLIT_DEBUGINFO — Controls debug file output behavior, see profile.<name>.split-debuginfo.
• CARGO_PROFILE_<name>_STRIP — Controls stripping of symbols and/or debuginfos, see profile.<name>.strip.
• CARGO_REGISTRIES_<name>_CREDENTIAL_PROVIDER — Credential provider for a registry, see registries.<name>.credential-provider.
• CARGO_REGISTRIES_<name>_INDEX — URL of a registry index, see registries.<name>.index.
• CARGO_REGISTRIES_<name>_TOKEN — Authentication token of a registry, see registries.<name>.token.
• CARGO_REGISTRY_CREDENTIAL_PROVIDER — Credential provider for crates.io, see registry.credential-provider.
• CARGO_REGISTRY_DEFAULT — Default registry for the --registry flag, see registry.default.
• CARGO_REGISTRY_GLOBAL_CREDENTIAL_PROVIDERS — Credential providers for registries that do not have a specific provider defined. See registry.global-credential-providers.
• CARGO_REGISTRY_TOKEN — Authentication token for crates.io, see registry.token.
• CARGO_TARGET_<triple>_LINKER — The linker to use, see target.<triple>.linker. The triple must be converted to uppercase and underscores.
• CARGO_TARGET_<triple>_RUNNER — The executable runner, see target.<triple>.runner.
• CARGO_TARGET_<triple>_RUSTFLAGS — Extra rustc flags for a target, see target.<triple>.rustflags.
• CARGO_TERM_QUIET — Quiet mode, see term.quiet.
• CARGO_TERM_VERBOSE — The default terminal verbosity, see term.verbose.
• CARGO_TERM_COLOR — The default color mode, see term.color.
• CARGO_TERM_PROGRESS_WHEN — The default progress bar showing mode, see term.progress.when.
• CARGO_TERM_PROGRESS_WIDTH — The default progress bar width, see term.progress.width.

Environment variables Cargo sets for crates

Cargo exposes these environment variables to your crate when it is compiled. Note that this applies for running binaries with cargo run and cargo test as well. To get the value of any of these variables in a Rust program, do this:

let version = env!("CARGO_PKG_VERSION");

version will now contain the value of CARGO_PKG_VERSION.

Note that if one of these values is not provided in the manifest, the corresponding environment variable is set to the empty string, "".

• CARGO — Path to the cargo binary performing the build.
• CARGO_MANIFEST_DIR — The directory containing the manifest of your package.
• CARGO_MANIFEST_PATH — The path to the manifest of your package.
• CARGO_PKG_VERSION — The full version of your package.
• CARGO_PKG_VERSION_MAJOR — The major version of your package.
• CARGO_PKG_VERSION_MINOR — The minor version of your package.
• CARGO_PKG_VERSION_PATCH — The patch version of your package.
• CARGO_PKG_VERSION_PRE — The pre-release version of your package.
• CARGO_PKG_AUTHORS — Colon separated list of authors from the manifest of your package.
• CARGO_PKG_NAME — The name of your package.
• CARGO_PKG_DESCRIPTION — The description from the manifest of your package.
• CARGO_PKG_HOMEPAGE — The home page from the manifest of your package.
• CARGO_PKG_REPOSITORY — The repository from the manifest of your package.
• CARGO_PKG_LICENSE — The license from the manifest of your package.
• CARGO_PKG_LICENSE_FILE — The license file from the manifest of your package.
• CARGO_PKG_RUST_VERSION — The Rust version from the manifest of your package. Note that this is the minimum Rust version supported by the package, not the current Rust version.
• CARGO_PKG_README — Path to the README file of your package.
• CARGO_CRATE_NAME — The name of the crate that is currently being compiled. It is the name of the Cargo target with - converted to _, such as the name of the library, binary, example, integration test, or benchmark.
• CARGO_BIN_NAME — The name of the binary that is currently being compiled. Only set for binaries or binary examples. This name does not include any file extension, such as .exe.
• OUT_DIR — If the package has a build script, this is set to the folder where the build script should place its output. See below for more information. (Only set during compilation.)
• CARGO_BIN_EXE_<name> — The absolute path to a binary target’s executable. This is only set when building an integration test or benchmark. This may be used with the env macro to find the executable to run for testing purposes. The <name> is the name of the binary target, exactly as-is. For example, CARGO_BIN_EXE_my-program for a binary named my-program. Binaries are automatically built when the test is built, unless the binary has required features that are not enabled.
• CARGO_PRIMARY_PACKAGE — This environment variable will be set if the package being built is primary. Primary packages are the ones the user selected on the command-line, either with -p flags or the defaults based on the current directory and the default workspace members. This variable will not be set when building dependencies, unless a dependency is also a workspace member that was also selected on the command-line. This is only set when compiling the package (not when running binaries or tests).
• CARGO_TARGET_TMPDIR — Only set when building integration test or benchmark code. This is a path to a directory inside the target directory where integration tests or benchmarks are free to put any data needed by the tests/benches. Cargo initially creates this directory but doesn’t manage its content in any way, this is the responsibility of the test code.

Dynamic library paths

Cargo also sets the dynamic library path when compiling and running binaries with commands like cargo run and cargo test. This helps with locating shared libraries that are part of the build process. The variable name depends on the platform:

• Windows: PATH
• macOS: DYLD_FALLBACK_LIBRARY_PATH
• Unix: LD_LIBRARY_PATH
• AIX: LIBPATH

The value is extended from the existing value when Cargo starts. macOS has special consideration where if DYLD_FALLBACK_LIBRARY_PATH is not already set, it will add the default $HOME/lib:/usr/local/lib:/usr/lib.

Cargo includes the following paths:

• Search paths included from any build script with the rustc-link-search instruction. Paths outside of the target directory are removed. It is the responsibility of the user running Cargo to properly set the environment if additional libraries on the system are needed in the search path.
• The base output directory, such as target/debug, and the “deps” directory. This is mostly for support of proc-macros.
• The rustc sysroot library path. This generally is not important to most users.

Environment variables Cargo sets for build scripts

Cargo sets several environment variables when build scripts are run. Because these variables are not yet set when the build script is compiled, the above example using env! won’t work and instead you’ll need to retrieve the values when the build script is run:

use std::env;
let out_dir = env::var("OUT_DIR").unwrap();

out_dir will now contain the value of OUT_DIR.

• CARGO — Path to the cargo binary performing the build.
• CARGO_MANIFEST_DIR — The directory containing the manifest for the package being built (the package containing the build script). Also note that this is the value of the current working directory of the build script when it starts.
• CARGO_MANIFEST_PATH — The path to the manifest of your package.
• CARGO_MANIFEST_LINKS — the manifest links value.
• CARGO_MAKEFLAGS — Contains parameters needed for Cargo’s jobserver implementation to parallelize subprocesses. Rustc or cargo invocations from build.rs can already read CARGO_MAKEFLAGS, but GNU Make requires the flags to be specified either directly as arguments, or through the MAKEFLAGS environment variable. Currently Cargo doesn’t set the MAKEFLAGS variable, but it’s free for build scripts invoking GNU Make to set it to the contents of CARGO_MAKEFLAGS.
• CARGO_FEATURE_<name> — For each activated feature of the package being built, this environment variable will be present where <name> is the name of the feature uppercased and having - translated to _.
• CARGO_CFG_<cfg> — For each configuration option of the package being built, this environment variable will contain the value of the configuration, where <cfg> is the name of the configuration uppercased and having - translated to _. Boolean configurations are present if they are set, and not present otherwise. Configurations with multiple values are joined to a single variable with the values delimited by ,. This includes values built-in to the compiler (which can be seen with rustc --print=cfg) and values set by build scripts and extra flags passed to rustc (such as those defined in RUSTFLAGS). Some examples of what these variables are:
  • CARGO_CFG_UNIX — Set on unix-like platforms.
  • CARGO_CFG_WINDOWS — Set on windows-like platforms.
  • CARGO_CFG_TARGET_FAMILY=unix,wasm — The target family.
  • CARGO_CFG_TARGET_OS=macos — The target operating system.
  • CARGO_CFG_TARGET_ARCH=x86_64 — The CPU target architecture.
  • CARGO_CFG_TARGET_VENDOR=apple — The target vendor.
  • CARGO_CFG_TARGET_ENV=gnu — The target environment ABI.
  • CARGO_CFG_TARGET_ABI=sim — The target ABI.
  • CARGO_CFG_TARGET_POINTER_WIDTH=64 — The CPU pointer width.
  • CARGO_CFG_TARGET_ENDIAN=little — The CPU target endianness.
  • CARGO_CFG_TARGET_FEATURE=mmx,sse — List of CPU target features enabled.

  Note that different target triples have different sets of cfg values, hence variables present in one target triple might not be available in the other.

  Some cfg values like debug_assertions, test, and Cargo features like feature="foo" are not available.

• OUT_DIR — the folder in which all output and intermediate artifacts should be placed. This folder is inside the build directory for the package being built, and it is unique for the package in question.
• TARGET — the target triple that is being compiled for. Native code should be compiled for this triple. See the Target Triple description for more information.
• HOST — the host triple of the Rust compiler.
• NUM_JOBS — the parallelism specified as the top-level parallelism. This can be useful to pass a -j parameter to a system like make. Note that care should be taken when interpreting this environment variable. For historical purposes this is still provided but recent versions of Cargo, for example, do not need to run make -j, and instead can set the MAKEFLAGS env var to the content of CARGO_MAKEFLAGS to activate the use of Cargo’s GNU Make compatible jobserver for sub-make invocations.
• OPT_LEVEL, DEBUG — values of the corresponding variables for the profile currently being built.
• PROFILE — release for release builds, debug for other builds. This is determined based on if the profile inherits from the dev or release profile. Using this environment variable is not recommended. Using other environment variables like OPT_LEVEL provide a more correct view of the actual settings being used.
• DEP_<name>_<key> — For more information about this set of environment variables, see build script documentation about links.
• RUSTC, RUSTDOC — the compiler and documentation generator that Cargo has resolved to use, passed to the build script so it might use it as well.
• RUSTC_WRAPPER — the rustc wrapper, if any, that Cargo is using. See build.rustc-wrapper.
• RUSTC_WORKSPACE_WRAPPER — the rustc wrapper, if any, that Cargo is using for workspace members. See build.rustc-workspace-wrapper.
• RUSTC_LINKER — The path to the linker binary that Cargo has resolved to use for the current target, if specified. The linker can be changed by editing .cargo/config.toml; see the documentation about cargo configuration for more information.
• CARGO_ENCODED_RUSTFLAGS — extra flags that Cargo invokes rustc with, separated by a 0x1f character (ASCII Unit Separator). See build.rustflags. Note that since Rust 1.55, RUSTFLAGS is removed from the environment; scripts should use CARGO_ENCODED_RUSTFLAGS instead.
• CARGO_PKG_<var> — The package information variables, with the same names and values as are provided during crate building.

Environment variables Cargo sets for 3rd party subcommands

Cargo exposes this environment variable to 3rd party subcommands (ie. programs named cargo-foobar placed in $PATH):

• CARGO — Path to the cargo binary performing the build.
• CARGO_MAKEFLAGS — Contains parameters needed for Cargo’s jobserver implementation to parallelize subprocesses. This is set only when Cargo detects the existence of a jobserver.

For extended information about your environment you may run cargo metadata.

Build Scripts

Some packages need to compile third-party non-Rust code, for example C libraries. Other packages need to link to C libraries which can either be located on the system or possibly need to be built from source. Others still need facilities for functionality such as code generation before building (think parser generators).

Cargo does not aim to replace other tools that are well-optimized for these tasks, but it does integrate with them with custom build scripts. Placing a file named build.rs in the root of a package will cause Cargo to compile that script and execute it just before building the package.

// Example custom build script.
fn main() {
    // Tell Cargo that if the given file changes, to rerun this build script.
    println!("cargo::rerun-if-changed=src/hello.c");
    // Use the `cc` crate to build a C file and statically link it.
    cc::Build::new()
        .file("src/hello.c")
        .compile("hello");
}

Some example use cases of build scripts are:

• Building a bundled C library.
• Finding a C library on the host system.
• Generating a Rust module from a specification.
• Performing any platform-specific configuration needed for the crate.

The sections below describe how build scripts work, and the examples chapter shows a variety of examples on how to write scripts.

Note: The package.build manifest key can be used to change the name of the build script, or disable it entirely.

Life Cycle of a Build Script

Just before a package is built, Cargo will compile a build script into an executable (if it has not already been built). It will then run the script, which may perform any number of tasks. The script may communicate with Cargo by printing specially formatted commands prefixed with cargo:: to stdout.

The build script will be rebuilt if any of its source files or dependencies change.

By default, Cargo will re-run the build script if any of the files in the package changes. Typically it is best to use the rerun-if commands, described in the change detection section below, to narrow the focus of what triggers a build script to run again.

Once the build script successfully finishes executing, the rest of the package will be compiled. Scripts should exit with a non-zero exit code to halt the build if there is an error, in which case the build script’s output will be displayed on the terminal.

Inputs to the Build Script

When the build script is run, there are a number of inputs to the build script, all passed in the form of environment variables.

In addition to environment variables, the build script’s current directory is the source directory of the build script’s package.

Outputs of the Build Script

Build scripts may save any output files or intermediate artifacts in the directory specified in the OUT_DIR environment variable. Scripts should not modify any files outside of that directory.

Build scripts communicate with Cargo by printing to stdout. Cargo will interpret each line that starts with cargo:: as an instruction that will influence compilation of the package. All other lines are ignored.

The order of cargo:: instructions printed by the build script may affect the order of arguments that cargo passes to rustc. In turn, the order of arguments passed to rustc may affect the order of arguments passed to the linker. Therefore, you will want to pay attention to the order of the build script’s instructions. For example, if object foo needs to link against library bar, you may want to make sure that library bar’s cargo::rustc-link-lib instruction appears after instructions to link object foo.

The output of the script is hidden from the terminal during normal compilation. If you would like to see the output directly in your terminal, invoke Cargo as “very verbose” with the -vv flag. This only happens when the build script is run. If Cargo determines nothing has changed, it will not re-run the script, see change detection below for more.

All the lines printed to stdout by a build script are written to a file like target/debug/build/<pkg>/output (the precise location may depend on your configuration). The stderr output is also saved in that same directory.

The following is a summary of the instructions that Cargo recognizes, with each one detailed below.

• cargo::rerun-if-changed=PATH — Tells Cargo when to re-run the script.
• cargo::rerun-if-env-changed=VAR — Tells Cargo when to re-run the script.
• cargo::rustc-link-arg=FLAG — Passes custom flags to a linker for benchmarks, binaries, cdylib crates, examples, and tests.
• cargo::rustc-link-arg-bin=BIN=FLAG — Passes custom flags to a linker for the binary BIN.
• cargo::rustc-link-arg-bins=FLAG — Passes custom flags to a linker for binaries.
• cargo::rustc-link-arg-tests=FLAG — Passes custom flags to a linker for tests.
• cargo::rustc-link-arg-examples=FLAG — Passes custom flags to a linker for examples.
• cargo::rustc-link-arg-benches=FLAG — Passes custom flags to a linker for benchmarks.
• cargo::rustc-link-lib=LIB — Adds a library to link.
• cargo::rustc-link-search=[KIND=]PATH — Adds to the library search path.
• cargo::rustc-flags=FLAGS — Passes certain flags to the compiler.
• cargo::rustc-cfg=KEY[="VALUE"] — Enables compile-time cfg settings.
• cargo::rustc-check-cfg=CHECK_CFG – Register custom cfgs as expected for compile-time checking of configs.
• cargo::rustc-env=VAR=VALUE — Sets an environment variable.
• cargo::rustc-cdylib-link-arg=FLAG — Passes custom flags to a linker for cdylib crates.

• cargo::error=MESSAGE — Displays an error on the terminal.

• cargo::warning=MESSAGE — Displays a warning on the terminal.
• cargo::metadata=KEY=VALUE — Metadata, used by links scripts.

MSRV: 1.77 is required for cargo::KEY=VALUE syntax. To support older versions, use the cargo:KEY=VALUE syntax.

cargo::rustc-link-arg=FLAG

The rustc-link-arg instruction tells Cargo to pass the -C link-arg=FLAG option to the compiler, but only when building supported targets (benchmarks, binaries, cdylib crates, examples, and tests). Its usage is highly platform specific. It is useful to set the shared library version or linker script.

cargo::rustc-link-arg-bin=BIN=FLAG

The rustc-link-arg-bin instruction tells Cargo to pass the -C link-arg=FLAG option to the compiler, but only when building the binary target with name BIN. Its usage is highly platform specific. It is useful to set a linker script or other linker options.

cargo::rustc-link-arg-bins=FLAG

The rustc-link-arg-bins instruction tells Cargo to pass the -C link-arg=FLAG option to the compiler, but only when building a binary target. Its usage is highly platform specific. It is useful to set a linker script or other linker options.

cargo::rustc-link-lib=LIB

The rustc-link-lib instruction tells Cargo to link the given library using the compiler’s -l flag. This is typically used to link a native library using FFI.

The LIB string is passed directly to rustc, so it supports any syntax that -l does.
Currently the fully supported syntax for LIB is [KIND[:MODIFIERS]=]NAME[:RENAME].

The -l flag is only passed to the library target of the package, unless there is no library target, in which case it is passed to all targets. This is done because all other targets have an implicit dependency on the library target, and the given library to link should only be included once. This means that if a package has both a library and a binary target, the library has access to the symbols from the given lib, and the binary should access them through the library target’s public API.

The optional KIND may be one of dylib, static, or framework. See the rustc book for more detail.

cargo::rustc-link-arg-tests=FLAG

The rustc-link-arg-tests instruction tells Cargo to pass the -C link-arg=FLAG option to the compiler, but only when building a tests target.

cargo::rustc-link-arg-examples=FLAG

The rustc-link-arg-examples instruction tells Cargo to pass the -C link-arg=FLAG option to the compiler, but only when building an examples target.

cargo::rustc-link-arg-benches=FLAG

The rustc-link-arg-benches instruction tells Cargo to pass the -C link-arg=FLAG option to the compiler, but only when building a benchmark target.

cargo::rustc-link-search=[KIND=]PATH

The rustc-link-search instruction tells Cargo to pass the -L flag to the compiler to add a directory to the library search path.

The optional KIND may be one of dependency, crate, native, framework, or all. See the rustc book for more detail.

These paths are also added to the dynamic library search path environment variable if they are within the OUT_DIR. Depending on this behavior is discouraged since this makes it difficult to use the resulting binary. In general, it is best to avoid creating dynamic libraries in a build script (using existing system libraries is fine).

cargo::rustc-flags=FLAGS

The rustc-flags instruction tells Cargo to pass the given space-separated flags to the compiler. This only allows the -l and -L flags, and is equivalent to using rustc-link-lib and rustc-link-search.

cargo::rustc-cfg=KEY[="VALUE"]

The rustc-cfg instruction tells Cargo to pass the given value to the --cfg flag to the compiler. This may be used for compile-time detection of features to enable conditional compilation. Custom cfgs must either be expected using the cargo::rustc-check-cfg instruction or usage will need to allow the unexpected_cfgs lint to avoid unexpected cfgs warnings.

Note that this does not affect Cargo’s dependency resolution. This cannot be used to enable an optional dependency, or enable other Cargo features.

Be aware that Cargo features use the form feature="foo". cfg values passed with this flag are not restricted to that form, and may provide just a single identifier, or any arbitrary key/value pair. For example, emitting cargo::rustc-cfg=abc will then allow code to use #[cfg(abc)] (note the lack of feature=). Or an arbitrary key/value pair may be used with an = symbol like cargo::rustc-cfg=my_component="foo". The key should be a Rust identifier, the value should be a string.

cargo::rustc-check-cfg=CHECK_CFG

Add to the list of expected config names and values that is used when checking the reachable cfg expressions with the unexpected_cfgs lint.

The syntax of CHECK_CFG mirrors the rustc --check-cfg flag, see Checking conditional configurations for more details.

The instruction can be used like this:

#![allow(unused)]
fn main() {
// build.rs
println!("cargo::rustc-check-cfg=cfg(foo, values(\"bar\"))");
if foo_bar_condition {
    println!("cargo::rustc-cfg=foo=\"bar\"");
}
}

Note that all possible cfgs should be defined, regardless of which cfgs are currently enabled. This includes all possible values of a given cfg name.

It is recommended to group the cargo::rustc-check-cfg and cargo::rustc-cfg instructions as closely as possible in order to avoid typos, missing check-cfg, stale cfgs…

See also the conditional compilation example.

MSRV: Respected as of 1.80

cargo::rustc-env=VAR=VALUE

The rustc-env instruction tells Cargo to set the given environment variable when compiling the package. The value can be then retrieved by the env! macro in the compiled crate. This is useful for embedding additional metadata in crate’s code, such as the hash of git HEAD or the unique identifier of a continuous integration server.

See also the environment variables automatically included by Cargo.

Note: These environment variables are also set when running an executable with cargo run or cargo test. However, this usage is discouraged since it ties the executable to Cargo’s execution environment. Normally, these environment variables should only be checked at compile-time with the env! macro.

cargo::rustc-cdylib-link-arg=FLAG

The rustc-cdylib-link-arg instruction tells Cargo to pass the -C link-arg=FLAG option to the compiler, but only when building a cdylib library target. Its usage is highly platform specific. It is useful to set the shared library version or the runtime-path.

cargo::error=MESSAGE

The error instruction tells Cargo to display an error after the build script has finished running, and then fail the build.

Note: Build script libraries should carefully consider if they want to use cargo::error versus returning a Result. It may be better to return a Result, and allow the caller to decide if the error is fatal or not. The caller can then decide whether or not to display the Err variant using cargo::error.

MSRV: Respected as of 1.84

cargo::warning=MESSAGE

The warning instruction tells Cargo to display a warning after the build script has finished running. Warnings are only shown for path dependencies (that is, those you’re working on locally), so for example warnings printed out in crates.io crates are not emitted by default, unless the build fails. The -vv “very verbose” flag may be used to have Cargo display warnings for all crates.

Build Dependencies

Build scripts are also allowed to have dependencies on other Cargo-based crates. Dependencies are declared through the build-dependencies section of the manifest.

[build-dependencies]
cc = "1.0.46"

The build script does not have access to the dependencies listed in the dependencies or dev-dependencies section (they’re not built yet!). Also, build dependencies are not available to the package itself unless also explicitly added in the [dependencies] table.

It is recommended to carefully consider each dependency you add, weighing against the impact on compile time, licensing, maintenance, etc. Cargo will attempt to reuse a dependency if it is shared between build dependencies and normal dependencies. However, this is not always possible, for example when cross-compiling, so keep that in consideration of the impact on compile time.

Change Detection

When rebuilding a package, Cargo does not necessarily know if the build script needs to be run again. By default, it takes a conservative approach of always re-running the build script if any file within the package is changed (or the list of files controlled by the exclude and include fields). For most cases, this is not a good choice, so it is recommended that every build script emit at least one of the rerun-if instructions (described below). If these are emitted, then Cargo will only re-run the script if the given value has changed. If Cargo is re-running the build scripts of your own crate or a dependency and you don’t know why, see “Why is Cargo rebuilding my code?” in the FAQ.

cargo::rerun-if-changed=PATH

The rerun-if-changed instruction tells Cargo to re-run the build script if the file at the given path has changed. Currently, Cargo only uses the filesystem last-modified “mtime” timestamp to determine if the file has changed. It compares against an internal cached timestamp of when the build script last ran.

If the path points to a directory, it will scan the entire directory for any modifications.

If the build script inherently does not need to re-run under any circumstance, then emitting cargo::rerun-if-changed=build.rs is a simple way to prevent it from being re-run (otherwise, the default if no rerun-if instructions are emitted is to scan the entire package directory for changes). Cargo automatically handles whether or not the script itself needs to be recompiled, and of course the script will be re-run after it has been recompiled. Otherwise, specifying build.rs is redundant and unnecessary.

cargo::rerun-if-env-changed=NAME

The rerun-if-env-changed instruction tells Cargo to re-run the build script if the value of an environment variable of the given name has changed.

Note that the environment variables here are intended for global environment variables like CC and such, it is not possible to use this for environment variables like TARGET that Cargo sets for build scripts. The environment variables in use are those received by cargo invocations, not those received by the executable of the build script.

The links Manifest Key

The package.links key may be set in the Cargo.toml manifest to declare that the package links with the given native library. The purpose of this manifest key is to give Cargo an understanding about the set of native dependencies that a package has, as well as providing a principled system of passing metadata between package build scripts.

[package]
# ...
links = "foo"

This manifest states that the package links to the libfoo native library. When using the links key, the package must have a build script, and the build script should use the rustc-link-lib instruction to link the library.

Primarily, Cargo requires that there is at most one package per links value. In other words, it is forbidden to have two packages link to the same native library. This helps prevent duplicate symbols between crates. Note, however, that there are conventions in place to alleviate this.

Build scripts can generate an arbitrary set of metadata in the form of key-value pairs. This metadata is set with the cargo::metadata=KEY=VALUE instruction.

The metadata is passed to the build scripts of dependent packages. For example, if the package bar depends on foo, then if foo generates key=value as part of its build script metadata, then the build script of bar will have the environment variables DEP_FOO_KEY=value. See the “Using another sys crate” for an example of how this can be used.

Note that metadata is only passed to immediate dependents, not transitive dependents.

MSRV: 1.77 is required for cargo::metadata=KEY=VALUE. To support older versions, use cargo:KEY=VAUE (unsupported directives are assumed to be metadata keys).

*-sys Packages

Some Cargo packages that link to system libraries have a naming convention of having a -sys suffix. Any package named foo-sys should provide two major pieces of functionality:

• The library crate should link to the native library libfoo. This will often probe the current system for libfoo before resorting to building from source.
• The library crate should provide declarations for types and functions in libfoo, but not higher-level abstractions.

The set of *-sys packages provides a common set of dependencies for linking to native libraries. There are a number of benefits earned from having this convention of native-library-related packages:

• Common dependencies on foo-sys alleviates the rule about one package per value of links.
• Other -sys packages can take advantage of the DEP_NAME_KEY=value environment variables to better integrate with other packages. See the “Using another sys crate” example.
• A common dependency allows centralizing logic on discovering libfoo itself (or building it from source).
• These dependencies are easily overridable.

It is common to have a companion package without the -sys suffix that provides a safe, high-level abstractions on top of the sys package. For example, the git2 crate provides a high-level interface to the libgit2-sys crate.

Overriding Build Scripts

If a manifest contains a links key, then Cargo supports overriding the build script specified with a custom library. The purpose of this functionality is to prevent running the build script in question altogether and instead supply the metadata ahead of time.

To override a build script, place the following configuration in any acceptable config.toml file.

[target.x86_64-unknown-linux-gnu.foo]
rustc-link-lib = ["foo"]
rustc-link-search = ["/path/to/foo"]
rustc-flags = "-L /some/path"
rustc-cfg = ['key="value"']
rustc-env = {key = "value"}
rustc-cdylib-link-arg = ["…"]
metadata_key1 = "value"
metadata_key2 = "value"

With this configuration, if a package declares that it links to foo then the build script will not be compiled or run, and the metadata specified will be used instead.

The warning, rerun-if-changed, and rerun-if-env-changed keys should not be used and will be ignored.

Jobserver

Cargo and rustc use the jobserver protocol, developed for GNU make, to coordinate concurrency across processes. It is essentially a semaphore that controls the number of jobs running concurrently. The concurrency may be set with the --jobs flag, which defaults to the number of logical CPUs.

Each build script inherits one job slot from Cargo, and should endeavor to only use one CPU while it runs. If the script wants to use more CPUs in parallel, it should use the jobserver crate to coordinate with Cargo.

As an example, the cc crate may enable the optional parallel feature which will use the jobserver protocol to attempt to build multiple C files at the same time.

Build Script Examples

The following sections illustrate some examples of writing build scripts.

Some common build script functionality can be found via crates on crates.io. Check out the build-dependencies keyword to see what is available. The following is a sample of some popular crates¹:

• bindgen — Automatically generate Rust FFI bindings to C libraries.
• cc — Compiles C/C++/assembly.
• pkg-config — Detect system libraries using the pkg-config utility.
• cmake — Runs the cmake build tool to build a native library.
• autocfg, rustc_version, version_check — These crates provide ways to implement conditional compilation based on the current rustc such as the version of the compiler.

Code generation

Some Cargo packages need to have code generated just before they are compiled for various reasons. Here we’ll walk through a simple example which generates a library call as part of the build script.

First, let’s take a look at the directory structure of this package:

.
├── Cargo.toml
├── build.rs
└── src
    └── main.rs

1 directory, 3 files

Here we can see that we have a build.rs build script and our binary in main.rs. This package has a basic manifest:

# Cargo.toml

[package]
name = "hello-from-generated-code"
version = "0.1.0"
edition = "2021"

Let’s see what’s inside the build script:

// build.rs

use std::env;
use std::fs;
use std::path::Path;

fn main() {
    let out_dir = env::var_os("OUT_DIR").unwrap();
    let dest_path = Path::new(&out_dir).join("hello.rs");
    fs::write(
        &dest_path,
        "pub fn message() -> &'static str {
            \"Hello, World!\"
        }
        "
    ).unwrap();
    println!("cargo::rerun-if-changed=build.rs");
}

There’s a couple of points of note here:

• The script uses the OUT_DIR environment variable to discover where the output files should be located. It can use the process’ current working directory to find where the input files should be located, but in this case we don’t have any input files.
• In general, build scripts should not modify any files outside of OUT_DIR. It may seem fine on the first blush, but it does cause problems when you use such crate as a dependency, because there’s an implicit invariant that sources in .cargo/registry should be immutable. cargo won’t allow such scripts when packaging.
• This script is relatively simple as it just writes out a small generated file. One could imagine that other more complex operations could take place such as generating a Rust module from a C header file or another language definition, for example.
• The rerun-if-changed instruction tells Cargo that the build script only needs to re-run if the build script itself changes. Without this line, Cargo will automatically run the build script if any file in the package changes. If your code generation uses some input files, this is where you would print a list of each of those files.

Next, let’s peek at the library itself:

// src/main.rs

include!(concat!(env!("OUT_DIR"), "/hello.rs"));

fn main() {
    println!("{}", message());
}

This is where the real magic happens. The library is using the rustc-defined include! macro in combination with the concat! and env! macros to include the generated file (hello.rs) into the crate’s compilation.

Using the structure shown here, crates can include any number of generated files from the build script itself.

Building a native library

Sometimes it’s necessary to build some native C or C++ code as part of a package. This is another excellent use case of leveraging the build script to build a native library before the Rust crate itself. As an example, we’ll create a Rust library which calls into C to print “Hello, World!”.

Like above, let’s first take a look at the package layout:

.
├── Cargo.toml
├── build.rs
└── src
    ├── hello.c
    └── main.rs

1 directory, 4 files

Pretty similar to before! Next, the manifest:

# Cargo.toml

[package]
name = "hello-world-from-c"
version = "0.1.0"
edition = "2021"

For now we’re not going to use any build dependencies, so let’s take a look at the build script now:

// build.rs

use std::process::Command;
use std::env;
use std::path::Path;

fn main() {
    let out_dir = env::var("OUT_DIR").unwrap();

    // Note that there are a number of downsides to this approach, the comments
    // below detail how to improve the portability of these commands.
    Command::new("gcc").args(&["src/hello.c", "-c", "-fPIC", "-o"])
                       .arg(&format!("{}/hello.o", out_dir))
                       .status().unwrap();
    Command::new("ar").args(&["crus", "libhello.a", "hello.o"])
                      .current_dir(&Path::new(&out_dir))
                      .status().unwrap();

    println!("cargo::rustc-link-search=native={}", out_dir);
    println!("cargo::rustc-link-lib=static=hello");
    println!("cargo::rerun-if-changed=src/hello.c");
}

This build script starts out by compiling our C file into an object file (by invoking gcc) and then converting this object file into a static library (by invoking ar). The final step is feedback to Cargo itself to say that our output was in out_dir and the compiler should link the crate to libhello.a statically via the -l static=hello flag.

Note that there are a number of drawbacks to this hard-coded approach:

• The gcc command itself is not portable across platforms. For example it’s unlikely that Windows platforms have gcc, and not even all Unix platforms may have gcc. The ar command is also in a similar situation.
• These commands do not take cross-compilation into account. If we’re cross compiling for a platform such as Android it’s unlikely that gcc will produce an ARM executable.

Not to fear, though, this is where a build-dependencies entry would help! The Cargo ecosystem has a number of packages to make this sort of task much easier, portable, and standardized. Let’s try the cc crate from crates.io. First, add it to the build-dependencies in Cargo.toml:

[build-dependencies]
cc = "1.0"

And rewrite the build script to use this crate:

// build.rs

fn main() {
    cc::Build::new()
        .file("src/hello.c")
        .compile("hello");
    println!("cargo::rerun-if-changed=src/hello.c");
}

The cc crate abstracts a range of build script requirements for C code:

• It invokes the appropriate compiler (MSVC for windows, gcc for MinGW, cc for Unix platforms, etc.).
• It takes the TARGET variable into account by passing appropriate flags to the compiler being used.
• Other environment variables, such as OPT_LEVEL, DEBUG, etc., are all handled automatically.
• The stdout output and OUT_DIR locations are also handled by the cc library.

Here we can start to see some of the major benefits of farming as much functionality as possible out to common build dependencies rather than duplicating logic across all build scripts!

Back to the case study though, let’s take a quick look at the contents of the src directory:

// src/hello.c

#include <stdio.h>

void hello() {
    printf("Hello, World!\n");
}

// src/main.rs

// Note the lack of the `#[link]` attribute. We’re delegating the responsibility
// of selecting what to link over to the build script rather than hard-coding
// it in the source file.
extern { fn hello(); }

fn main() {
    unsafe { hello(); }
}

And there we go! This should complete our example of building some C code from a Cargo package using the build script itself. This also shows why using a build dependency can be crucial in many situations and even much more concise!

We’ve also seen a brief example of how a build script can use a crate as a dependency purely for the build process and not for the crate itself at runtime.

Linking to system libraries

This example demonstrates how to link a system library and how the build script is used to support this use case.

Quite frequently a Rust crate wants to link to a native library provided on the system to bind its functionality or just use it as part of an implementation detail. This is quite a nuanced problem when it comes to performing this in a platform-agnostic fashion. It is best, if possible, to farm out as much of this as possible to make this as easy as possible for consumers.

For this example, we will be creating a binding to the system’s zlib library. This is a library that is commonly found on most Unix-like systems that provides data compression. This is already wrapped up in the libz-sys crate, but for this example, we’ll do an extremely simplified version. Check out the source code for the full example.

To make it easy to find the location of the library, we will use the pkg-config crate. This crate uses the system’s pkg-config utility to discover information about a library. It will automatically tell Cargo what is needed to link the library. This will likely only work on Unix-like systems with pkg-config installed. Let’s start by setting up the manifest:

# Cargo.toml

[package]
name = "libz-sys"
version = "0.1.0"
edition = "2021"
links = "z"

[build-dependencies]
pkg-config = "0.3.16"

Take note that we included the links key in the package table. This tells Cargo that we are linking to the libz library. See “Using another sys crate” for an example that will leverage this.

The build script is fairly simple:

// build.rs

fn main() {
    pkg_config::Config::new().probe("zlib").unwrap();
    println!("cargo::rerun-if-changed=build.rs");
}

Let’s round out the example with a basic FFI binding:

// src/lib.rs

use std::os::raw::{c_uint, c_ulong};

extern "C" {
    pub fn crc32(crc: c_ulong, buf: *const u8, len: c_uint) -> c_ulong;
}

#[test]
fn test_crc32() {
    let s = "hello";
    unsafe {
        assert_eq!(crc32(0, s.as_ptr(), s.len() as c_uint), 0x3610a686);
    }
}

Run cargo build -vv to see the output from the build script. On a system with libz already installed, it may look something like this:

[libz-sys 0.1.0] cargo::rustc-link-search=native=/usr/lib
[libz-sys 0.1.0] cargo::rustc-link-lib=z
[libz-sys 0.1.0] cargo::rerun-if-changed=build.rs

Nice! pkg-config did all the work of finding the library and telling Cargo where it is.

It is not unusual for packages to include the source for the library, and build it statically if it is not found on the system, or if a feature or environment variable is set. For example, the real libz-sys crate checks the environment variable LIBZ_SYS_STATIC or the static feature to build it from source instead of using the system library. Check out the source for a more complete example.

Using another sys crate

When using the links key, crates may set metadata that can be read by other crates that depend on it. This provides a mechanism to communicate information between crates. In this example, we’ll be creating a C library that makes use of zlib from the real libz-sys crate.

If you have a C library that depends on zlib, you can leverage the libz-sys crate to automatically find it or build it. This is great for cross-platform support, such as Windows where zlib is not usually installed. libz-sys sets the include metadata to tell other packages where to find the header files for zlib. Our build script can read that metadata with the DEP_Z_INCLUDE environment variable. Here’s an example:

# Cargo.toml

[package]
name = "zuser"
version = "0.1.0"
edition = "2021"

[dependencies]
libz-sys = "1.0.25"

[build-dependencies]
cc = "1.0.46"

Here we have included libz-sys which will ensure that there is only one libz used in the final library, and give us access to it from our build script:

// build.rs

fn main() {
    let mut cfg = cc::Build::new();
    cfg.file("src/zuser.c");
    if let Some(include) = std::env::var_os("DEP_Z_INCLUDE") {
        cfg.include(include);
    }
    cfg.compile("zuser");
    println!("cargo::rerun-if-changed=src/zuser.c");
}

With libz-sys doing all the heavy lifting, the C source code may now include the zlib header, and it should find the header, even on systems where it isn’t already installed.

// src/zuser.c

#include "zlib.h"

// … rest of code that makes use of zlib.

Conditional compilation

A build script may emit rustc-cfg instructions which can enable conditions that can be checked at compile time. In this example, we’ll take a look at how the openssl crate uses this to support multiple versions of the OpenSSL library.

The openssl-sys crate implements building and linking the OpenSSL library. It supports multiple different implementations (like LibreSSL) and multiple versions. It makes use of the links key so that it may pass information to other build scripts. One of the things it passes is the version_number key, which is the version of OpenSSL that was detected. The code in the build script looks something like this:

println!("cargo::metadata=version_number={openssl_version:x}");

This instruction causes the DEP_OPENSSL_VERSION_NUMBER environment variable to be set in any crates that directly depend on openssl-sys.

The openssl crate, which provides the higher-level interface, specifies openssl-sys as a dependency. The openssl build script can read the version information generated by the openssl-sys build script with the DEP_OPENSSL_VERSION_NUMBER environment variable. It uses this to generate some cfg values:

// (portion of build.rs)

println!("cargo::rustc-check-cfg=cfg(ossl101,ossl102)");
println!("cargo::rustc-check-cfg=cfg(ossl110,ossl110g,ossl111)");

if let Ok(version) = env::var("DEP_OPENSSL_VERSION_NUMBER") {
    let version = u64::from_str_radix(&version, 16).unwrap();

    if version >= 0x1_00_01_00_0 {
        println!("cargo::rustc-cfg=ossl101");
    }
    if version >= 0x1_00_02_00_0 {
        println!("cargo::rustc-cfg=ossl102");
    }
    if version >= 0x1_01_00_00_0 {
        println!("cargo::rustc-cfg=ossl110");
    }
    if version >= 0x1_01_00_07_0 {
        println!("cargo::rustc-cfg=ossl110g");
    }
    if version >= 0x1_01_01_00_0 {
        println!("cargo::rustc-cfg=ossl111");
    }
}

These cfg values can then be used with the cfg attribute or the cfg macro to conditionally include code. For example, SHA3 support was added in OpenSSL 1.1.1, so it is conditionally excluded for older versions:

// (portion of openssl crate)

#[cfg(ossl111)]
pub fn sha3_224() -> MessageDigest {
    unsafe { MessageDigest(ffi::EVP_sha3_224()) }
}

Of course, one should be careful when using this, since it makes the resulting binary even more dependent on the build environment. In this example, if the binary is distributed to another system, it may not have the exact same shared libraries, which could cause problems.

Build cache

Cargo stores the output of a build into the “target” directory. By default, this is the directory named target in the root of your workspace. To change the location, you can set the CARGO_TARGET_DIR environment variable, the build.target-dir config value, or the --target-dir command-line flag.

The directory layout depends on whether or not you are using the --target flag to build for a specific platform. If --target is not specified, Cargo runs in a mode where it builds for the host architecture. The output goes into the root of the target directory, with each profile stored in a separate subdirectory:

For historical reasons, the dev and test profiles are stored in the debug directory, and the release and bench profiles are stored in the release directory. User-defined profiles are stored in a directory with the same name as the profile.

When building for another target with --target, the output is placed in a directory with the name of the target:

Note: When not using --target, this has a consequence that Cargo will share your dependencies with build scripts and proc macros. RUSTFLAGS will be shared with every rustc invocation. With the --target flag, build scripts and proc macros are built separately (for the host architecture), and do not share RUSTFLAGS.

Within the profile directory (such as debug or release), artifacts are placed into the following directories:

Some commands place their output in dedicated directories in the top level of the target directory:

Cargo also creates several other directories and files needed for the build process. Their layout is considered internal to Cargo, and is subject to change. Some of these directories are:

Dep-info files

Next to each compiled artifact is a file called a “dep info” file with a .d suffix. This file is a Makefile-like syntax that indicates all of the file dependencies required to rebuild the artifact. These are intended to be used with external build systems so that they can detect if Cargo needs to be re-executed. The paths in the file are absolute by default. See the build.dep-info-basedir config option to use relative paths.

# Example dep-info file found in target/debug/foo.d
/path/to/myproj/target/debug/foo: /path/to/myproj/src/lib.rs /path/to/myproj/src/main.rs

Shared cache

A third party tool, sccache, can be used to share built dependencies across different workspaces.

To setup sccache, install it with cargo install sccache and set RUSTC_WRAPPER environmental variable to sccache before invoking Cargo. If you use bash, it makes sense to add export RUSTC_WRAPPER=sccache to .bashrc. Alternatively, you can set build.rustc-wrapper in the Cargo configuration. Refer to sccache documentation for more details.

Package ID Specifications

Package ID specifications

Subcommands of Cargo frequently need to refer to a particular package within a dependency graph for various operations like updating, cleaning, building, etc. To solve this problem, Cargo supports Package ID Specifications. A specification is a string which is used to uniquely refer to one package within a graph of packages.

The specification may be fully qualified, such as https://github.com/rust-lang/crates.io-index#regex@1.4.3 or it may be abbreviated, such as regex. The abbreviated form may be used as long as it uniquely identifies a single package in the dependency graph. If there is ambiguity, additional qualifiers can be added to make it unique. For example, if there are two versions of the regex package in the graph, then it can be qualified with a version to make it unique, such as regex@1.4.3.

Specification grammar

The formal grammar for a Package Id Specification is:

spec := pkgname |
        [ kind "+" ] proto "://" hostname-and-path [ "?" query] [ "#" ( pkgname | semver ) ]
query = ( "branch" | "tag" | "rev" ) "=" ref
pkgname := name [ ("@" | ":" ) semver ]
semver := digits [ "." digits [ "." digits [ "-" prerelease ] [ "+" build ]]]

kind = "registry" | "git" | "file"
proto := "http" | "git" | ...

Here, brackets indicate that the contents are optional.

The URL form can be used for git dependencies, or to differentiate packages that come from different sources such as different registries.

Example specifications

The following are references to the regex package on crates.io:

The following are some examples of specs for several different git dependencies:

Local packages on the filesystem can use file:// URLs to reference them:

Brevity of specifications

The goal of this is to enable both succinct and exhaustive syntaxes for referring to packages in a dependency graph. Ambiguous references may refer to one or more packages. Most commands generate an error if more than one package could be referred to with the same specification.

External tools

One of the goals of Cargo is simple integration with third-party tools, like IDEs and other build systems. To make integration easier, Cargo has several facilities:

• a cargo metadata command, which outputs package structure and dependencies information in JSON,

• a --message-format flag, which outputs information about a particular build, and

• support for custom subcommands.

Information about package structure

You can use cargo metadata command to get information about package structure and dependencies. See the cargo metadata documentation for details on the format of the output.

The format is stable and versioned. When calling cargo metadata, you should pass --format-version flag explicitly to avoid forward incompatibility hazard.

If you are using Rust, the cargo_metadata crate can be used to parse the output.

JSON messages

When passing --message-format=json, Cargo will output the following information during the build:

• compiler errors and warnings,

• produced artifacts,

• results of the build scripts (for example, native dependencies).

The output goes to stdout in the JSON object per line format. The reason field distinguishes different kinds of messages. The package_id field is a unique identifier for referring to the package, and as the --package argument to many commands. The syntax grammar can be found in chapter Package ID Specifications.

Note: --message-format=json only controls Cargo and Rustc’s output. This cannot control the output of other tools, e.g. cargo run --message-format=json, or arbitrary output from procedural macros. A possible workaround in these situations is to only interpret a line as JSON if it starts with {.

The --message-format option can also take additional formatting values which alter the way the JSON messages are computed and rendered. See the description of the --message-format option in the build command documentation for more details.

If you are using Rust, the cargo_metadata crate can be used to parse these messages.

MSRV: 1.77 is required for package_id to be a Package ID Specification. Before that, it was opaque.

Compiler messages

The “compiler-message” message includes output from the compiler, such as warnings and errors. See the rustc JSON chapter for details on rustc’s message format, which is embedded in the following structure:

{
    /* The "reason" indicates the kind of message. */
    "reason": "compiler-message",
    /* The Package ID, a unique identifier for referring to the package. */
    "package_id": "file:///path/to/my-package#0.1.0",
    /* Absolute path to the package manifest. */
    "manifest_path": "/path/to/my-package/Cargo.toml",
    /* The Cargo target (lib, bin, example, etc.) that generated the message. */
    "target": {
        /* Array of target kinds.
           - lib targets list the `crate-type` values from the
             manifest such as "lib", "rlib", "dylib",
             "proc-macro", etc. (default ["lib"])
           - binary is ["bin"]
           - example is ["example"]
           - integration test is ["test"]
           - benchmark is ["bench"]
           - build script is ["custom-build"]
        */
        "kind": [
            "lib"
        ],
        /* Array of crate types.
           - lib and example libraries list the `crate-type` values
             from the manifest such as "lib", "rlib", "dylib",
             "proc-macro", etc. (default ["lib"])
           - all other target kinds are ["bin"]
        */
        "crate_types": [
            "lib"
        ],
        /* The name of the target.
           For lib targets, dashes will be replaced with underscores.
        */
        "name": "my_package",
        /* Absolute path to the root source file of the target. */
        "src_path": "/path/to/my-package/src/lib.rs",
        /* The Rust edition of the target.
           Defaults to the package edition.
        */
        "edition": "2018",
        /* Array of required features.
           This property is not included if no required features are set.
        */
        "required-features": ["feat1"],
        /* Whether the target should be documented by `cargo doc`. */
        "doc": true,
        /* Whether or not this target has doc tests enabled, and
           the target is compatible with doc testing.
        */
        "doctest": true
        /* Whether or not this target should be built and run with `--test`
        */
        "test": true
    },
    /* The message emitted by the compiler.

    See https://doc.rust-lang.org/rustc/json.html for details.
    */
    "message": {
        /* ... */
    }
}

Artifact messages

For every compilation step, a “compiler-artifact” message is emitted with the following structure:

{
    /* The "reason" indicates the kind of message. */
    "reason": "compiler-artifact",
    /* The Package ID, a unique identifier for referring to the package. */
    "package_id": "file:///path/to/my-package#0.1.0",
    /* Absolute path to the package manifest. */
    "manifest_path": "/path/to/my-package/Cargo.toml",
    /* The Cargo target (lib, bin, example, etc.) that generated the artifacts.
       See the definition above for `compiler-message` for details.
    */
    "target": {
        "kind": [
            "lib"
        ],
        "crate_types": [
            "lib"
        ],
        "name": "my_package",
        "src_path": "/path/to/my-package/src/lib.rs",
        "edition": "2018",
        "doc": true,
        "doctest": true,
        "test": true
    },
    /* The profile indicates which compiler settings were used. */
    "profile": {
        /* The optimization level. */
        "opt_level": "0",
        /* The debug level, an integer of 0, 1, or 2, or a string
           "line-directives-only" or "line-tables-only". If `null`, it implies
           rustc's default of 0.
        */
        "debuginfo": 2,
        /* Whether or not debug assertions are enabled. */
        "debug_assertions": true,
        /* Whether or not overflow checks are enabled. */
        "overflow_checks": true,
        /* Whether or not the `--test` flag is used. */
        "test": false
    },
    /* Array of features enabled. */
    "features": ["feat1", "feat2"],
    /* Array of files generated by this step. */
    "filenames": [
        "/path/to/my-package/target/debug/libmy_package.rlib",
        "/path/to/my-package/target/debug/deps/libmy_package-be9f3faac0a26ef0.rmeta"
    ],
    /* A string of the path to the executable that was created, or null if
       this step did not generate an executable.
    */
    "executable": null,
    /* Whether or not this step was actually executed.
       When `true`, this means that the pre-existing artifacts were
       up-to-date, and `rustc` was not executed. When `false`, this means that
       `rustc` was run to generate the artifacts.
    */
    "fresh": true
}

Build script output

The “build-script-executed” message includes the parsed output of a build script. Note that this is emitted even if the build script is not run; it will display the previously cached value. More details about build script output may be found in the chapter on build scripts.

{
    /* The "reason" indicates the kind of message. */
    "reason": "build-script-executed",
    /* The Package ID, a unique identifier for referring to the package. */
    "package_id": "file:///path/to/my-package#0.1.0",
    /* Array of libraries to link, as indicated by the `cargo::rustc-link-lib`
       instruction. Note that this may include a "KIND=" prefix in the string
       where KIND is the library kind.
    */
    "linked_libs": ["foo", "static=bar"],
    /* Array of paths to include in the library search path, as indicated by
       the `cargo::rustc-link-search` instruction. Note that this may include a
       "KIND=" prefix in the string where KIND is the library kind.
    */
    "linked_paths": ["/some/path", "native=/another/path"],
    /* Array of cfg values to enable, as indicated by the `cargo::rustc-cfg`
       instruction.
    */
    "cfgs": ["cfg1", "cfg2=\"string\""],
    /* Array of [KEY, VALUE] arrays of environment variables to set, as
       indicated by the `cargo::rustc-env` instruction.
    */
    "env": [
        ["SOME_KEY", "some value"],
        ["ANOTHER_KEY", "another value"]
    ],
    /* An absolute path which is used as a value of `OUT_DIR` environmental
       variable when compiling current package.
    */
    "out_dir": "/some/path/in/target/dir"
}

Build finished

The “build-finished” message is emitted at the end of the build.

{
    /* The "reason" indicates the kind of message. */
    "reason": "build-finished",
    /* Whether or not the build finished successfully. */
    "success": true,
}

This message can be helpful for tools to know when to stop reading JSON messages. Commands such as cargo test or cargo run can produce additional output after the build has finished. This message lets a tool know that Cargo will not produce additional JSON messages, but there may be additional output that may be generated afterwards (such as the output generated by the program executed by cargo run).

Note: There is experimental nightly-only support for JSON output for tests, so additional test-specific JSON messages may begin arriving after the “build-finished” message if that is enabled.

Custom subcommands

Cargo is designed to be extensible with new subcommands without having to modify Cargo itself. This is achieved by translating a cargo invocation of the form cargo (?<command>[^ ]+) into an invocation of an external tool cargo-${command}. The external tool must be present in one of the user’s $PATH directories.

Note: Cargo defaults to prioritizing external tools in $CARGO_HOME/bin over $PATH. Users can override this precedence by adding $CARGO_HOME/bin to $PATH.

When Cargo invokes a custom subcommand, the first argument to the subcommand will be the filename of the custom subcommand, as usual. The second argument will be the subcommand name itself. For example, the second argument would be ${command} when invoking cargo-${command}. Any additional arguments on the command line will be forwarded unchanged.

Cargo can also display the help output of a custom subcommand with cargo help ${command}. Cargo assumes that the subcommand will print a help message if its third argument is --help. So, cargo help ${command} would invoke cargo-${command} ${command} --help.

Custom subcommands may use the CARGO environment variable to call back to Cargo. Alternatively, it can link to cargo crate as a library, but this approach has drawbacks:

• Cargo as a library is unstable: the API may change without deprecation
• versions of the linked Cargo library may be different from the Cargo binary

Instead, it is encouraged to use the CLI interface to drive Cargo. The cargo metadata command can be used to obtain information about the current project (the cargo_metadata crate provides a Rust interface to this command).

Registries

Cargo installs crates and fetches dependencies from a “registry”. The default registry is crates.io. A registry contains an “index” which contains a searchable list of available crates. A registry may also provide a web API to support publishing new crates directly from Cargo.

Note: If you are interested in mirroring or vendoring an existing registry, take a look at Source Replacement.

If you are implementing a registry server, see Running a Registry for more details about the protocol between Cargo and a registry.

If you’re using a registry that requires authentication, see Registry Authentication. If you are implementing a credential provider, see Credential Provider Protocol for details.

Using an Alternate Registry

To use a registry other than crates.io, the name and index URL of the registry must be added to a .cargo/config.toml file. The registries table has a key for each registry, for example:

[registries]
my-registry = { index = "https://my-intranet:8080/git/index" }

The index key should be a URL to a git repository with the registry’s index or a Cargo sparse registry URL with the sparse+ prefix.

A crate can then depend on a crate from another registry by specifying the registry key and a value of the registry’s name in that dependency’s entry in Cargo.toml:

# Sample Cargo.toml
[package]
name = "my-project"
version = "0.1.0"
edition = "2021"

[dependencies]
other-crate = { version = "1.0", registry = "my-registry" }

As with most config values, the index may be specified with an environment variable instead of a config file. For example, setting the following environment variable will accomplish the same thing as defining a config file:

CARGO_REGISTRIES_MY_REGISTRY_INDEX=https://my-intranet:8080/git/index

Note: crates.io does not accept packages that depend on crates from other registries.

Publishing to an Alternate Registry

If the registry supports web API access, then packages can be published directly to the registry from Cargo. Several of Cargo’s commands such as cargo publish take a --registry command-line flag to indicate which registry to use. For example, to publish the package in the current directory:

1. cargo login --registry=my-registry

   This only needs to be done once. You must enter the secret API token retrieved from the registry’s website. Alternatively the token may be passed directly to the publish command with the --token command-line flag or an environment variable with the name of the registry such as CARGO_REGISTRIES_MY_REGISTRY_TOKEN.

2. cargo publish --registry=my-registry

Instead of always passing the --registry command-line option, the default registry may be set in .cargo/config.toml with the registry.default key. For example:

[registry]
default = "my-registry"

Setting the package.publish key in the Cargo.toml manifest restricts which registries the package is allowed to be published to. This is useful to prevent accidentally publishing a closed-source package to crates.io. The value may be a list of registry names, for example:

[package]
# ...
publish = ["my-registry"]

The publish value may also be false to restrict all publishing, which is the same as an empty list.

The authentication information saved by cargo login is stored in the credentials.toml file in the Cargo home directory (default $HOME/.cargo). It has a separate table for each registry, for example:

[registries.my-registry]
token = "854DvwSlUwEHtIo3kWy6x7UCPKHfzCmy"

Registry Protocols

Cargo supports two remote registry protocols: git and sparse. If the registry index URL starts with sparse+, Cargo uses the sparse protocol. Otherwise Cargo uses the git protocol.

The git protocol stores index metadata in a git repository and requires Cargo to clone the entire repo.

The sparse protocol fetches individual metadata files using plain HTTP requests. Since Cargo only downloads the metadata for relevant crates, the sparse protocol can save significant time and bandwidth.

The crates.io registry supports both protocols. The protocol for crates.io is controlled via the registries.crates-io.protocol config key.

Registry Authentication

Cargo authenticates to registries with credential providers. These credential providers are external executables or built-in providers that Cargo uses to store and retrieve credentials.

Using alternative registries with authentication requires a credential provider to be configured to avoid unknowingly storing unencrypted credentials on disk. For historical reasons, public (non-authenticated) registries do not require credential provider configuration, and the cargo:token provider is used if no providers are configured.

Cargo also includes platform-specific providers that use the operating system to securely store tokens. The cargo:token provider is also included which stores credentials in unencrypted plain text in the credentials file.

Recommended configuration

It’s recommended to configure a global credential provider list in $CARGO_HOME/config.toml which defaults to:

• Windows: %USERPROFILE%\.cargo\config.toml
• Unix: ~/.cargo/config.toml

This recommended configuration uses the operating system provider, with a fallback to cargo:token to look in Cargo’s credentials file or environment variables:

# ~/.cargo/config.toml
[registry]
global-credential-providers = ["cargo:token", "cargo:libsecret", "cargo:macos-keychain", "cargo:wincred"]

Note that later entries have higher precedence. See registry.global-credential-providers for more details.

Some private registries may also recommend a registry-specific credential-provider. Check your registry’s documentation to see if this is the case.

Built-in providers

Cargo includes several built-in credential providers. The available built-in providers may change in future Cargo releases (though there are currently no plans to do so).

cargo:token

Uses Cargo’s credentials file to store tokens unencrypted in plain text. When retrieving tokens, checks the CARGO_REGISTRIES_<NAME>_TOKEN environment variable. If this credential provider is not listed, then the *_TOKEN environment variables will not work.

cargo:wincred

Uses the Windows Credential Manager to store tokens.

The credentials are stored as cargo-registry:<index-url> in the Credential Manager under “Windows Credentials”.

cargo:macos-keychain

Uses the macOS Keychain to store tokens.

The Keychain Access app can be used to view stored tokens.

cargo:libsecret

Uses libsecret to store tokens.

Any password manager with libsecret support can be used to view stored tokens. The following are a few examples (non-exhaustive):

• GNOME Keyring
• KDE Wallet Manager (since KDE Frameworks 5.97.0)
• KeePassXC (since 2.5.0)

cargo:token-from-stdout <command> <args>

Launch a subprocess that returns a token on stdout. Newlines will be trimmed.

• The process inherits the user’s stdin and stderr.
• It should exit 0 on success, and nonzero on error.
• cargo login and cargo logout are not supported and return an error if used.

The following environment variables will be provided to the executed command:

• CARGO — Path to the cargo binary executing the command.
• CARGO_REGISTRY_INDEX_URL — The URL of the registry index.
• CARGO_REGISTRY_NAME_OPT — Optional name of the registry. Should not be used as a lookup key.

Arguments will be passed on to the subcommand.

Credential plugins

For credential provider plugins that follow Cargo’s credential provider protocol, the configuration value should be a string with the path to the executable (or the executable name if on the PATH).

For example, to install cargo-credential-1password from crates.io do the following:

Install the provider with cargo install cargo-credential-1password

In the config, add to (or create) registry.global-credential-providers:

[registry]
global-credential-providers = ["cargo:token", "cargo-credential-1password --account my.1password.com"]

The values in global-credential-providers are split on spaces into path and command-line arguments. To define a global credential provider where the path or arguments contain spaces, use the [credential-alias] table.

Credential Provider Protocol

This document describes information for building a Cargo credential provider. For information on setting up or using a credential provider, see Registry Authentication.

When using an external credential provider, Cargo communicates with the credential provider using stdin/stdout messages passed as single lines of JSON.

Cargo will always execute the credential provider with the --cargo-plugin argument. This enables a credential provider executable to have additional functionality beyond what Cargo needs. Additional arguments are included in the JSON via the args field.

JSON messages

The JSON messages in this document have newlines added for readability. Actual messages must not contain newlines.

Credential hello

• Sent by: credential provider
• Purpose: used to identify the supported protocols on process startup

{
    "v":[1]
}

Requests sent by Cargo will include a v field set to one of the versions listed here. If Cargo does not support any of the versions offered by the credential provider, it will issue an error and shut down the credential process.

Registry information

• Sent by: Cargo Not a message by itself. Included in all messages sent by Cargo as the registry field.

{
    // Index URL of the registry
    "index-url":"https://github.com/rust-lang/crates.io-index",
    // Name of the registry in configuration (optional)
    "name": "crates-io",
    // HTTP headers received from attempting to access an authenticated registry (optional)
    "headers": ["WWW-Authenticate: cargo"]
}

Login request

• Sent by: Cargo
• Purpose: collect and store credentials

{
    // Protocol version
    "v":1,
    // Action to perform: login
    "kind":"login",
    // Registry information (see Registry information)
    "registry":{"index-url":"sparse+https://registry-url/index/", "name": "my-registry"},
    // User-specified token from stdin or command line (optional)
    "token": "<the token value>",
    // URL that the user could visit to get a token (optional)
    "login-url": "http://registry-url/login",
    // Additional command-line args (optional)
    "args":[]
}

If the token field is set, then the credential provider should use the token provided. If the token is not set, then the credential provider should prompt the user for a token.

In addition to the arguments that may be passed to the credential provider in configuration, cargo login also supports passing additional command line args via cargo login -- <additional args>. These additional arguments will be included in the args field after any args from Cargo configuration.

Read request

• Sent by: Cargo
• Purpose: Get the credential for reading crate information

{
    // Protocol version
    "v":1,
    // Request kind: get credentials
    "kind":"get",
    // Action to perform: read crate information
    "operation":"read",
    // Registry information (see Registry information)
    "registry":{"index-url":"sparse+https://registry-url/index/", "name": "my-registry"},
    // Additional command-line args (optional)
    "args":[]
}

Publish request

• Sent by: Cargo
• Purpose: Get the credential for publishing a crate

{
    // Protocol version
    "v":1,
    // Request kind: get credentials
    "kind":"get",
    // Action to perform: publish crate
    "operation":"publish",
    // Crate name
    "name":"sample",
    // Crate version
    "vers":"0.1.0",
    // Crate checksum
    "cksum":"...",
    // Registry information (see Registry information)
    "registry":{"index-url":"sparse+https://registry-url/index/", "name": "my-registry"},
    // Additional command-line args (optional)
    "args":[]
}

Get success response

• Sent by: credential provider
• Purpose: Gives the credential to Cargo

{"Ok":{
    // Response kind: this was a get request
    "kind":"get",
    // Token to send to the registry
    "token":"...",
    // Cache control. Can be one of the following:
    // * "never": do not cache
    // * "session": cache for the current cargo session
    // * "expires": cache for the current cargo session until expiration
    "cache":"expires",
    // Unix timestamp (only for "cache": "expires")
    "expiration":1693942857,
    // Is the token operation independent?
    "operation_independent":true
}}

The token will be sent to the registry as the value of the Authorization HTTP header.

operation_independent indicates whether the token can be cached across different operations (such as publishing or fetching). In general, this should be true unless the provider wants to generate tokens that are scoped to specific operations.

Login success response

• Sent by: credential provider
• Purpose: Indicates the login was successful

{"Ok":{
    // Response kind: this was a login request
    "kind":"login"
}}

Logout success response

• Sent by: credential provider
• Purpose: Indicates the logout was successful

{"Ok":{
    // Response kind: this was a logout request
    "kind":"logout"
}}

Failure response (URL not supported)

• Sent by: credential provider
• Purpose: Gives error information to Cargo

{"Err":{
    "kind":"url-not-supported"
}}

Sent if the credential provider is designed to only handle specific registry URLs and the given URL is not supported. Cargo will attempt another provider if available.

Failure response (not found)

• Sent by: credential provider
• Purpose: Gives error information to Cargo

{"Err":{
    // Error: The credential could not be found in the provider.
    "kind":"not-found"
}}

Sent if the credential could not be found. This is expected for get requests where the credential is not available, or logout requests where there is nothing found to erase.

Failure response (operation not supported)

• Sent by: credential provider
• Purpose: Gives error information to Cargo

{"Err":{
    // Error: The credential could not be found in the provider.
    "kind":"operation-not-supported"
}}

Sent if the credential provider does not support the requested operation. If a provider only supports get and a login is requested, the provider should respond with this error.

Failure response (other)

• Sent by: credential provider
• Purpose: Gives error information to Cargo

{"Err":{
    // Error: something else has failed
    "kind":"other",
    // Error message string to be displayed
    "message": "free form string error message",
    // Detailed cause chain for the error (optional)
    "caused-by": ["cause 1", "cause 2"]
}}

Example communication to request a token for reading:

1. Cargo spawns the credential process, capturing stdin and stdout.
2. Credential process sends the Hello message to Cargo

   { "v": [1] }
   

3. Cargo sends the CredentialRequest message to the credential process (newlines added for readability).

   {
       "v": 1,
       "kind": "get",
       "operation": "read",
       "registry":{"index-url":"sparse+https://registry-url/index/"}
   }
   

4. Credential process sends the CredentialResponse to Cargo (newlines added for readability).

   {
       "token": "...",
       "cache": "session",
       "operation_independent": true
   }
   

5. Cargo closes the stdin pipe to the credential provider and it exits.
6. Cargo uses the token for the remainder of the session (until Cargo exits) when interacting with this registry.

Running a Registry

A minimal registry can be implemented by having a git repository that contains an index, and a server that contains the compressed .crate files created by cargo package. Users won’t be able to use Cargo to publish to it, but this may be sufficient for closed environments. The index format is described in Registry Index.

A full-featured registry that supports publishing will additionally need to have a web API service that conforms to the API used by Cargo. The web API is described in Registry Web API.

Commercial and community projects are available for building and running a registry. See https://github.com/rust-lang/cargo/wiki/Third-party-registries for a list of what is available.

Index Format

The following defines the format of the index. New features are occasionally added, which are only understood starting with the version of Cargo that introduced them. Older versions of Cargo may not be able to use packages that make use of new features. However, the format for older packages should not change, so older versions of Cargo should be able to use them.

Index Configuration

The root of the index contains a file named config.json which contains JSON information used by Cargo for accessing the registry. This is an example of what the crates.io config file looks like:

{
    "dl": "https://crates.io/api/v1/crates",
    "api": "https://crates.io"
}

The keys are:

• dl: This is the URL for downloading crates listed in the index. The value may have the following markers which will be replaced with their corresponding value:

  • {crate}: The name of crate.
  • {version}: The crate version.
  • {prefix}: A directory prefix computed from the crate name. For example, a crate named cargo has a prefix of ca/rg. See below for details.
  • {lowerprefix}: Lowercase variant of {prefix}.
  • {sha256-checksum}: The crate’s sha256 checksum.

  If none of the markers are present, then the value /{crate}/{version}/download is appended to the end.

• api: This is the base URL for the web API. This key is optional, but if it is not specified, commands such as cargo publish will not work. The web API is described below.

• auth-required: indicates whether this is a private registry that requires all operations to be authenticated including API requests, crate downloads and sparse index updates.

Download Endpoint

The download endpoint should send the .crate file for the requested package. Cargo supports https, http, and file URLs, HTTP redirects, HTTP1 and HTTP2. The exact specifics of TLS support depend on the platform that Cargo is running on, the version of Cargo, and how it was compiled.

If auth-required: true is set in config.json, the Authorization header will be included with http(s) download requests.

Index files