cargo-edit: managing Cargo.toml dependencies from the command line

What cargo-edit changes, and what it deliberately does not

Cargo already has a way to move dependency versions: cargo update. That command rewrites Cargo.lock, the resolved graph, and leaves the version requirements written in Cargo.toml alone. cargo-edit works on the other file. Its cargo upgrade subcommand, in the README's words, "Upgrade dependency version requirements in Cargo.toml manifest files", and cargo set-version changes the version field of a package in the local manifest.

The audience is narrow and identifiable. If you maintain a library and want its declared semver ranges to move forward, or you maintain a workspace and want one version number propagated across several crates, cargo-edit is aimed at you. If you only want newer transitive dependencies resolved for a local build, cargo update already does that and you do not need this tool.

The README is explicit that the surface has shrunk. cargo add was integrated into Cargo as of v1.62 and cargo rm as of v1.66. The README lists only cargo upgrade and cargo set-version as currently available subcommands in the header, while still keeping the add and rm sections for older toolchains. That is the honest state of the project: two commands, not four.

How cargo upgrade decides what a version requirement becomes

The mechanism is a manifest rewrite, not a lockfile update. cargo upgrade reads the manifest, resolves what newer versions exist, and writes new version requirement strings back into Cargo.toml. The README contrasts this directly with cargo update, which "updates the dependency versions recorded in the local lock file (Cargo.lock)".

The interesting part is that upgrades are classified rather than applied uniformly. The help output exposes three switches, each taking allow or ignore: --compatible (default allow), --incompatible (default ignore), and --pinned (default ignore). So a plain cargo upgrade moves requirements to the latest compatible version and stops there. Crossing a semver boundary requires opting in with --incompatible allow, and pinned dependencies need --pinned allow on top of that. That default is conservative in a useful way, but it also means the command name overpromises: running cargo upgrade without flags will not take you to the newest release of everything.

Version targets can be stated per crate with the <crate name>@<version> form. The README's example passes ranges through: cargo upgrade -p docopt@~0.9 -p serde@>=0.9,<2.0. There is also an exclusion path, --exclude docopt --exclude serde, for the crates you want left alone. Two other flags matter in practice: -n, --dry-run prints the changes without applying them, and --rust-version with --ignore-rust-version controls whether the tool respects the rust-version field when choosing targets. --locked requires Cargo.toml to be up to date before the command runs.

Installing cargo-edit and running a first dry-run upgrade

The README's installation path assumes a reasonably recent Rust and Cargo toolchain, and notes that on Ubuntu you also need libssl-dev and pkg-config. The install itself is a normal cargo install of the crate, which places the cargo-* binaries somewhere on your PATH so Cargo can dispatch to them as subcommands.

cargo install cargo-edit

After that, cargo upgrade and cargo set-version should be callable as Cargo subcommands. The README points at cargo's own documentation for how cargo install works and how to make sure your system finds the binaries it installs, which is worth reading if the subcommands are not found afterwards.

If you do not want the whole set, the README documents a feature-gated install. The binary targets in Cargo.toml are gated behind the features add, rm, upgrade and set-version, so a trimmed build is possible.

cargo install -f --no-default-features --features "upgrade set-version"

Before letting it write anything, run the upgrade in dry-run mode against a real manifest. The README documents -n, --dry-run as printing the changes to be made without making them, so this is the step where you see exactly which version requirement strings would be rewritten.

cargo upgrade --dry-run

If you want to move a single crate across a semver boundary, name it and opt in to incompatible upgrades. The README's -p flag accepts the <crate name>@<version> form, so you can state the target range explicitly rather than letting the tool choose.

cargo upgrade -p serde@>=0.9,<2.0 --incompatible allow

cargo set-version and the workspace version bump

cargo set-version changes a package's version in the local manifest. It takes a target version as a positional argument, or derives one from --bump with major, minor or patch. The README's examples cover both: cargo set-version 1.0.0 sets an explicit version, and cargo set-version --bump minor increments the minor component.

The workspace behaviour is the part that earns the tool its place. --workspace modifies all packages in the workspace, and --exclude keeps named crates out of that sweep. The older --all flag is marked deprecated in favour of --workspace in the help output. For a repository that ships several crates under one version number, this replaces a script that opens every Cargo.toml and edits the same line. -p, --package narrows the change to a single package when you do not want the whole workspace touched.

Two smaller details are worth knowing. -m, --metadata sets the version metadata field, which the README explains with a link to the semver crate's BuildMetadata documentation, and describes as useful for a wrapped library's version. --offline runs the command without accessing the network, which is the flag to reach for in a sandboxed build environment. As with upgrade, -n, --dry-run prints the intended change first, and --locked requires the manifest to be up to date.

Where cargo-edit is the wrong tool

The clearest limitation is that cargo-edit edits files, and the README does not document a rollback command. --dry-run exists, so the intended workflow is to inspect before applying, but once cargo upgrade has rewritten version requirements in Cargo.toml, undoing it means reverting the file through version control or by hand. If your manifest is not committed, or is generated by another tool, that is a real risk rather than a theoretical one.

The second limitation is scope drift. Anyone reaching for cargo-edit to add a dependency is working against the project's own direction: cargo add has been in Cargo since v1.62 and cargo rm since v1.66, and the README sends older toolchains to cargo-edit v0.9 or earlier for add and v0.11 or earlier for rm. Installing the current release to get add is the wrong reason to install it.

Third, the default upgrade behaviour is narrower than the command name suggests. Without --incompatible allow, requirements stay inside their compatible range, and pinned dependencies are not moved at all unless --pinned allow is passed. A team expecting cargo upgrade to bring every dependency current will be surprised by the diff. That default is defensible, but it needs to be understood before the command runs in CI.

Finally, this is a tool that writes to the manifest of the crate you are working on. It is not a dependency auditor, it does not tell you whether a newer version is a good idea, and it has no opinion about the security or maintenance status of what it upgrades.

cargo-edit against cargo update and the newer Cargo subcommands

The honest comparison is not against a third-party competitor but against Cargo itself. cargo update moves Cargo.lock; cargo upgrade moves Cargo.toml. They answer different questions. If your goal is a reproducible build with newer transitive dependencies, cargo update is the right command and cargo-edit adds nothing. If your goal is to publish a library whose declared version requirements are current, cargo update does not help at all, because it never touches the manifest.

For the add and rm cases, the alternative is simply Cargo. The README documents the differences from cargo-edit v0.9.1 that came with that move: cargo add <path> is unsupported in favour of cargo add --path <path>, and the +<feature> syntax is replaced by -F <feature>, with multi-crate feature additions qualified as cargo add serde -F serde/derive serde_json. Those are small syntax changes, but they mean instructions written for cargo-edit's add subcommand will not work against Cargo's own implementation.

The README also points at two neighbouring tools in a Related Cargo Commands section: cargo feature and cargo override. Both are separate projects with their own repositories, and neither is a replacement for cargo-edit's version-editing commands.

Maintenance, licence and the cost of upgrading cargo-edit itself

The repository is not archived, and the last push was on 2026-07-15, which is recent enough that the project is not dormant. The release history supports that: v0.13.13 on 2026-07-15, v0.13.12 on 2026-07-14, and v0.13.11 on 2026-05-28. Releases cluster, which suggests work arrives in bursts rather than continuously, but there is no gap long enough to call the project abandoned.

There is a real upgrade cost, and it comes from the toolchain requirement rather than from cargo-edit's own API. The crate's Cargo.toml declares edition = "2024" and rust-version = "1.92". Building the current release therefore needs a Rust toolchain at or above that version, which is a higher floor than many CI images carry by default. Teams on an older pinned toolchain will either upgrade Rust or stay on an older cargo-edit release.

The licence situation is permissive and slightly unusual in how it is declared. The repository is listed under MIT, while the crate manifest states license = "Apache-2.0 OR MIT", which is the common dual-licence arrangement for Rust crates. For most users this changes nothing; if your organisation has a policy about which of the two it accepts, read the LICENSE file in the repository rather than relying on the summary. This is a description of what the files say, not legal advice.

One maintenance note from the README is worth repeating for anyone filing bugs: questions go to the issue tracker or the Gitter channel, and the project asks that large changes be discussed in an issue before a pull request is opened. The README also states that cargo-edit has a moderately comprehensive test suite and asks contributors to add tests for every change.

Editorial conclusion

cargo-edit is worth installing if you maintain a workspace, need to bump Cargo.toml version requirements rather than Cargo.lock entries, or want cargo set-version to apply --bump across --workspace. Skip it if you only need cargo add or cargo rm: both are in Cargo as of v1.62 and v1.66, and the README points older toolchains at cargo-edit v0.9 or v0.11 instead. Before adopting, run cargo upgrade --dry-run on your own manifest and check what --compatible and --pinned would do to your version requirements, because the tool rewrites Cargo.toml and the README does not document a rollback command.

Frequently asked questions

Official sources

1. killercup/cargo-edit on GitHub
2. License: MIT
3. Project website
4. README
5. Releases