The shared filing cabinet problem
You clone a Go project from 2018. The README tells you to export GOPATH, run go get, and hope the dependencies resolve. You try it on a fresh machine with Go 1.22. The compiler complains about missing modules, or worse, silently places files in a directory you never asked for. You are not broken. The ecosystem moved on.
GOPATH was Go's original workspace layout. Imagine a single shared office where every project lives in the same src folder. Dependencies go into a central pkg directory or a local vendor folder. It worked when the language was small and projects rarely depended on each other. It broke when the community grew. Two projects could require different versions of the same library, and the shared workspace would silently overwrite one with the other. Builds became fragile. Reproducing environments required manual surgery.
Go Modules changed the layout entirely. Now every project carries its own manifest file named go.mod. Dependencies live in a shared local cache instead of your project folder. The compiler reads the manifest, fetches exactly what you need, and locks the versions so your code builds the same way tomorrow as it does today. You do not need to configure a workspace directory anymore. The toolchain handles it.
Modules are the default. The workspace directory is now a quiet utility belt.
How modules actually work
A module is a collection of Go packages shipped together with a go.mod file at the root. The manifest records the module path, the minimum Go version, and every direct dependency with its exact version. When you run a build command, the toolchain reads that file, checks the local cache, downloads missing versions, and writes a cryptographic lockfile called go.sum. The lockfile guarantees that every machine pulling the same repository gets the exact same dependency tree.
Here is the simplest module in action.
package main
import (
"fmt"
"rsc.io/quote/v3" // external dependency for demonstration
)
func main() {
fmt.Println(quote.Go()) // prints a famous Go proverb
}
Save that as main.go. Run go mod init example.com/myproject. The toolchain creates go.mod with a module directive and a go directive. Run go run main.go. The compiler sees the rsc.io/quote/v3 import, checks go.mod, finds nothing, contacts the default module proxy, downloads the package, stores it in the local cache, updates go.mod with a require line, and writes go.sum. The program prints the proverb. No global pollution. No manual downloads.
The local cache lives at $GOPATH/pkg/mod. Yes, GOPATH still appears in the path. That is intentional. The environment variable now points to a user directory (usually ~/go on Linux and macOS, %USERPROFILE%\go on Windows). The pkg/mod subdirectory holds every downloaded module version, indexed by path and version. The bin subdirectory holds compiled tools. The rest of the old workspace structure is ignored.
Run go env GOMODCACHE to see the exact cache path. Run go env GOPATH to see the base directory. The toolchain sets sensible defaults. You rarely need to override them.
Modules are self-contained. The cache is shared. The lockfile is strict.
A realistic project layout
Real projects rarely consist of a single file. They have multiple packages, third-party dependencies, and sometimes internal libraries. Here is how a typical module looks when it matures.
// cmd/server/main.go
package main
import (
"log"
"net/http"
"example.com/myproject/internal/handler"
)
func main() {
http.HandleFunc("/health", handler.HealthCheck) // route to internal package
log.Println("listening on :8080")
http.ListenAndServe(":8080", nil) // starts the standard HTTP server
}
// internal/handler/handler.go
package handler
import (
"net/http"
"github.com/gorilla/mux" // third-party router dependency
)
func HealthCheck(w http.ResponseWriter, r *http.Request) {
w.WriteHeader(http.StatusOK)
w.Write([]byte("ok"))
}
The internal directory is a Go convention. Packages inside internal can only be imported by code within the same module. This prevents accidental leakage of implementation details. The github.com/gorilla/mux import triggers the module proxy fetch if it is not already cached. The go.mod file records it. The go.sum file records its hash.
Run go mod tidy after adding or removing imports. The command scans your source tree, adds missing requirements, removes unused ones, and updates the lockfile. It is the standard way to keep the manifest synchronized with your actual code. Most teams run it before committing. The community accepts the extra step because it eliminates drift between what you import and what you declare.
The module proxy is another quiet piece of infrastructure. By default, GOPROXY points to proxy.golang.org. The proxy caches every public module, verifies cryptographic signatures, and serves them over HTTPS. If your network blocks the proxy, you can set GOPROXY=direct to fetch from version control systems, or point it to a corporate mirror. The proxy is not mandatory, but it makes builds faster and more reproducible.
Modules isolate your project. The proxy standardizes distribution. The tidy command keeps them honest.
Common traps and compiler signals
The transition from GOPATH to modules left a few landmines. Most of them trigger clear compiler or toolchain messages.
If you run go build inside a directory that lacks a go.mod file and you are not inside a workspace, the toolchain falls back to legacy behavior or rejects the command with go: cannot find main module. The fix is go mod init <module-path>. The module path should match your import path, usually a domain you control or a GitHub repository.
If you accidentally leave GO111MODULE=off in your environment, the toolchain ignores go.mod entirely and reverts to the old workspace layout. You will see go: GO111MODULE=off warnings or missing dependency errors. Remove the variable. It has been deprecated for years. Modern Go ignores it unless you explicitly set it.
If you mix go get and go install, you will confuse yourself. go get is for adding dependencies to your module. go install is for compiling and placing executable tools into $GOPATH/bin. The toolchain enforces this split. Running go get github.com/segmentio/golines in a module adds it as a dependency. Running go install github.com/segmentio/golines@latest compiles the binary and drops it in your bin directory. Use the right command for the right job.
If you commit a vendor directory alongside modules, you are duplicating work. Modules do not require vendoring. The cache handles distribution. Vendoring is only useful when you need to ship a fully self-contained archive for air-gapped environments or strict compliance pipelines. The default is to leave vendor out of version control.
The compiler will also complain with missing go.sum entry for module providing package if you delete go.sum or run go mod edit -dropsum. The lockfile is mandatory for reproducible builds. Restore it with go mod tidy.
Modules are strict by design. The toolchain tells you exactly what is missing. Follow the message.
When to touch GOPATH and when to leave it alone
The environment variable still exists. It serves a narrow set of purposes. You do not need to configure it for everyday development.
Use Go Modules when you are writing new code, adding dependencies, or sharing a project with others. The manifest and lockfile guarantee reproducibility. The proxy handles distribution. The cache keeps your disk organized.
Use go install with the default $GOPATH/bin when you want to add CLI tools to your system path. The toolchain places compiled binaries there automatically. Add $GOPATH/bin to your shell PATH once, and every go install command becomes instantly available.
Use GOPATH only when you are maintaining legacy code that explicitly relies on the pre-module workspace structure. Some older tutorials and internal monorepos still expect the old layout. Set the variable, run the build, and plan a migration. The toolchain supports go mod init on old projects to ease the transition.
Use Go Workspaces when you are developing multiple related modules simultaneously. A go.work file at the root overrides the proxy and cache for local development, letting you import sibling modules without publishing them first. Workspaces are a modern extension of the old workspace idea, but they stay local and explicit.
Use the default settings when you are starting a new project. The toolchain ships with sensible defaults. Override them only when your network, compliance, or toolchain requirements demand it.
GOPATH is a directory. Modules are a system. Let the system do the work.