A retract directive in go.mod tells users that a module version should not be depended on. The go command stops choosing it for latest and upgrade queries and prints warnings, but the version stays downloadable and existing builds keep working. It is a warning mechanism, not a removal.
What retraction changes
According to the Go reference, when a version is retracted:
- go get, go mod tidy and similar commands will not upgrade to it automatically.
- go list -m -u shows whether your current version is retracted.
- go get prints a warning for each retracted version it finds after selecting versions.
- Retracted versions are hidden from go list -m -versions unless you add the retracted flag.
- They are excluded when a query like latest is resolved.
The reference also says retracted versions should remain available on version control and module proxies so that builds depending on them do not break.
What it does not change
If you already depend on a retracted version, your build keeps working. Nothing forces an upgrade. You only find out if you check for updates or touch a related module.
That is why retraction alone is a weak control for a security problem. A consumer who never runs an update check may never see it.
Retract versus other signals
| Signal | Who sets it | Effect |
|---|---|---|
| retract in go.mod | The module author | Warns and hides from latest queries |
| Vulnerability advisory | A database maintainer | Scanners report affected versions |
| Deprecated comment | The module author | Warns that the module should not be used |
For a vulnerable release, authors should do both: publish a fixed version that retracts the bad ones, and file an advisory so scanners can match it.
How to check your own project
go list -m -u all
Look for the word retracted next to a version in the output. The reference shows an example line with the format module, version, retracted marker, and the available upgrade in brackets.
How an author retracts a version
Add the directive to the go.mod of a newer version, with a comment explaining why:
retract v1.0.1 // Contains a vulnerable parser, use v1.0.2
The new version must be higher than the ones being retracted, so that latest resolves to it before retractions are considered. A version that contains retractions may retract itself.
The directive needs Go 1.16 or later.
Quick check
Does retract delete a version from the proxy?
No. The Go reference says retracted versions should remain available so existing builds do not break.
If my scanner shows nothing, am I safe from a retracted version?
Not necessarily. Retraction is a notice, and a scanner only reports it if its data includes it. Run go list -m -u all as well.
Safeguard's dependency scanning reports known advisories against the versions in your inventory, and continuous monitoring rechecks them as new data arrives. The free scan is a quick way to see your own list.
Sources
Last reviewed: 19 October 2026.
