Advanced Modules
What you will learn
The beginner lesson covered go.mod, go.sum, go mod tidy, and go get. This lesson covers what you need once projects grow: how Go handles major versions, how to work on several modules at once, how to hide packages, and how to update dependencies without surprises.
Direct and indirect requirements
Open a go.mod that has a few dependencies:
require (
example.com/direct v1.2.0
example.com/transitive v0.9.1 // indirect
)
A direct requirement provides a package your own code imports. An indirect requirement is a dependency of a dependency that Go needs to record for the build. The // indirect comment is added by go mod tidy, not by you.
Minimum version selection
If your project needs A v1.2.0 and another dependency needs A v1.4.0, Go picks v1.4.0: the highest of the minimum versions requested anywhere in the graph. It does not jump to the newest release available. This makes builds predictable, because adding a dependency never silently upgrades unrelated ones.
It also explains why go get can change several lines in go.mod. Raising one module can raise others it requires, so always review the diff.
Major versions
Go uses semantic import versioning. From version 2 onward, the major version is part of the module path:
module example.com/toolkit/v2
Callers import example.com/toolkit/v2/parser. Because v1 and v2 have different paths, both can exist in the same build, which lets you migrate gradually. Versions v0 and v1 do not add a suffix.
Internal packages
A package inside a folder named internal can only be imported by code rooted at that folder's parent:
tasker/
├── go.mod
├── cmd/tasker/main.go
└── internal/task/task.go
cmd/tasker/main.go can import example.com/learner/tasker/internal/task. Code in a different module cannot, and the toolchain rejects the import. Use internal for code you do not want to promise as a public API.
Local development with replace
A replace directive points a module path at a folder on your machine:
replace example.com/shared => ../shared
This is useful while fixing a library and testing it in an app at the same time. It is dangerous to publish: other people do not have ../shared. Remove it before you release, or use a workspace instead.
Workspaces
For coordinated work across several local modules, a workspace is cleaner than editing go.mod:
go work init ./service ./shared
This creates a go.work file that tells Go to use the local copies of both modules. Your go.mod files stay untouched. Decide deliberately whether to commit go.work. Many teams keep it out of version control because it describes one person's local layout.
Vendoring
go mod vendor copies all dependencies into a vendor/ folder in your project. It is an explicit workflow for builds that must work offline or for strict review policies. Most projects do not need it, and it never happens automatically.
A safe update workflow
- Read the release notes and any migration guide.
- Update one logical group of modules at a time.
- Run
go fmt ./...,go vet ./..., andgo test ./.... Add-racewhere concurrency is involved. - Review the
go.modandgo.sumdiff. - Scan for known vulnerabilities with
govulncheck, which reports only vulnerabilities in code your program actually reaches. - Commit with a message that explains why, so a future maintainer can revert safely.
go install golang.org/x/vuln/cmd/govulncheck@latest
govulncheck ./...
Common mistakes
- Committing a
replacethat points at a local path. Everyone else's build breaks. - Importing
/v2code without the/v2suffix. You will silently get the old major version. - Importing an
internalpackage from outside its allowed tree. The toolchain rejects it by design. - Assuming
vendor/is used automatically. It is an explicit choice.
Practice
Create two modules, app and shared, in sibling folders. Make app import a function from shared, and run it without publishing shared anywhere. Use a workspace.
mkdir workspace && cd workspace
mkdir app shared
(cd shared && go mod init example.com/shared)
(cd app && go mod init example.com/app)
package shared
func Greet() string { return "hello from shared" }
package main
import (
"fmt"
"example.com/shared"
)
func main() { fmt.Println(shared.Greet()) }
go work init ./app ./shared
cd app && go run .
The workspace makes Go use the local shared folder for the example.com/shared import, so no replace directive and no published module is needed. Neither go.mod file was changed.
Summary
Direct requirements come from your imports, while indirect ones are dependencies of dependencies. Minimum version selection picks the highest minimum version requested in the graph. From v2 onward the major version is part of the import path. Use internal to hide packages, go.work for local multi-module work, and avoid committing replace paths. Update dependencies one group at a time, verify with tests, and scan with govulncheck.
Official references: Go Modules Reference and Tutorial: Getting started with multi-module workspaces.
Ready to wrap up?
Mark this complete when you can explain the main idea and finish the practice task.