packageurls
← Blog

2026-11-12

Versioning Go modules behind a domain you control

You set up a vanity domain – go.yourcompany.com, pkg.yourname.dev, whatever – so your import paths are stable no matter where you host git. Then you ship v2 and realize the module path has to change anyway; the import path you worked so hard to stabilize now has /v2 bolted onto the end. That isn’t a bug in Go’s module system; it’s the design, and once you understand why, the wiring makes a lot more sense.

v0 and v1 have no version suffix

For any module at v0 or v1, the module path has no major-version suffix. If your module is pkg.yourname.dev/acme/toolkit, that’s exactly what goes in go.mod:

module pkg.yourname.dev/acme/toolkit

go 1.21

Users import it as pkg.yourname.dev/acme/toolkit/somepackage. The go tool fetches the ?go-get=1 response from your vanity server, finds the <meta name="go-import"> tag, and follows the git URL from there. v0 and v1 share this path; there is no /v1 suffix. A final path element of the form /vN must not be /v1; the go command does not accept it.

The v0 tag series is really useful if your API isn’t settled yet; you can make breaking changes freely under v0 without incrementing the major version. Once you’re satisfied the API is stable, tag v1.0.0 and the path stays exactly the same – nothing changes for users, and the unsuffixed path just keeps working.

When /v2 belongs in the import path

The moment you tag v2.0.0, the module path must change; the /v2 suffix is not optional. Your go.mod becomes:

module pkg.yourname.dev/acme/toolkit/v2

go 1.21

Every import inside your own v2 code changes too; import "pkg.yourname.dev/acme/toolkit/helper" becomes import "pkg.yourname.dev/acme/toolkit/v2/helper". This is the major version suffix convention, and proxy.golang.org and the go toolchain both enforce it.

Go requires it because v1 and v2 of the same library can coexist in a single build. If both used the same import path, the linker couldn’t tell them apart; so the path change is how the module system makes two major versions simultaneously importable without conflict. It feels strange the first time, but it means a project that depends on your v1 and another project that depends on your v2 can both compile into the same binary without either of them breaking.

Your vanity domain doesn’t change any of this; you still serve a <meta name="go-import"> tag, but now you decide whether the v2 path resolves to the same repo (via a tag or branch) or a completely separate repo. Both approaches work; most people choose the same repo because it’s so much simpler to maintain.

Tag naming that proxy.golang.org expects

proxy.golang.org caches module versions by git tag. For v1, your tags are plain semver: v1.2.3. For v2, they’re v2.0.0, v2.1.0, and so on; no path prefix, just the semver tag. The tag’s major version must match the module path’s suffix. A v2.0.0 tag belongs to a /v2 module path; it does not belong to the unsuffixed v0/v1 path.

One thing that trips people up: if your module lives in a subdirectory of the repo – which is really only relevant for monorepos where the module root isn’t the repo root – you might see tags prefixed with a directory component, like toolkit/v2.0.0. If your vanity module is at the repo root, plain v2.0.0 is correct; adding a prefix will break resolution. Per the Go module reference, the module subdirectory excludes the major-version suffix, so a module in a v2/ major-version subdirectory still uses plain v2.0.0 tags (not v2/v2.0.0).

Pre-release tags such as v2.0.0-beta.1 are valid semver. go get pkg.yourname.dev/acme/toolkit/v2@v2.0.0-beta.1 selects that version. @latest prefers a release; it selects a pre-release only when no release exists.

Retiring a major version without breaking old go.mod lines

When you ship v2, you don’t have to delete v1. Existing projects that import pkg.yourname.dev/acme/toolkit at v1 keep working; their go.mod files still resolve to the v1 tags, and proxy.golang.org still serves them. You just stop cutting new v1 releases.

The two common strategies for the repo layout are subdirectory and branch. With the subdirectory strategy, you keep v1 code at the repo root and put v2 source in a /v2 directory; both versions share the same repo and the same git history. With the branch strategy, you create a v2 branch and update the module path there, leaving main as your v1 codebase. Either approach works; the subdirectory layout is generally simpler if your CI runs on the default branch, since you don’t have to keep two long-lived branches in sync indefinitely.

Because you own the vanity domain, you also control the <meta name="go-import"> responses; that means you can point both pkg.yourname.dev/acme/toolkit and pkg.yourname.dev/acme/toolkit/v2 at the same git repo. The toolchain resolves the right code from the right tag; you don’t need two separate repos to support two major versions.

You must avoid breaking the v1 <meta> response. If an old go.mod still references your v1 path and your vanity server stops returning a valid response for it, builds fail for every project that hasn’t upgraded. Even if you consider v1 end-of-life, keep serving a valid go-import response for that path and keep the v1 tags in the repo.

Documenting versions on the vanity site itself

This is the part most people skip; it’s also the part that frustrates users the most. If your vanity domain is pkg.yourname.dev, you probably have some kind of landing page; that page is a really good place to document which module paths are active, which major version is current, and how to migrate.

At minimum, show users:

  • The current module path – pkg.yourname.dev/acme/toolkit/v2
  • The exact import line they should paste into their code
  • Which version is stable vs. in pre-release
  • A link to the changelog or a v1-to-v2 migration guide

pkg.go.dev auto-generates API docs from your source; it doesn’t explain your versioning decisions or migration path, so that context has to come from you. Users who land on your vanity domain directly – because they searched for it or followed a blog link – deserve a clear answer to “which version do I use and how do I get it.”

When the go tool hits pkg.yourname.dev/acme/toolkit/v2?go-get=1, you serve the go-import meta tag; when a human hits the same URL without that query parameter, Package URLs redirects them to the git repository.

What you end up with

A stable vanity domain plus correct major version paths gives you the best of both: you’re not coupled to any git host, and you handle major API breaks cleanly without forcing every downstream user to scramble at once. v1 stays alive at the unsuffixed path; v2 picks up the /v2 suffix in the module path and in every import inside it; tags follow plain semver; and proxy.golang.org handles the caching.

The discipline required is really just two things: keep your vanity server running and keep the git tags consistent. Both are far simpler than the alternative – rewriting import paths across every project that depends on you every time you switch hosting or ship a breaking change.