If you come to Go from JavaScript, one small thing surprises almost every developer.

Open any package.json. Look near the top. It is always there:

{
    "name": "my-app",
    "version": "1.2.3"
}

You know your version right away. You can read it. You can change it in a pull request. You can grep for it. It is a fact that lives inside your code.

Now open a go.mod:

module github.com/you/my-app

go 1.22

Try to find your version.

It is not there. And that is not a mistake — it is on purpose. This post explains how Go handles versioning instead, why it works that way, and what changes for you if npm is the world you know.

🕳️ There is no version field

Let me be clear about one thing first: this is not about your dependencies. Go pins those very precisely:

require (
    github.com/gin-gonic/gin v1.9.1
    golang.org/x/text v0.14.0
)

Exact versions, no fuzzy ^ ranges, and builds that are always the same. This part is solid.

The surprise is about your own module. Go gives you no field in go.mod to write your own version. There is no version line, and there is no convention for one. If you are looking for it, you can stop — it does not exist.

So where does the version come from? A different place than you expect.

🏷️ The version is a git tag

Here is how you set the version of your own module in Go:

git tag v1.2.3
git push origin v1.2.3

That is the whole process. The git tag is the version. When someone runs go get github.com/you/my-app@v1.2.3, Go looks at your repository's tags and finds the matching commit. There is no registry, no version field, and no publish step. The tag is the single source of truth.

This design has a real strength. A version can never point to the wrong code, because it is a pointer to a commit. You cannot have a file that says 1.2.3 while the real code is something else. In npm, the published code and the tagged source can slowly drift apart, because they are two separate things. In Go, they cannot — they are the same thing.

So the model is consistent and hard to fake. The trade-off is in the day-to-day experience, especially if you are used to npm.

🤔 What is different day to day

Here are the concrete differences. None of these are bugs — they are the natural result of keeping the version in git instead of in a file.

Seeing your version takes a command. In npm, it is one file. In Go, you run git describe --tags in a terminal. The version lives in repository metadata, not in your source tree. So "what version am I?" is a command, not a glance.

A version bump is not a code diff. In npm, a bump shows up in the pull request: "1.2.3" → "1.3.0". Your team reviews it like any other change. In Go, a bump is a tag push. It is not part of any commit's content, so it does not appear in code review. Your release history and your git history are two separate records.

A local build has no clean version yet. Build a commit that has no tag, then ask the binary what it is. You get a pseudo-version like v0.0.0-20260616035800-4a9a8ad4fed2 — a timestamp plus a commit hash. Run it with go run instead and you get (devel). A clean, human version like v1.2.3 appears only after you tag that commit. (npm shows its version even on uncommitted code, because the version is just a field.)

Major versions go into the import path. This is the most surprising rule for npm users.

In npm, going from 1.x to 2.x changes only the version field. The package name stays the same, and code that imports it does not change.

In Go, starting at v2, the major version becomes part of the module path. So the same project has a different path for each major version:

• v1 → github.com/you/my-app
• v2 → github.com/you/my-app/v2
• v3 → github.com/you/my-app/v3

And everyone who uses your v2 must include the /v2 when they import it:

import "github.com/you/my-app/v2"

Why does Go do this? So one program can use v1 and v2 of the same library at the same time. They have different paths, so they never clash.

The cost is that your major version now lives in two places: the git tag (v2.0.0) and the module path (the /v2 in go.mod). They have to match. If the tag says v2 but the path does not end in /v2, the build breaks.

📊 Where other ecosystems keep the version

To put Go in context, here is where your own version lives in the tools many developers use.

Full honesty first: I mainly work with npm and Go. I have not used Rust, Python, Java, Ruby, or .NET in depth, so I am not an expert on them. But from what I can see, they all keep the version in a file, the same way Node does:

Most ecosystems keep the version in a file. Composer is the closest to Go — it usually uses git tags too — but it still lets you write the field if you want. Go is the one that relies on tags only. That is the design choice, stated plainly.

🛠️ How to work with it

If you are shipping Go and you miss the npm experience, here is the common way to get it back. The idea is simple: keep the tag as the source of truth, and show that version where people can see it.

Since Go 1.18, the binary already stamps a version from git on its own. But it is that long v0.0.0-timestamp-hash pseudo-version, which is not nice to print. So most projects inject a clean version at build time, straight from git:

package main

var version = "dev" // replaced at build time

func main() {
    // myapp --version  →  prints the real version
}

go build -ldflags "-X main.version=$(git describe --tags --always)" -o myapp

git describe --tags does the work here. On a tagged commit you get v1.2.3. A few commits later you get v1.2.3-4-gabc1234 — the version, the number of commits since the tag, and the commit hash, all automatically. You never bump anything by hand.

If you would rather read that stamped info from the runtime instead of passing it through ldflags:

import "runtime/debug"

info, _ := debug.ReadBuildInfo()
_ = info.Main.Version // "v1.2.3" on a tagged build, a pseudo-version otherwise, "(devel)" under `go run`

And if you want the full "tag, build, publish, release notes" flow in one command — the closest thing Go has to npm publish — most projects use goreleaser. It reads your tags, adds the ldflags, and ships the binaries.

None of this puts a version field into go.mod. But it lets your binary answer "who are you?" out loud, which is usually what you actually wanted.

🚪 An open question

Now the part for Go developers.

Both designs are real and both are used by huge ecosystems, so this is not "one is right and one is wrong." Each one optimizes for a different thing:

• A version field (npm, Cargo, Maven, and most others) is easy to read, easy to edit, and shows up in code review. The cost is that the field can drift away from the real code.
• A git tag (Go) can never drift, because the version is the commit. The cost is that the version is harder to see, harder to review, and, from v2 on, lives in two places at once.

Go picked the second one. That choice gives strong guarantees, and it removes a whole class of "the manifest says one thing, the code says another" bugs. It also moves the version out of the place a newcomer looks first.

So here is the honest question, for the people who know Go best:

Is the tag-only model the best we can do? Could Go keep the "version equals commit" guarantee and still give you a readable field in go.mod — for example, a field the tooling verifies against the tag? Or does adding a field always reopen the drift problem that tags were meant to solve?

I am genuinely asking. If you have shipped a lot of Go, I would like to hear how the tag model feels in practice — and whether you would change it if you could.