A module, go.mod and module paths

A module is a folder tree with a go.mod file at its root. The file names the module, fixes the language version and lists the modules this one depends on, with their versions. Every Go project that is more than one file is a module, and the module is what the toolchain builds.

Create a module

go mod init writes the file and nothing else: no folder tree, no template, no dependency. The argument is the module path, the name other modules will use to import this one. A name like example.com/hello is a domain the author controls plus a path; a name with no domain works locally but cannot be fetched by anyone else.

go mod init example.com/demo
cat go.mod
go mod init example.com/demo

go: creating new go.mod: module example.com/demo
go: to add module requirements and sums:
go mod tidy
module example.com/demo

go 1.26.10
go: /tmp/gengo/runs/005/init/go.mod already exists

The second go mod init fails on purpose: the file already exists, and the command will not overwrite the name of a module that other code may already import. The go line is the language version, and it is what the compiler enforces when a newer feature appears in an older module.

The module path and its packages

Inside the module, every folder is a package, and its import path is the module path plus the folder. The tree below has one extra package, greet, in a folder of the same name: its import path is example.com/hello/greet, and that is the string main.go imports.

hello/
    go.mod
    main.go
    greet/greet.go

The package greet declares its own name in its first line, and it need not match the folder name; by convention it does. Hello is exported because it starts with a capital letter, which is the whole of Go's visibility rule.

package greet import "fmt" // Hello returns a greeting for the given name. func Hello(name string) string { return fmt.Sprintf("hello, %s", name) }

The program imports the package by its full path and calls the exported function. The go run . command builds the package of the current folder, which is main; go run . with the dot, not a file name, is what makes the module's import paths resolve.

package main import ( "fmt" "example.com/hello/greet" ) func main() { fmt.Println(greet.Hello("Go")) fmt.Println(greet.Hello("world")) }

go list -m
go run .

example.com/hello
hello, Go
hello, world

Dependencies and go.sum

A module that imports another project's package names the requirement in go.mod and the checksum of the downloaded files in go.sum. go get adds a requirement, go mod tidy removes the ones no code imports and adds the ones it does, and go mod download fills the module cache without building. Two files, both committed, and a build that never resolves a version at random: the lesson on versions reads them in full.

The program below imports only the standard library, so its go.mod has no requirements and there is no go.sum. That is the state of a new project, and a good state to keep: every requirement is a maintenance promise.

package main import ( "fmt" "runtime/debug" ) func main() { info, ok := debug.ReadBuildInfo() if !ok { fmt.Println("no build information") return } fmt.Println("module:", info.Main.Path) fmt.Println("dependencies:", len(info.Deps)) }

go list -m
ls
go run .

example.com/list
go.mod
main.go
module: example.com/list
dependencies: 0

Exercises

  1. Create a module named after a domain you control, add a package in a subfolder and import it from main. Which command would fail if the module path were misspelled?
  2. Run go mod tidy after deleting the import of the local package. What changes in go.mod, and what does the build say?
  3. Change the go line of a module to an older version and build code that uses a newer language feature. What is the error, and where is the file it names?

Questions

A new set of questions in a new order every time. Choose one answer for each, then check.

  1. What file makes a folder tree a Go module?

    Answer

    go.mod at its root

    go.mod declares the module path, the language version and the requirements.

  2. What does go mod init example.com/hello write?

    Answer

    A go.mod naming the module and a language version

    The command writes the module file only; the code and the dependencies come later.

  3. What is the import path of the package in the folder greet of the module example.com/hello?

    Answer

    example.com/hello/greet

    An import path is the module path plus the folder path inside the module.

  4. What does go run . build?

    Answer

    The package of the current folder

    The dot names the package of the current folder; ./... names all of them.

  5. What does go mod init answer when go.mod already exists?

    Answer

    go: go.mod already exists

    The command refuses to overwrite the module path, because other code may import it.

  6. What does go mod tidy do?

    Answer

    It adds the requirements the code imports and removes the unused ones

    tidy reconciles go.mod and go.sum with the imports of the code.

  7. What does this program print? package main import ( "fmt" "path" ) func main() { fmt.Println(path.Base("example.com/hello/greet")) }

    Answer

    greet

    path.Base returns the last element of a slash-separated path.

  8. Why is the capital letter of Hello important?

    Answer

    It exports the name to other packages

    In Go, an identifier that starts with a capital letter is exported; everything else is package private.

  9. Which file records the checksums of the downloaded modules?

    Answer

    go.sum

    go.sum holds the hashes the toolchain verifies before it uses a module.

  10. What does go list -m print in a module?

    Answer

    The module path of the current module

    go list -m prints module information, and with no argument the current module.

The code on this page was run with go 1.26.10 on Alpine Linux 3.24.3 (x86_64) in a Docker container.

Article author: Arthur Isaev