Getting Started

Advanced Modules

Major versions, indirect requirements, replace, workspaces, internal packages, vendoring, and a safe dependency update workflow.

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:

go.mod
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:

go.mod
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:

go.mod
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:

Terminal
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

  1. Read the release notes and any migration guide.
  2. Update one logical group of modules at a time.
  3. Run go fmt ./..., go vet ./..., and go test ./.... Add -race where concurrency is involved.
  4. Review the go.mod and go.sum diff.
  5. Scan for known vulnerabilities with govulncheck, which reports only vulnerabilities in code your program actually reaches.
  6. Commit with a message that explains why, so a future maintainer can revert safely.
Terminal
go install golang.org/x/vuln/cmd/govulncheck@latest
govulncheck ./...

Common mistakes

  • Committing a replace that points at a local path. Everyone else's build breaks.
  • Importing /v2 code without the /v2 suffix. You will silently get the old major version.
  • Importing an internal package 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.

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.

Copyright © 2026