3. Modules

Go programs are organized into packages. A package is a directory of Go code that's all compiled together. Functions, types, variables, and constants defined in one source file are visible to all other source files within the same package (directory).

A repository contains one or more modules. A module is a collection of Go packages that are released together.

Go modules illustration

One Module Per Repo (Usually)

A file named go.mod at the root of a project declares the module. It contains:

• The module path

• The version of the Go language your project requires

• Optionally, any external package dependencies your project has

The module path is just the import path prefix for all packages within the module. Here's an example of a go.mod file:

go.mod

module github.com/bootdotdev/exampleproject

go 1.25.1

require github.com/google/examplepackage v1.3.0

Each module's path not only serves as an import path prefix for the packages within but also indicates where the go command should look to download it. For example, to download the module golang.org/x/tools, the go command would consult the repository located at https://golang.org/x/tools.

An "import path" is a string used to import a package. A package's import path is its module path joined with its subdirectory within the module. For example, the module github.com/google/go-cmp contains a package in the directory cmp/. That package's import path is github.com/google/go-cmp/cmp. Packages in the standard library do not have a module path prefix.

-- Paraphrased from Golang.org's code organization (https://golang.org/doc/code#Organization)

Only GitHub?

You don't need to publish your code to a remote repository before you can build it. A module can be defined locally without belonging to a remote repository. However, it's a good habit to keep a copy of all your projects on some remote server, like GitHub.

Package vs Module vs Repository

Repository (GitHub repo)
└── Module (go.mod file)
    └── Package 1 (directory with .go files)
    └── Package 2 (directory with .go files)
    └── Package 3 (directory with .go files)

Package

• A directory of Go code

• All .go files in the same directory = same package

• Files in the same package can see each other's functions, types, variables

Module

• A collection of packages released together

• Defined by a go.mod file at the root

• Usually one module per repository

Repository

• The GitHub/GitLab repo

• Contains one or more modules (usually just one)

The go.mod File

Located at the root of your project:

go.mod

module github.com/bootdotdev/exampleproject

go 1.25.1

require github.com/google/examplepackage v1.3.0

What's in it:

1

Module path

github.com/bootdotdev/exampleproject

2

Go version

go 1.25.1

3

Dependencies

require github.com/google/examplepackage v1.3.0

Module Path

The module path serves two purposes:

1

Import path prefix

Used as the import path prefix for all packages in the module.

2

Download location

Tells the go command where to look to download the module.

Example:

module github.com/myname/myproject

Tells Go to look at https://github.com/myname/myproject to download this module.

Package Import Paths

Formula:

Import Path = Module Path + Subdirectory

Example structure:

github.com/google/go-cmp/          (module path)
├── go.mod
└── cmp/                           (subdirectory)
    └── compare.go

Import path:

example.go

import "github.com/google/go-cmp/cmp"
        └────────┬────────────┘ └┬┘
          module path        subdirectory

Same Package = Can See Everything

All files in the same package (directory) can access each other's code:

myproject/
├── main.go
└── helpers.go

helpers.go:

helpers.go

package main

func helperFunction() {
    // ...
}

main.go:

main.go

package main

func main() {
    helperFunction()  // Can access directly, same package!
}

Standard Library Exception

Standard library packages don't have a module path prefix:

import "fmt"           // Not github.com/golang/fmt
import "strings"       // Not github.com/golang/strings
import "net/http"      // Not github.com/golang/net/http

Example Project Structure

github.com/myname/bankapp/
├── go.mod                          (module definition)
├── main.go                         (package main)
├── customer/                       (package customer)
│   ├── customer.go
│   └── account.go
└── transaction/                    (package transaction)
    └── transaction.go

go.mod:

go.mod

module github.com/myname/bankapp

go 1.25.1

Importing packages:

main.go

package main

import (
    "github.com/myname/bankapp/customer"
    "github.com/myname/bankapp/transaction"
)

func main() {
    c := customer.New("Alice")
    t := transaction.New(100.0)
}

Local vs Remote

You don't need GitHub to build:

go.mod (local)

module myapp

go 1.25.1

This works locally, but can't be downloaded by others.

But it's good practice to use a full path:

go.mod (recommended)

module github.com/myname/myapp

go 1.25.1

Even if not published yet, this prepares for future publishing.

Key Takeaways

• Package = directory of .go files compiled together

• Module = collection of packages, defined by go.mod

• One module per repo is the standard

• Module path = import prefix + download location

• Same package = all code visible to each other

• go.mod declares module path, Go version, dependencies

Visual Summary

Repository: github.com/user/project
│
├── go.mod  ← Defines module "github.com/user/project"
│
├── package1/
│   ├── file1.go  ← package package1
│   └── file2.go  ← package package1 (can see file1.go)
│
└── package2/
    └── file3.go  ← package package2
    
Import package1: "github.com/user/project/package1"
Import package2: "github.com/user/project/package2"