Modules and Dependencies
What you will learn
Real programs are never one file. In this lesson you will learn how Go organises code into packages and modules, how to split your own program into pieces, and how to add a library written by someone else. You will also learn what go.mod and go.sum are for and which commands keep them correct.
Package, module, repository
Three words get mixed up, so fix them first.
| Term | What it is | Example |
|---|---|---|
| Package | A folder of .go files compiled together. Each file starts with package name. | fmt |
| Module | A project: one or more packages versioned together, described by a go.mod file. | example.com/hello-go |
| Repository | A place in version control (such as a Git repo). It usually holds one module. | a GitHub repo |
An analogy: a module is a book, a package is a chapter, and a repository is the shelf the book is stored on. In a small project all three overlap, which is why they feel like the same thing.
Split your own code into packages
Start with the module from the last lesson, or make a new one:
mkdir tasker
cd tasker
go mod init example.com/tasker
Create this layout:
tasker/
├── go.mod
├── main.go
└── greeting/
└── greeting.go
The new package lives in its own folder:
package greeting
func Hello(name string) string {
return "Hello, " + name + "!"
}
Two things to notice. The file says package greeting, matching its folder name. And Hello starts with a capital letter, which makes it exported: visible to other packages. A function named hello would be private to this package.
Now use it from main.go:
package main
import (
"fmt"
"example.com/tasker/greeting"
)
func main() {
fmt.Println(greeting.Hello("Gopher"))
}
Run it:
go run .
Hello, Gopher!
The import path is the module path plus the folder path: example.com/tasker + /greeting. Inside the code you refer to the package by its short name, greeting. The standard library follows the same idea. fmt is just a package with a short path.
Hello, the compiler says undefined: greeting.hello or "refers to unexported name". Exported or not is decided by that first letter alone.Add a third-party dependency
Libraries from other people are modules too. Let's use github.com/google/uuid, a small and widely used library for generating unique IDs. Change main.go:
package main
import (
"fmt"
"github.com/google/uuid"
"example.com/tasker/greeting"
)
func main() {
fmt.Println(greeting.Hello("Gopher"))
fmt.Println("Your ID:", uuid.NewString())
}
If you run it now, Go complains that the package is missing. Fix that with:
go mod tidy
go mod tidy reads your imports, downloads whatever is missing, and updates go.mod and go.sum. Run go run . and you get your greeting plus a random ID. Then look at go.mod:
module example.com/tasker
go 1.26
require github.com/google/uuid v1.6.0
The new require line says your module depends on uuid at version v1.6.0. Anyone who clones your project gets exactly that version.
What go.sum does
A second file, go.sum, appeared. Each line looks like this:
github.com/google/uuid v1.6.0 h1:...
github.com/google/uuid v1.6.0/go.mod h1:...
The h1: values are cryptographic hashes of the downloaded code. Go checks them every time it downloads a module, so if someone changed the library after you first used it, you find out instead of silently running different code.
Three rules for go.sum:
- Commit it to version control, along with
go.mod. - Never edit it by hand.
- Never delete it to "fix" an error. Run
go mod tidyinstead and let Go regenerate it.
Choose a version
go mod tidy picks a suitable version for you, but you can ask for a specific one:
go get github.com/google/uuid@v1.6.0
To see which of your dependencies have newer releases:
go list -m -u all
To upgrade one dependency to its latest release:
go get github.com/google/uuid@latest
After any upgrade, run your tests and look at what changed in go.mod and go.sum. A dependency update is a code change, not background noise, because the new version may behave differently.
Remove a dependency
Delete the uuid import and the line that uses it from main.go, then run:
go mod tidy
Go notices that nothing imports uuid any more and removes it from go.mod. This is the second half of why go mod tidy is so useful: it adds what you need and removes what you do not.
Common mistakes
- Folder and package name do not match. The package in
greeting/should bepackage greeting. A mismatch works but confuses everyone reading it. - Forgetting the capital letter on a function you want to use from another package.
- Using the wrong import path. It must start with the
moduleline fromgo.mod, not just the folder name. - Running
go getand not reading the diff. One upgrade can pull in changes to other modules. - Deleting
go.sumto fix an error. This throws away your protection. Usego mod tidyinstead. - Using a made-up module path for a library others will install. If it will be published, the path must match a real address, like
github.com/yourname/tasker.
Practice
- Create a module named
example.com/calcwith a packagecalcin its own folder. Add an exported functionAdd(a, b int) int. - Call it from
main.goand print the result ofAdd(2, 3). - Add
github.com/google/uuid, print one ID, then remove the dependency again. Check howgo.modchanges each time.
mkdir calc
cd calc
go mod init example.com/calc
mkdir calc
package calc
func Add(a, b int) int {
return a + b
}
package main
import (
"fmt"
"example.com/calc/calc"
)
func main() {
fmt.Println(calc.Add(2, 3))
}
go run . prints 5. The import path is example.com/calc (the module) plus /calc (the folder). Both happen to be called calc, which is a common source of confusion; you could name the folder mathutil and package mathutil to see the difference.
To add the dependency, import github.com/google/uuid, call uuid.NewString(), and run go mod tidy. go.mod gains require github.com/google/uuid v1.6.0 and go.sum appears. To remove it, delete the import and the call, then run go mod tidy again. The require line disappears from go.mod.
Summary
A package is a folder of Go files, a module is a project described by go.mod, and a repository is where the code is stored. Import paths combine the module path and the package folder, and a capital first letter exports a name. Use go mod tidy to add missing dependencies and remove unused ones, and go get to choose versions. go.sum verifies downloads, so commit it and never edit it. Treat every dependency update as a code change you review.
Replacing modules, workspaces, major versions, and vulnerability scanning come later, in Advanced Modules.
Official references: Managing dependencies and the Go Modules Reference.
Ready to wrap up?
Mark this complete when you can explain the main idea and finish the practice task.