Go 1.16: Retracting Versions in Go Modules

Source: Dev.to

Preface

Go Modules were officially introduced in Go 1.11, and they are enabled by default starting with Go 1.16. When a package is already published, you may encounter situations such as:

• Discovering a critical problem in a released version and wanting to prevent others from using it.
• Accidentally publishing a version with an incorrect version number (e.g., publishing v1.0.0 instead of the intended v0.4.0).

If the package has already been distributed, you need module version retraction to inform users about the issue and to stop future use of the problematic version.

This article explains the (still‑under‑publicized) retraction feature added in Go 1.16 and demonstrates how to use it.

TL;DR

• What is Retraction
• Why Retraction is Needed
• How Retracting Was Handled Previously
• How to Use Go Modules Retraction
• Related Learning Resources

What is Retraction?

Retraction marks specific module versions as retracted, indicating that they should not be used because they contain problems.

Why Retraction is Needed?

Typical scenarios:

1. Critical bug discovered after a version has been published and consumed by others.
2. Incorrect version number was released (e.g., v0.4.0 mistakenly published as v1.0.0) and other projects depend on it.

Retraction lets module authors communicate these issues directly through go get/go list.

How Retracting Was Handled Previously

Before Go 1.16, there was no built‑in retraction mechanism. Authors could only add notes to the README, but go get had no way to surface that information automatically.

How to Use Go Modules Retraction

The following example follows the official Go Playground demo.

Problem 1: A critical problem is found in a released version

Assume you maintain the module gopher.live/ue0ddd4a99c02/proverb and have already released version v0.2.0. After discovering a severe bug, you want to retract that version.

1. Add a retract directive to go.mod:

   go mod edit -retract=v0.2.0

   go.mod now looks like:

   module gopher.live/ue0ddd4a99c02/proverb
   
   go 1.16
   
   // Go proverb was totally wrong
   retract v0.2.0

2. Commit and tag a new version (e.g., v0.3.0):

   git add -A
   git commit -m "Fix severe error in Go proverb"
   git push origin main
   
   git tag v0.3.0
   git push origin v0.3.0

3. Observe the warning when someone tries to fetch the retracted version:

   go get gopher.live/ue0ddd4a99c02/proverb@v0.2.0
   go: warning: gopher.live/ue0ddd4a99c02/proverb@v0.2.0: retracted by module author: Go proverb was totally wrong
   go: to switch to the latest unretracted version, run:
       go get gopher.live/ue0ddd4a99c02/proverb@latest
   go get: downgraded gopher.live/ue0ddd4a99c02/proverb v0.3.0 => v0.2.0

   The warning makes it clear that v0.2.0 should no longer be used, and users are guided to the latest unretracted version.

Related Question

• Do I need to run go get (or go list) to see retraction information?
  Yes. The retraction metadata is retrieved when the module is queried via go get, go list, or similar commands.

Related Learning Resources

• Using Go Modules
• Go Dev Playground: Retract Module Versions
• Retract Go Module Versions in Go 1.16