Understanding Go Modules: From GOPATH to Modern Dependency Management

2020 Tencent internal reports show Go has become the second‑largest backend language within the company, exposing many scaling and security issues that are gradually being solved by Go Modules and related tooling.

The author, responsible for Go usage in Tencent Cloud, introduces the series by describing the shift from the traditional GOPATH workflow to Go Modules , which now powers services such as Tencent Cloud, WeChat, Tencent Video, Games, Music, and Meeting.

1. Evolution of Go development models

Initially Go relied on the GOPATH environment variable for locating source, binaries, and packages. As the language grew, dependency problems emerged, leading to the introduction of Go Modules around the 10‑year anniversary of Go.

2. GOPATH usage

go install installs binaries to $GOPATH/bin .

go install also installs compiled packages to $GOPATH/pkg .

go get downloads source to $GOPATH/src .

3. Go Modules timeline

Go 1.11 (Aug 2018) introduced GO111MODULE with values off , on , auto .

Go 1.13 (Aug 2019) relaxed auto rules, allowing module mode inside $GOPATH/src when a go.mod file exists.

Go 1.16 (Feb 2021) made GO111MODULE=on the default, effectively disabling GOPATH mode unless overridden.

Future Go 1.NN will deprecate GO111MODULE and remove GOPATH mode entirely.

4. GOPATH vs. Go Modules

GOPATH will remain as an environment variable for locating the binary cache ( $GOPATH/bin ), module cache ( $GOPATH/pkg/mod ), and checksum database ( $GOPATH/pkg/sumdb ), but the development workflow will default to Modules.

5. Frequently asked questions

Will GOPATH be removed? No, it stays for backward compatibility.

Can I still create code under GOPATH/src ? Yes, just add a go.mod file.

How to test changes to a dependency? Use the replace directive in go.mod to point to a local copy.

6. Hands‑on tutorial: creating a module from scratch

Create a directory and source file:

package hello

func Hello() string {
    return "Hello, world."
}

Create a test file:

package hello

import "testing"

func TestHello(t *testing.T) {
    want := "Hello, world."
    if got := Hello(); got != want {
        t.Errorf("Hello() = %q, want %q", got, want)
    }
}

Running go test fails because no go.mod exists. Initialise the module:

go mod init example.com/hello

Now go test passes and a go.mod file is created:

module example.com/hello

go 1.17

7. Adding a dependency

Import rsc.io/quote in hello.go and run go get rsc.io/quote . The command downloads the module and its indirect dependencies, updating go.mod and creating go.sum with cryptographic hashes.

module example.com/hello

go 1.17

require (
    golang.org/x/text v0.0.0-20170915032832-14c0d48ead0c // indirect
    rsc.io/quote v1.5.2 // indirect
    rsc.io/sampler v1.3.0 // indirect
)

Running go test again succeeds without re‑downloading.

8. Managing dependencies

List all modules with go list -m all , update a module (e.g., go get golang.org/x/text ), and verify the updated go.mod reflects the new version.

9. Conclusion

Go Modules unify dependency management across the Go ecosystem, are fully integrated into the Go toolchain, and provide better developer experience, performance, and security. Teams still using GOPATH are strongly encouraged to migrate to Modules.