iwantcoding.com
🔥 Daily 👥 Rooms 🏆 Top Log in Sign up

Go Modules

By · Reviewed & last updated · Part of Go Tutorial

Go modules are how Go projects declare their dependencies. A module is a tree of packages rooted at a `go.mod` file that names the module and pins its dependencies. `go.sum` records the checksums. Together they make Go builds reproducible across machines and CI.

go.mod + go.sum, versions, replace, and workspaces

EXAMPLE
# 1) Initialise a new module
go mod init example.com/shop
# Writes go.mod with: module example.com/shop  + go 1.22

# 2) Add a dependency — go pulls the latest semver-compatible version
go get github.com/google/uuid
go get github.com/jackc/pgx/v5@latest         # explicit @latest
go get github.com/sirupsen/logrus@v1.9.3      # pin to an exact version

# 3) Update a dependency
go get github.com/google/uuid@v1.6.0
go get -u                                      # upgrade everything (minor/patch)
go get -u=patch                                # patch-only updates

# 4) Remove unused dependencies — keep go.mod tidy
go mod tidy
# Reads every .go file, adds anything imported but missing, removes anything not imported.

# 5) Inspect the module graph
go list -m all                                 # every module the build needs
go list -m -versions github.com/google/uuid    # which versions are available
go mod why github.com/some/lib                 # why is this in the graph?
go mod graph | head -20

# 6) Vendoring (offline / hermetic builds)
go mod vendor
# Writes vendor/. CI can build from vendor/ even without network.

# 7) Replace a module — useful for local development of a dependency
# go.mod
# replace example.com/shared => ../shared
# Then go build picks the local copy. Remove before tagging a release.

# 8) Verify checksums match go.sum on every build
GOFLAGS=-mod=readonly go build ./...           # CI-friendly: fail if go.mod/.sum drift

# 9) Workspaces — develop multiple modules together without replace directives
go work init ./api ./worker ./shared
go work sync                                   # bring deps in line across all
# Creates go.work; commit it ONLY if every contributor uses the same layout.

# 10) Private modules — set GOPRIVATE so go skips the public proxy
go env -w GOPRIVATE=example.com/*,gitlab.example.com/*

# 11) Semantic Import Versioning — major versions appear in the import PATH
# v0/v1 import:  github.com/foo/bar
# v2 import:     github.com/foo/bar/v2          (NOT @v2 in path; the v2 IS the path)

# 12) Release a new version of YOUR module
git tag v1.4.0
git push origin v1.4.0
# Consumers: go get example.com/shop@v1.4.0

Why it matters

`go mod tidy` is the command every PR should pass cleanly. Run it locally before commit; have CI run it and fail if go.mod or go.sum changes. That single rule kills "works on my machine because I forgot to commit the dep update" — the dominant source of green-CI/red-prod surprises in Go projects.

Tip: Tweak the snippet with Try it Yourself », then sit the quiz at the bottom of the page.

Example

Example
# Initialize a module
go mod init github.com/me/app
# Add a dep
go get github.com/stretchr/testify@latest
Try it Yourself »

Discussion

Loading…