Handling +incompatible Module Versions

The +incompatible Suffix

Some module versions in go.mod have a +incompatible suffix:

require (
    github.com/docker/docker v24.0.7+incompatible
    github.com/docker/go-connections v0.4.0+incompatible
)

What It Means

The +incompatible suffix indicates that a module:

1. Has a major version v2 or higher in its git tags
2. Does not have a go.mod file (or its go.mod does not use the /vN suffix)
3. Was created before Go modules became standard

Why It Exists

Before Go modules (pre-Go 1.11), Go packages did not follow the import compatibility rule. Many popular packages (like Docker) tagged v2, v3, etc. without using the /vN path suffix. When Go modules were introduced, these existing tags needed to work somehow.

The Compatibility Bridge

Go treats +incompatible versions as a special case:

• The module path does NOT include /vN (e.g., just github.com/docker/docker)
• The version is vN.X.Y+incompatible (e.g., v24.0.7+incompatible)
• Go knows this module predates the import compatibility rule

When You See It

github.com/lib/pq v1.10.9                    // Normal: v1.x, no suffix
github.com/docker/docker v24.0.7+incompatible // +incompatible: v24 but no /v24 suffix
github.com/example/mod/v2 v2.3.0             // Normal: v2 with /v2 suffix

Working With +incompatible Modules

• You cannot remove the suffix — it is determined by the module author's repository
• go get adds it automatically
• The formatter preserves the suffix as-is
• Functionally, it works like any other dependency

Migration Path

When a module author adds a proper go.mod with the /vN suffix, future versions will not need +incompatible. Users migrating will:

1. Change the import path to include /vN
2. Update go.mod to use the new module path
3. The +incompatible suffix disappears for the new version

Common +incompatible Modules

Many Docker ecosystem packages use +incompatible because they predate Go modules and have high major version numbers.