Guide to Go Modules: Versioning, Dependency Management, and Common Commands

When a project starts using Go, the traditional tools such as Makefile, goinstall and go get evolve into the modern module system, which records precise dependency requirements and enables reproducible builds.

Versioning and API stability are achieved by adding version information to the import path; vendoring copies dependencies into a vendor directory to guarantee repeatable builds, and the official experiment dep explored best practices before the built‑in module support.

The module concept solves the problem of defining a single versioned unit, requiring semantic versioning (semver) and using tags on the repository to mark releases.

Basic operations start with creating a directory and a hello.go file, initializing the module with go mod init example.com/hello , and writing simple functions and tests. Example code: package hello func Hello() string { return "Hello, world." } Test example: func TestHello(t *testing.T) { want := "Hello, world." if got := Hello(); got != want { t.Errorf("Hello() = %q, want %q", got, want) } } Running go test verifies the module works.

The generated go.mod file lists the module name and Go version, while go.sum stores cryptographic hashes of each dependency. Upgrading a dependency is done with go get , e.g., go get golang.org/x/text , and the new version appears in go.mod as an indirect requirement.

Specific versions can be requested, for example go get rsc.io/[email protected] , and new major versions are imported with a versioned path such as import "rsc.io/quote/v3" . Sample code using the v3 module demonstrates calling quoteV3.Concurrency() .

For local development, the replace directive can point a module to a local path, and Git configuration can rewrite remote URLs to private proxies. It is essential to commit both go.mod and go.sum to avoid checksum errors.

Finally, go mod tidy removes unused dependencies, leaving a clean module definition.