cargo add: Stop Editing Cargo.toml By Hand

WHY IT EXISTS Before cargo add, developers had to manually find a crate's latest version and then edit the Cargo.toml manifest file by hand. This process was tedious, error-prone, and required switching context away from the code. cargo add automates this, ensuring correct syntax and fetching rules directly from the command line.

THE MENTAL MODEL Think of cargo add as a structured editor for your Cargo.toml file, operated from the command line. It understands the different sections like [dependencies], [dev-dependencies], and [build-dependencies], and it knows how to handle versions, features, and sources like Git or local paths. It prevents the manual syntax errors and version lookup that come with editing the file yourself.

HOW IT WORKS When you run cargo add <crate_name>, Cargo queries the default registry (usually crates.io) for the latest compatible version. It then adds a corresponding line to your Cargo.toml under the [dependencies] section. You can modify this behavior with flags. For example, cargo add serde --features derive adds the serde crate and enables its derive feature. cargo add rand --dev adds the rand crate to the [dev-dependencies] table instead, making it available only for tests, examples, and benchmarks. You can also specify a source with --git <url> or --path <path>.

WHEN TO USE IT Use cargo add whenever you need to add a new dependency to your Rust project. It is the standard, modern workflow. It's also useful for modifying an existing dependency, such as adding a new feature (cargo add some_crate --features new_feature) or renaming the crate within your project (cargo add some_crate --rename my_crate).

WHEN NOT TO USE IT While powerful, cargo add is designed for adding or modifying one or more dependencies at a time within a single package. For complex, sweeping changes across an entire dependency tree, or for automated scripts that require precise TOML manipulation, you might still edit Cargo.toml directly or use a dedicated TOML parsing tool. It does not manage dependencies for an entire workspace at once; you must target a specific package with -p or run the command from within that package's directory.

ONE CANONICAL EXAMPLE To add the popular serde crate for serialization and enable its derive feature for use in your production binary, you would run: cargo add serde --features derive. To add the anyhow crate for error handling, but only for development purposes like integration tests, you would run: cargo add anyhow --dev. After a successful run, Cargo will print the features that were enabled for the dependency.