With Cargo, how do you move only one transitive dependency in Cargo.lock to a fixed release, and what if no dependent's range allows it?
answer
- plain update moves everything
- name one package spec
- pick the exact version
- override the source at the root
basics
~20 sRun cargo update -p NAME (a conservative update that moves only that package) or add --precise VERSION to pin the fixed release. If a dependent's requirement excludes the fix, upgrade that dependent or add a [patch.crates-io] entry pointing at a fixed copy.
solid answer
~40 sA bare `cargo update` re-resolves every package to the newest version its ranges allow, which turns a one-line security fix into a large diff. `cargo update -p NAME` (or `cargo update NAME`) is a **conservative update**: only that package moves, and its own dependencies move only if they must. Adding `--precise VERSION` sets the exact version instead of the newest; it must still satisfy every requirement in the graph. When a dependent's requirement shuts the fixed release out, you either upgrade that dependent to a release that accepts it, or add `[patch.crates-io]` in the workspace root manifest pointing at a fork or local copy whose version still fits the requirement. `cargo tree -i NAME` confirms what you ended up with.
code
toml · 11 lines# collector/Cargo.toml (workspace root)
[package]
name = "collector"
version = "0.1.0"
edition = "2024"
[dependencies]
ingest = { path = "../ingest" } # ingest needs heapless = "0.9"
[patch.crates-io]
heapless = { path = "patches/heapless" }go deeper
Know that cargo update changes Cargo.lock, and that naming one package keeps the rest of the lockfile where it is.
Explain the conservative update with -p, what --precise adds, why it still has to satisfy every requirement, and how cargo tree -i confirms the result.
Show the escalation path when a range blocks the fix: upgrade the dependent, or a root-level [patch.crates-io] whose version fits, with a plan to delete it.
Turn the fix into routine: a lockfile-only change for advisories, recorded reasons for every patch, and libraries raising their minimum requirement.
## Scenario An advisory lands for a crate you never named in `Cargo.toml`: your service depends on `ingest`, and `ingest` depends on `heapless = "0.9"`. The fix is a new 0.9.x release. You want that one line of `Cargo.lock` to change and nothing else, so the pull request is easy to review and roll back. ## The cargo update family | Command | What moves | |---|---| | `cargo update` | Every package, to the newest version allowed by the ranges | | `cargo update -p heapless` | Only `heapless`, to the newest allowed; its dependencies only if required | | `cargo update -p heapless --precise VERSION` | Only `heapless`, to exactly `VERSION` | | `cargo update -p heapless --recursive` | `heapless` and its own dependencies (cannot be combined with `--precise`) | | `cargo update --dry-run` | Nothing; it prints what would change | Key details: - **Conservative update.** With a package spec, Cargo keeps every other entry at its locked version. The cargo-update page states it directly: transitive dependencies of the spec are updated only if the spec cannot be updated without them. - **`-p` is optional.** The spec can also be positional, `cargo update heapless`. - **Ambiguous names.** If two versions of the crate are locked, a bare name is rejected and Cargo prints the full specs to use, such as `[email protected]`. - **`--precise` respects requirements.** It picks an exact version, which is useful for taking a fix without jumping further, for downgrading away from a broken point release, or for merging two copies the resolver split. It can also select a yanked version, which the cargo-update page allows but does not recommend. - **Verify.** `cargo tree -i heapless` shows the version now in the graph and who depends on it. ## When the range shuts the fix out `cargo update` never breaks a requirement. If `ingest` asked for `heapless = "=0.9.3"`, or the fix exists only in a newer major, `--precise` fails. The options, in order of preference: 1. **Upgrade the dependent.** A newer `ingest` that accepts the fixed release is the clean fix. 2. **Patch the source.** In the **workspace root** `Cargo.toml`, add `[patch.crates-io]` with a path or git dependency on a copy that contains the fix. Cargo then offers that copy whenever anything in the graph asks crates.io for `heapless`, which reaches transitive dependents too. 3. **Remove the patch later.** Once a fixed release is published and accepted by the ranges, delete the entry and run `cargo update -p heapless`. Three rules decide whether a patch is used: - The patched copy's **version must satisfy the existing requirements**. A copy that claims 0.10.0 against `"0.9"` is ignored, and Cargo warns ``patch `heapless v0.10.0 (...)` was not used in the crate graph``. - **Only the workspace root's** `[patch]` counts; one written in a dependency's manifest is ignored without a warning. - If a patch is not picked up because the lock already holds a matching version, the warning's help text says to run `cargo update` (or `--precise` with the patched version) so the lock switches to it. The older `[replace]` table did a similar job keyed by an exact package ID; the Cargo book marks it **deprecated** in favour of `[patch]`. For a one-off local test, a patch can also come from the command line, as in `--config 'patch.crates-io.heapless.path="patches/heapless"'`. ## Checking the result 1. Preview with `cargo update -p heapless --dry-run`, which prints the planned change and writes nothing. 2. Run the real update; Cargo prints a line such as `Updating heapless v0.9.2 -> v0.9.3` or `Downgrading ...` for each entry it moves. 3. Confirm with `cargo tree -i heapless` that only the expected version remains and that every dependent now uses it. 4. Review the `Cargo.lock` diff: typically one `version` and one `checksum` line per moved registry package. ## Lockfile hygiene around a fix - Keep the change to `Cargo.lock` plus, if needed, the `[patch]` lines; reviewers can see exactly one package moved. - Note why a patch exists and when to remove it, so a fork does not outlive the fix. - A library cannot push its users onto the fix through its own lockfile. It must raise its `Cargo.toml` requirement, such as `"0.9.4"` once that release exists, because dependents resolve their own graphs.
- Why does the [patch] entry have to live in the workspace root manifest?Cargo reads `[patch]` only from the root of the workspace being built; patch tables in dependencies' manifests are ignored, without a warning. Overriding a source changes the whole graph, so only the top-level build gets to decide it, and a library cannot force a patch on its users.
- When would you reach for cargo update --precise to downgrade rather than upgrade?When a new point release breaks your build or behaviour, or when the resolver split a crate into two copies that one older version could serve. `--precise` sets the locked version back to a known-good release that still satisfies every requirement, without touching anything else, until the upstream fix or yank arrives.
- Does a yanked release disappear from projects that already locked it?No. The resolver ignores yanked releases for new resolution, but a version already in `Cargo.lock` keeps being used, and `--precise` can still name one explicitly. A yank stops new lockfiles from picking the release; existing lockfiles still have to be moved off it with `cargo update -p`.
- Run plain cargo update to pick up one security fix
- --precise can force a version outside the dependents' requirements
- A [patch] in a dependency's Cargo.toml applies to everyone using it
- Any patched copy is used, whatever version it declares
- [replace] is the current way to override a crate