A Go module declares itself deprecated with a Deprecated: comment in its go.mod. You can see it by running go list -m -u on the module, and go get shows it when you fetch packages from it. Treat the message as a prompt to find the replacement, not as proof the code is unsafe.
How deprecation is written
From the Go modules reference, a deprecation is a comment block with Deprecated: (case sensitive) at the start of a paragraph, placed just before the module directive or on the same line after it:
// Deprecated: use example.com/mod/v2 instead.
module example.com/mod
Rules worth knowing:
- It applies to all minor versions of the module path.
- Major versions above v2 are separate modules, so v3 is not deprecated by a note on v2.
- Individual minor and patch versions cannot be deprecated. The reference says retract may be more appropriate for those.
Where you see it
go list -m -u checks for deprecation (since Go 1.17), and go get checks for modules needed by the named packages. Checking is on the latest version of the module, so a note added after you adopted it shows up the next time you run the command.
A check you can run today
- List modules with updates and notices:
go list -m -u all. - Scan the output for deprecation text beside a module name.
- For each hit, read the message and note the suggested replacement.
- Run
go mod why -mon it to see whether your build imports it directly or through another module. - If a direct import, plan the migration. If transitive, update the parent module that still imports it.
What deprecation does and does not tell you
| Signal | Meaning |
|---|---|
| Deprecated comment | Maintainer says use something else |
| Retracted version | Maintainer says do not use this version |
| Known vulnerability | A reviewed advisory exists |
| No updates for years | Unclear, check the maintainer's statement |
A deprecated module may still be secure today, but it will not get fixes. That matters the next time an advisory lands, because there may be nobody to ship a patch. For more on judging stale projects, see last commit two years ago, is the dependency abandoned.
Make it routine
Add go list -m -u all to a scheduled job and send the output to the team that owns the module. A quarterly review is enough for most services.
Where Safeguard fits
Safeguard's dependency scanning and policies can flag packages that meet your criteria and gate pull requests that add them. Run a free scan to see your current inventory.
Quick check
Can I deprecate just one Go module version?
No. The Go reference says individual minor and patch versions cannot be deprecated, and suggests retract instead.
Is a deprecated module vulnerable?
Not necessarily. It means the maintainer recommends something else, so fixes may stop.
Sources
Last reviewed: 19 October 2026.
