Retract Versions in go.mod
Learn how module authors use retract directives to mark published versions as broken or unintended. Understand retraction of single versions and version ranges with comments.
Detailed Explanation
Retract Directive
The retract directive allows module authors to mark published versions as should not be used. Unlike exclude (which is for consumers), retract is declared by the module author in their own go.mod.
Single Version Retraction
retract v1.0.0 // Published with wrong API
Version Range Retraction
retract [v1.0.0, v1.2.0] // All versions in this range had a data bug
Block Form
retract (
v1.0.0 // Accidental publish
[v1.1.0, v1.1.3] // Regression in database layer
v2.0.0-beta.1 // Incompatible schema migration
)
How Retraction Works
- Module author adds
retractdirectives togo.modin a new version - The new version's go.mod must be published (it cannot retract itself)
- When users run
go getorgo list, retracted versions are hidden - Existing go.mod files that already reference a retracted version are not affected
- Users can still explicitly request a retracted version with
go get module@v1.0.0
Retraction Comments
Comments on retract directives are displayed to users who try to use the retracted version:
retract v1.5.0 // Security vulnerability CVE-2024-1234: upgrade to v1.5.1
The comment explains why the version was retracted and suggests an alternative.
Best Practices
- Always include a comment explaining the retraction reason
- Suggest an alternative version in the comment
- Publish the retraction in a patch release (e.g., retract v1.5.0 in v1.5.1)
- Use ranges when multiple consecutive versions are affected
- Never retract the latest version without publishing a newer one first
Self-Retraction
A module can retract its own version in a newer release:
// In v1.5.1's go.mod:
retract v1.5.0 // Memory leak in connection pool
But v1.5.1 cannot retract itself — that would create a paradox.
Use Case
Retract directives are essential for module authors who accidentally publish broken versions. Instead of deleting versions (which Go's proxy caches prevent), authors retract them. This maintains the immutability of published versions while clearly signaling to users that they should upgrade. The formatter preserves retract comments, which serve as important user-facing documentation.