Getting Started

Modules and Dependencies

Understand packages and modules, split code into your own packages, and add and remove third-party libraries.

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.

TermWhat it isExample
PackageA folder of .go files compiled together. Each file starts with package name.fmt
ModuleA project: one or more packages versioned together, described by a go.mod file.example.com/hello-go
RepositoryA 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:

Terminal
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:

greeting/greeting.go
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:

main.go
package main

import (
    "fmt"

    "example.com/tasker/greeting"
)

func main() {
    fmt.Println(greeting.Hello("Gopher"))
}

Run it:

Terminal
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.

If you forget the capital letter on 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:

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:

Terminal
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:

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:

  1. Commit it to version control, along with go.mod.
  2. Never edit it by hand.
  3. Never delete it to "fix" an error. Run go mod tidy instead 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:

Terminal
go get github.com/google/uuid@v1.6.0

To see which of your dependencies have newer releases:

Terminal
go list -m -u all

To upgrade one dependency to its latest release:

Terminal
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:

Terminal
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 be package 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 module line from go.mod, not just the folder name.
  • Running go get and not reading the diff. One upgrade can pull in changes to other modules.
  • Deleting go.sum to fix an error. This throws away your protection. Use go mod tidy instead.
  • 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

  1. Create a module named example.com/calc with a package calc in its own folder. Add an exported function Add(a, b int) int.
  2. Call it from main.go and print the result of Add(2, 3).
  3. Add github.com/google/uuid, print one ID, then remove the dependency again. Check how go.mod changes each time.

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.

Copyright © 2026