Major Version Suffixes in Go Module Paths

Major Version Suffixes

Go modules enforce a unique convention: module paths for major version 2 and above must include a version suffix. This is known as the import compatibility rule.

The Rule

require (
    github.com/example/lib    v1.5.0    // v0 or v1: no suffix
    github.com/example/lib/v2 v2.3.1    // v2: /v2 suffix required
    github.com/example/lib/v3 v3.0.0    // v3: /v3 suffix required
)

Why This Convention?

Go's import compatibility rule states: if an old package and a new package have the same import path, the new package must be backward-compatible with the old one. Since major version bumps indicate breaking changes, a different import path is required.

Coexisting Major Versions

This design allows different major versions to coexist in the same binary:

import (
    v1 "github.com/example/lib"
    v2 "github.com/example/lib/v2"
)

This is useful during gradual migrations from v1 to v2 of a library.

Module Authors: Creating v2+

To release v2 of a module, authors have two options:

1. Major branch: Create a v2 branch, update go.mod to module github.com/example/lib/v2
2. Major subdirectory: Create a v2/ directory with its own go.mod

Common Mistakes

The formatter detects a key error: mismatched path suffix and version:

// ERROR: path says v3 but version is v2.x
github.com/example/lib/v3 v2.1.0

This would fail go mod tidy validation.

v0 and v1 Exception

Modules at v0.x.x or v1.x.x do not use a suffix. The v0 prefix indicates instability (no compatibility guarantee), and v1 is the default major version.