ZetCode

Go module

last modified October 30, 2026

In this article we show how to work with modules in Go. A module is a collection of packages stored in a file tree, with a go.mod file at its root. The module path in that file is the prefix that every package of the module uses in its import path.

Modules replace the old GOPATH layout: dependencies are versioned, recorded in go.mod, verified through go.sum and downloaded into a shared cache instead of a single workspace directory.

All commands in this article were run with Go 1.27.0 on Linux.

What a module contains

Two files describe a module. go.mod holds the module path, the Go version and the requirements; go.sum holds the checksums of the downloaded modules and is maintained by the toolchain, not by hand.

$ cat go.mod
module com.zetcode/first

go 1.27.0

require gonum.org/v1/gonum v0.17.0

The go line records the language version the module was checked with. When a module requires another module, the requirement is listed here, either directly or with an // indirect comment.

Creating a module with go mod init

go mod init creates go.mod in the current directory. The argument is the module path, usually the repository URL or a private namespace.

$ mkdir first && cd first
$ go mod init com.zetcode/first
go: creating new go.mod: module com.zetcode/first

$ cat go.mod
module com.zetcode/first

go 1.27.0

The command refuses to run when a go.mod already exists. In a directory that already contains Go files it also prints a hint that go mod tidy should be run to add the missing requirements.

Adding a dependency with go get

go get resolves a package or a module, downloads it and records the requirement in go.mod. The Gonum library is a set of numeric packages that is distributed as a single module.

$ go get gonum.org/v1/gonum/stat
go: downloading gonum.org/v1/gonum v0.17.0
go: added gonum.org/v1/gonum v0.17.0

$ cat go.mod
module com.zetcode/first

go 1.27.0

require gonum.org/v1/gonum v0.17.0 // indirect

$ ls
go.mod  go.sum

The // indirect marker appears because no file in the module imports the package yet. The requirement is present, but the toolchain does not know whether the program really needs it.

Using the dependency and running go mod tidy

After a file imports the package, go mod tidy recomputes the requirements from the imports: it drops what is unused and marks what is used directly.

first.go
package main

import (
    "fmt"
    "math"

    "gonum.org/v1/gonum/stat"
)

func main() {

    xs := []float64{12.44, 11.2, 34.5, 1.4, 6.7, 23.4}

    mean := stat.Mean(xs, nil)
    variance := stat.Variance(xs, nil)
    stddev := math.Sqrt(variance)

    fmt.Printf("mean: %.2f\n", mean)
    fmt.Printf("variance: %.2f\n", variance)
    fmt.Printf("std-dev: %.2f\n", stddev)
}

The stat package computes the mean and the variance, and math.Sqrt turns the variance into the standard deviation. The formatting with two decimals keeps the output readable.

$ go run first.go
mean: 14.94
variance: 145.13
std-dev: 12.05

Running the tidy command afterwards removes the indirect marker, because the package is now imported by the main package.

$ go mod tidy
$ cat go.mod
module com.zetcode/first

go 1.27.0

require gonum.org/v1/gonum v0.17.0

go.sum and the module cache

While go.mod records which versions are required, go.sum records their content hashes. Every download is verified against these hashes, so a replaced or tampered module is rejected at build time.

$ wc -l go.sum
2 go.sum

$ go mod verify
all modules verified

The two lines in go.sum are the hashes of the module file and of the whole module zip. Sources are unpacked into $GOMODCACHE, which defaults to the pkg/mod subdirectory of the Go path.

$ go env GOMODCACHE
/home/user/go/pkg/mod

$ ls $(go env GOMODCACHE)/gonum.org/v1/
gonum@v0.17.0

$ ls $(go env GOMODCACHE)/cache/download/gonum.org/v1/gonum/@v/
list
v0.15.0.info
v0.17.0.info
v0.17.0.lock
v0.17.0.mod
v0.17.0.zip

The cache/download directory keeps the original archives and their metadata; the unpacked copies next to it are what the compiler reads. Both are safe to delete, and both are restored on the next build.

Inspecting the module graph

Three commands answer the usual questions: which modules take part in the build, why a module is needed, and how the requirements depend on each other.

$ go list -m all
com.zetcode/first
codeberg.org/go-fonts/liberation v0.5.0
codeberg.org/go-latex/latex v0.1.0
codeberg.org/go-pdf/fpdf v0.10.0
git.sr.ht/~sbinet/gg v0.6.0
github.com/ajstarks/svgo v0.0.0-20211024235047-1546f124cd8b
...
gonum.org/v1/tools v0.0.0-20200318103217-c168b003ce8c
rsc.io/pdf v0.1.1

The list has 20 lines; the middle is replaced by an ellipsis. Not every entry is imported by the program: Gonum requires plotting and documentation tools for its own packages and tests, and those requirements appear here as well.

$ go mod why gonum.org/v1/gonum/stat
# gonum.org/v1/gonum/stat
com.zetcode/first
gonum.org/v1/gonum/stat

go mod why prints the shortest import chain from the main module to the package. The chain here has one step, which confirms that the package is imported directly.

$ go mod graph | head -3
com.zetcode/first go@1.27.0
com.zetcode/first gonum.org/v1/gonum@v0.17.0
go@1.27.0 toolchain@go1.27.0
$ go mod graph | wc -l
22

The graph has one line per requirement edge and 22 lines in total. The truncated output shows the edges from the main module and from the go directive.

A module with several packages

Packages inside a module import each other through the module path. A new module named com.zetcode/calc with a mathx subdirectory is imported as com.zetcode/calc/mathx.

$ go mod init com.zetcode/calc
go: creating new go.mod: module com.zetcode/calc
go: to add module requirements and sums:
    go mod tidy

The second message appears because the directory already contains Go files. The module has no external requirements, so tidy has nothing to add.

mathx/mathx.go
package mathx

// Mean returns the arithmetic mean of the values.
func Mean(vals []float64) float64 {

    if len(vals) == 0 {
        return 0
    }

    var sum float64
    for _, v := range vals {
        sum += v
    }

    return sum / float64(len(vals))
}

The package name mathx matches its directory. The exported Mean function is the only element visible outside the package.

main.go
package main

import (
    "fmt"

    "com.zetcode/calc/mathx"
)

func main() {

    vals := []float64{2, 4, 6, 8}

    fmt.Printf("mean: %.1f\n", mathx.Mean(vals))
}

The import path starts with the module path, not with a repository hostname. The toolchain resolves the prefix from go.mod and looks for the remaining directory inside the module. go list ./... then enumerates the packages of the module; the ./... pattern never leaves it, so packages of dependencies cannot appear in the result.

$ go run .
mean: 5.0

$ go list ./...
com.zetcode/calc
com.zetcode/calc/mathx

Upgrading, downgrading and removing a dependency

An explicit version after the package path pins the requirement. go get reports the direction of the change, and @none removes the requirement altogether.

$ go get github.com/google/uuid@v1.6.0
go: added github.com/google/uuid v1.6.0
$ go list -m github.com/google/uuid
github.com/google/uuid v1.6.0

$ go get github.com/google/uuid@v1.5.0
go: downloading github.com/google/uuid v1.5.0
go: downgraded github.com/google/uuid v1.6.0 => v1.5.0
$ go list -m github.com/google/uuid
github.com/google/uuid v1.5.0

$ go get github.com/google/uuid@none
go: removed github.com/google/uuid v1.5.0

Removing the requirement leaves the import in the source, so the next build fails until the package is added back or the import is deleted. This is a feature: the module file always describes what the code needs, not what was downloaded at some point.

Vendoring dependencies

go mod vendor copies the packages needed for the build into a vendor directory and writes vendor/modules.txt with their versions. From then on the toolchain reads the sources from that directory.

$ go mod vendor
$ ls
first.go  go.mod  go.sum  vendor

$ head -3 vendor/modules.txt
# gonum.org/v1/gonum v0.17.0
## explicit; go 1.24.0
gonum.org/v1/gonum/blas

The first line names the module and its version, the second marks it as an explicit requirement and records the Go version of the dependency, and the remaining lines list the vendored packages.

$ go build -o first .
$ ./first
mean: 14.94
variance: 145.13
std-dev: 12.05

$ go list -m all
go: can't compute 'all' using the vendor directory
    (Use -mod=mod or -mod=readonly to bypass.)

The build succeeds without touching the network, because the sources are in vendor. The listing of modules fails, however: with a vendor directory the module graph is not loaded. Adding -mod=mod to the command restores the old behaviour, and deleting the directory with rm -rf vendor returns the module to the cache-based setup.

Replacing a module with a local directory

A replace directive redirects an import path to another location, which is how a module is tested before it is published or how two modules are developed side by side.

go.mod
module com.zetcode/app

go 1.27.0

require example.com/greeter v0.0.0

replace example.com/greeter => ./local/greeter

The replacement target must itself be a module, so local/greeter/go.mod declares module example.com/greeter. The two directives were written with go mod edit, which does not need a network connection.

The version in the require line is a placeholder; the local directory is always used, whatever the version says. Such a replace directive must be removed before the module is published, otherwise other developers get a path that does not exist on their machines.

$ go mod edit -require=example.com/greeter@v0.0.0
$ go mod edit -replace=example.com/greeter=./local/greeter
$ go run .
hello John

Module paths with a major version

A module that reaches version 2 or later must add the major version to its module path. The suffix is part of the import path, so the compiler can use versions 1 and 2 of the same library in one program.

module example.com/mylib/v2

go 1.27.0

The corresponding release is tagged v2.0.0 in the repository, and imports use example.com/mylib/v2. Without the suffix the toolchain rejects the release: go get example.com/mylib@v2.0.0 reports that the module contains a go.mod file, so the module path must match the major version. The +incompatible form exists only for old repositories without a go.mod.

Source

Go modules reference

In this article we have created modules, added and removed dependencies, inspected the module graph, vendored the sources, replaced a module with a local directory and explained the major version suffix in module paths.

Author

I am Jan Bodnar, a programmer and technical writer. I have been writing programming tutorials at ZetCode since 2007 and have published eight e-books. See about the author.

List all Go tutorials.