cargo ships with Rust, and its crate is not meant for you

The crate carries an explicit warning against external use

There is a notice on the front page that is easy to skim past because it sits in small type above the build instructions. It draws a distinction between two things that share a name.

The Cargo binary distributed with Rust is maintained by the Cargo team for use by the wider ecosystem. That is the cargo you run every day, and it is supported.

For all other uses of the crate, as a binary or a library, the notice says it is maintained primarily for Cargo's own purposes and is not intended for external use, with the single exception of being pulled in as a transitive dependency. It closes by warning that the crate may make major changes to its APIs.

So the two are not interchangeable. Running cargo is a supported arrangement. Depending on the cargo crate in your own software is an arrangement the project declines to stand behind, with no promise of semver stability and no deprecation period promised in advance.

If you have seen tooling built on top of the Cargo library, this is the caveat that applies to it, and it is worth raising with whoever maintains that tool before you depend on it.

Build your own from the binary, or from source as described below, rather than from the crate.

A system library found by pkg-config quietly replaces the tested one

The build documentation lists four optional system libraries and explains an inversion of expectations in it.

The build will automatically use vendored versions of libcurl for network transfers, libgit2 for fetching git dependencies, libssh2 for SSH access to git repositories, and zlib, which the C libraries use for compression while the Rust code uses zlib-rs instead. Then comes the catch: if these are provided by the system and can be found with pkg-config, the system libraries are used instead.

So installing a development package for one of these changes what you build. The project then says plainly that the vendored versions are recommended, because they are the versions tested to work with Cargo.

That asymmetry is the whole risk. A distro's libgit2 or libcurl is built for the distro's needs, and if pkg-config finds it, your Cargo silently links the untested copy. Nothing warns you, and the behaviour difference would show up as something inelegant in git dependency resolution rather than as an obvious build error.

Build on a machine where pkg-config cannot find those libraries, or point it somewhere it will not look, and let the vendored copies in. On Windows the Schannel implementation is used instead of OpenSSL, and LibreSSL is supported for the Unix case.

There are no Cargo releases, because the version is the toolchain

This repository has no GitHub releases, and the documentation explains why in a single sentence: Cargo releases coincide with Rust releases.

That is the whole operational model. You do not choose a Cargo version, you choose a Rust toolchain through rustup, and whatever Cargo shipped alongside it is the Cargo you have. High level release notes live with Rust's own release notes, and the detailed notes are published as a changelog on the nightly documentation site rather than as tagged releases here.

The practical consequences are several and they all follow from that one fact. You cannot upgrade Cargo to fix a bug without moving your whole toolchain. You cannot stay on a Rust version and take a newer Cargo. You cannot put a Cargo version in a lockfile or a requirements file, because nothing in your project declares one. And the documentation you find for a given Cargo is whatever was current for the toolchain you happened to install.

For teams this is mostly a non-issue, because the toolchain moves for other reasons anyway. It becomes a problem in the cases where Cargo matters more than the compiler, such as a build environment pinned for reproducibility or a CI image that cannot move.

There, the only lever is the toolchain channel itself.

Three licence files exist while the metadata records one

The licence story is more layered than a single file suggests, and the pieces do not line up.

The front page states that Cargo is primarily distributed under the terms of both the MIT license and the Apache License, Version 2.0, and points at two files, LICENSE-APACHE and LICENSE-MIT. The workspace manifest agrees, declaring the licence as MIT OR Apache-2.0.

Yet the licence metadata recorded for this project lists Apache-2.0 on its own. A tool that reads only that single value will report one licence where there are two options, and will not mention MIT at all.

There is then a third file. LICENSE-THIRD-PARTY exists because the product includes software developed by the OpenSSL Project and, in binary form, software licensed under the GNU General Public License version 2 with a linking exception, obtainable from the libgit2 upstream repository.

That last point is the one with teeth for redistributors. Cargo is a dual-licensed Rust project, but the binary you ship contains a component under GPL-2.0 with an exception, which is why the third file has to be carried alongside the other two.

If you audit licences automatically, read the three files rather than trusting the metadata field, and ship the third-party file with your binary.

Credential storage is split into separately versioned per-platform crates

There is a credential/ directory at the top level, and it contains a family of small crates with individual version numbers in the workspace dependency table.

You can see them there: cargo-credential-libsecret for Linux, cargo-credential-macos-keychain for macOS, and cargo-credential-wincred for Windows, alongside the cargo-credential interface crate itself. Each is declared with both a path inside this repository and its own version.

The structure tells you something about how Cargo stores registry credentials. It is not one implementation with platform branches, it is three independent helpers behind a common interface, and each ships on its own release cadence. A version bump on one platform's helper does not move the others.

Two practical effects follow. The first is platform-specific behaviour, since the storage backend, its security properties and its failure modes are entirely different on each of the three systems, and a problem with credential prompts may well be Linux-only or Windows-only. The second is that each helper is versioned separately in the workspace dependency table, so record which helper version you are diagnosing.

If you are diagnosing a credential problem, identify the platform first, then look at the helper crate rather than Cargo itself.

Subcommands are an extension point with no API behind them

Cargo is designed to be extensible with new subcommands without having to modify Cargo itself, and the project maintains a wiki page listing known community-developed subcommands.

That sentence is a precise description of the mechanism and of its limits. Because nothing in Cargo needs to change, adding a command means providing an executable that Cargo can find, conventionally as a cargo-something binary on the path. There is no plugin manifest, no registration call, no capability declaration and no version negotiation.

Which means there is no compatibility contract either. A third-party subcommand's behaviour, its flags and its output format are its own business, and a Cargo upgrade will not warn you about anything. The extension point is deliberately as thin as it is, which is exactly why the ecosystem can add commands without upstream coordination.

The consequence for you is that subcommands are worth reaching for when a command does something self-contained, and worth being careful about when you depend on one in a script. Anything parsing its output is coupled to a tool that nobody version-locks for you.

Pin the tool yourself if you automate around it.

Building Cargo from source needs Rust 1.95 and edition 2024

The workspace manifest sets the floor for the project itself:

[workspace.package]
rust-version = "1.97"  # MSRV:3
edition = "2024"
license = "MIT OR Apache-2.0"

That minimum supported Rust version is far higher than most Rust projects declare, and the edition is the 2024 one. If your toolchain is pinned to anything older, you cannot build Cargo from source, and the message you get will be a version requirement rather than anything suggesting a workaround.

The workspace also uses the version 2 resolver, and its members are the crates under crates/, the credential helpers, and two benchmark targets. A target/ directory is explicitly excluded, with a comment noting it is excluded for bench testing.

The clone and build themselves are short. With cargo already installed:

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

followed by cargo build --release. The stated prerequisites beyond that are rustc and cargo, a C compiler for your platform, and git.

The C compiler requirement is the one people forget, because building a Rust project does not normally need one. It exists for the C libraries Cargo vendors.

Editorial conclusion

cargo is not a decision most teams make, it is the toolchain that arrives with Rust, and that framing explains most of its rough edges. Two things are worth checking if you build it yourself or link against it. Confirm your system is not supplying an untested libcurl or libgit2 through pkg-config, since the vendored copies are the ones the project says are tested. And if you depend on the crate rather than run the binary, assume the API can change under you, because the project says so in those terms. For documentation, the Cargo Book and the contributor guide cover everything the front page does not.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. Project website
4. README
5. rust-lang/cargo on GitHub