Specifying Dependencies

Your crates can depend on other libraries from crates.io, 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 string "0.1.12" is a semver version requirement. Since this string does not have any operators in it, it is interpreted the same way as if we had specified "^0.1.12", which is called a caret requirement.

Caret requirements

Caret requirements allow SemVer compatible updates to a specified version. An update is allowed if the new version number does not modify the left-most non-zero digit in the major, minor, patch grouping. In this case, if we ran cargo update -p time, cargo would update us to version 0.1.13 if it was available, but would not update us to 0.2.0. If instead we had specified the version string as ^1.0, cargo would update to 1.1 but not 2.0. 0.0.x is not considered compatible with any other version.

Here are some more examples of caret requirements and the versions that would be allowed with them:

^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.0.3 := >=0.0.3 <0.0.4
^0.0 := >=0.0.0 <0.1.0
^0 := >=0.0.0 <1.0.0

While SemVer says that there is no compatibility before 1.0.0, many programmers treat a 0.x.y release in the same way as a 1.x.y release: that is, y is incremented for bugfixes, and x is incremented for new features. As such, Cargo considers a 0.x.y and 0.x.z version, where z > y, to be compatible.

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

Inequality requirements

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

Here are some examples of inequality requirements:

>= 1.2.0
> 1
< 2
= 1.2.3

Multiple requirements

Multiple version requirements can also be separated with a comma, e.g. >= 1.2, < 1.5.

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]
rand = { git = "https://github.com/rust-lang-nursery/rand" }

Cargo will fetch the git repository at this location then look for a Cargo.toml for the requested crate anywhere inside the git repository (not necessarily at the root).

Since we haven’t specified any other information, Cargo assumes that we intend to use the latest commit on the master branch to build our project. You can combine the git key with the rev, tag, or branch keys to specify something else. Here's an example of specifying that you want to use the latest commit on a branch named next:

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

Specifying path dependencies

Over time, our hello_world project 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 off by making a new crate inside of our hello_world project:

# 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. In order 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 it’s written in).

And that’s it! The next cargo build will automatically build hello_utils and all of its own dependencies, and others can also start using the crate as well. However, 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 (or specify a git repository location) and specify its version in the dependencies line as well:

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

Overriding dependencies

Sometimes you may want to override one of Cargo’s dependencies. For example let's say you're working on a project using the uuid crate which depends on rand. You've discovered there's a bug in rand, however, and it's already fixed upstream but hasn't been published yet. You'd like to test out the fix, so let's first take a look at what your Cargo.toml will look like:

[package]
name = "my-awesome-crate"
version = "0.2.0"
authors = ["The Rust Project Developers"]

[dependencies]
uuid = "0.2"

To override the rand dependency of uuid, we'll leverage the [replace] section of Cargo.toml by appending this to the end:

[replace]
"rand:0.3.14" = { git = 'https://github.com/rust-lang-nursery/rand' }

This indicates that the version of rand we're currently using, 0.3.14, will be replaced with the master branch of rand on GitHub. Next time when you execute cargo build Cargo will take care of checking out this repository and hooking the uuid crate up to the new version.

Note that a restriction of [replace], however, is that the replaced crate must not only have the same name but also the same version. This means that if the master branch of rand has migrated to, for example, 0.4.3, you'll need to follow a few extra steps to test out the crate:

Fork the upstream repository to your account
Create a branch which starts from the 0.3.14 release (likely tagged as 0.3.14)
Identify the fix of the bug at hand and cherry-pick it onto your branch
Update [replace] to point to your git repository and branch

This technique can also be useful when testing out new features for a dependency. Following the workflow above you can have a branch where you add features, and then once it's ready to go you can send a PR to the upstream repository. While you're waiting for the PR to get merged you can continue to work locally with a [replace], and then once the PR is merged and published you can remove [replace] and use the newly-published version.

Note: The Cargo.lock file will list two versions of the replaced crate: one for the original crate, and one for the version specified in [replace]. cargo build -v can verify that only one version is used in the build.

Overriding with local dependencies

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

Similar to before, let’s say you’re working on a project, uuid, which depends on rand. This time you're the one who finds a bug in rand, and you want to write a patch and be able to test out your patch by using your version of rand in uuid. Here’s what uuid’s Cargo.toml looks like:

[package]
name = "uuid"
version = "0.2.2"
authors = ["The Rust Project Developers"]

[dependencies]
rand = { version = "0.3", optional = true }

You check out a local copy of rand, let’s say in your ~/src directory:

$ cd ~/src
$ git clone https://github.com/rust-lang-nursery/rand

A path override is communicated to Cargo through the .cargo/config configuration mechanism. If Cargo finds this configuration when building your package, it will use the override on your local machine instead of the source specified in your Cargo.toml.

Cargo looks for a directory named .cargo up the directory hierarchy of your project. If your project is in /path/to/project/uuid, it will search for a .cargo in:

/path/to/project/uuid
/path/to/project
/path/to
/path
/

This allows you to specify your overrides in a parent directory that includes commonly used packages that you work on locally and share them with all projects.

To specify overrides, create a .cargo/config file in some ancestor of your project’s directory (common places to put it is in the root of your code directory or in your home directory).

Inside that file, put this:

paths = ["/path/to/project/rand"]

This array should be filled with directories that contain a Cargo.toml. In this instance, we’re just adding rand, so it will be the only one that’s overridden. This path must be an absolute path.

Path overrides are more restricted than the [replace] section, however, in that they cannot change the structure of the dependency graph. When a replacement is applied it must be the case that the previous set of dependencies all match exactly and can be used for the replacement. For example this means that path overrides cannot be used to test out adding a dependency to a crate, instead [replace] must be used in that situation.

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.

More information about local configuration can be found in the configuration documentation.

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 = { path = "native/i686" }

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

Like with Rust, the syntax here supports the not, any, and all operators to combine various cfg name/value pairs. Note that the cfg syntax has only been available since Cargo 0.9.0 (Rust 1.8.0).

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"

If you’re using a custom target specification, quote the full path and file name:

[target."x86_64/windows.json".dependencies]
winhttp = "0.4.0"

[target."i686/linux.json".dependencies]
openssl = "1.0.1"
native = { path = "native/i686" }

[target."x86_64/linux.json".dependencies]
openssl = "1.0.1"
native = { path = "native/x86_64" }

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"

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]
gcc = "0.3"

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 manifest documentation.

CARGO

Specifying Dependencies