Add a patch table to Cargo.toml that names the registry and the crate, and point it at your fork by Git URL and branch or a local path. Cargo then uses your copy everywhere in the dependency graph, including inside other crates. Treat it as temporary and write down who removes it.
What the patch section is for
The Cargo book describes patch as a way to override dependencies with other copies, and lists use cases such as testing a bug fix, working with an unpublished version, overriding a repository URL and prepublishing a breaking change. The problem it solves is waiting: you found a bug in a crate, fixed it, and do not want to block on the fix being merged and released.
Syntax
[patch.crates-io]
examplecrate = { git = "https://github.com/acme/examplecrate.git", branch = "security-fix" }
localcrate = { path = "../localcrate" }
The syntax mirrors the dependencies section. The table name says which source is being replaced. For crates from the main registry, that is crates-io. For a crate fetched from a Git URL, the table name is that URL.
The Cargo book also notes that the patch table can be set in a Cargo configuration file or on the command line, which is useful for local changes you do not want to commit.
Why it is powerful, and why that is risky
| Property | Benefit | Risk |
|---|---|---|
| Applies across the graph | Fixes transitive uses without editing other crates | Everything uses your fork, including parts you did not review |
| Keeps the original dependency line | Little manifest churn | The manifest reads like upstream, hiding the fork |
| Can point at a branch | Easy to update | A branch can move. Prefer a pinned revision |
| Can live in a config file | Local only experiments | Builds differ between machines if the file is not shared |
Cargo's Git dependency syntax also accepts a tag or a revision, as the Cargo book's chapter on specifying dependencies explains. Check that chapter, then pin a revision so the build is reproducible. The same reasoning applies in pip and npm.
A safe workflow
- Fork the crate and make the fix on a branch. Open a private report or a pull request upstream as appropriate. See sending a fix upstream.
- Add the patch entry with a pinned revision, and a comment naming the reason and the owner.
- Run tests and your security checks with the patch in place.
- Add the fork to your register with an exit condition, such as "upstream releases a version containing the fix." See the fork register.
- When upstream releases, remove the patch entry, update the version requirement and rebuild.
Publishing a crate that uses a patch
The Cargo book says patch can only be defined at the top level, and that patch settings defined in dependencies are ignored. So the consumers of a library you publish have to repeat the patch section themselves. Release a proper fixed version, or ask upstream to. This mirrors the Go case in what a replace directive hides.
Auditing
A reader of Cargo.toml should be able to find every patch in one place. Search for the patch table in code review, and list each entry in your inventory.
Where Safeguard fits
Safeguard's dependency scanning and policy gates can flag changes to dependency sources in a pull request, so a new patch entry gets reviewed. Try a free scan at gold.safeguard.sh/scan.
Quick check
Does patch only affect my own code?
No. It overrides the dependency across the whole graph, including uses inside other crates, which is both its strength and its risk.
Branch or revision?
Prefer a pinned revision. A branch can move and change your build without a commit in your repository.
Sources
Last reviewed: 19 October 2026.
