Understanding Go Modules: The Complete Guide to Dependency Management

Managing dependencies in Go projects shouldn’t give you headaches. While older methods like GOPATH worked, Go modules make the whole process straightforward and reliable. Let’s walk through everything you need to know about using Go modules effectively.

Before we start – if you’re new to Go, check out our Getting Started with Go guide first.

Table of Contents

• What Are Go Modules?
• Starting Your First Module
  • Setting Up
• Working with Dependencies
• Handling Your Dependencies
  • See What You’re Using
  • Update Packages
  • Clean Up
• Version Control
  • Version Tips
• Private Code
  • GitHub:
  • GitLab:
• Smart Practices
  • Keep Dependencies Local
  • Version Control Rules
  • Stay on Top of Dependencies
• Fixing Common Problems
  • Can’t Find Module
  • Version Issues
• More Advanced Stuff
  • Swap Dependencies
  • Big Projects
• Wrapping Up

What Are Go Modules?

Go modules are the current standard for handling project dependencies. They let you work anywhere on your computer (not just in GOPATH) and keep track of exactly which versions of packages you’re using. Introduced in Go 1.11 and made default in Go 1.13, modules solve these common problems:

• Keep builds consistent across different machines
• Handle multiple versions of the same package
• Make projects work anywhere
• Make sharing code easier

Starting Your First Module

Let’s create a module from scratch.

Setting Up

Make a new project folder:

mkdir myproject
cd myproject

Start your module:

go mod init myproject

This creates a go.mod file that looks like:

module myproject

go 1.20
Code language: JavaScript (javascript)

Working with Dependencies

Let’s build something real. We’ll make a simple web server using the popular gorilla/mux package.

Create main.go:

package main

import (
    "fmt"
    "log"
    "net/http"
    "github.com/gorilla/mux"
)

func main() {
    r := mux.NewRouter()
    r.HandleFunc("/", HomeHandler)
    fmt.Println("Server starting on port 8080...")
    log.Fatal(http.ListenAndServe(":8080", r))
}

func HomeHandler(w http.ResponseWriter, r *http.Request) {
    fmt.Fprintf(w, "Welcome to our Go application!")
}
Code language: JavaScript (javascript)

Add the package:

go get github.com/gorilla/mux
Code language: JavaScript (javascript)

This command:

• Gets the package
• Updates go.mod
• Creates/updates go.sum with security hashes

Handling Your Dependencies

See What You’re Using

Check all dependencies:

go list -m all
Code language: PHP (php)

Update Packages

Update one package:

go get -u github.com/gorilla/mux
Code language: JavaScript (javascript)

Update everything:

go get -u ./...
Code language: JavaScript (javascript)

Clean Up

Remove unused packages:

go mod tidy

Version Control

Go modules use semantic versioning. Your go.mod might look like:

require (
    github.com/gorilla/mux v1.8.0
    github.com/example/package v1.2.3
)
Code language: JavaScript (javascript)

Version Tips

Get specific versions:

• Latest: @latest
• Exact version: @v1.2.3
• Latest commit: @master

Example:

go get github.com/gorilla/[email protected]
Code language: JavaScript (javascript)

Private Code

For private repositories, set up authentication:

GitHub:

go env -w GOPRIVATE=github.com/mycompany/*

GitLab:

go env -w GOPRIVATE=gitlab.com/mycompany/*

Smart Practices

Keep Dependencies Local

Store dependencies in your project:

go mod vendor

Version Control Rules

Always commit:

• go.mod
• go.sum

Maybe commit:

• vendor directory (if you use vendoring)

Stay on Top of Dependencies

1. Update regularly for security
2. Use go mod why to check relationships
3. Look at your dependency tree often
4. Set up automatic updates

Fixing Common Problems

Can’t Find Module

When you see “module not found”:

1. Check the module name
2. Test your internet
3. Clear the cache:

go clean -modcache

Version Issues

When versions clash:

1. Use go mod graph to see connections
2. Update problem packages
3. Try replace in go.mod

More Advanced Stuff

Swap Dependencies

Use your own version of a package:

replace github.com/original/package => github.com/myfork/package v1.0.0
Code language: JavaScript (javascript)

Big Projects

Large projects might need multiple modules:

my-project/
  ├── go.mod
  ├── module1/
  │   └── go.mod
  └── module2/
      └── go.mod

Each module manages its own dependencies.

Wrapping Up

Good dependency management keeps Go projects healthy. Go modules make this job much easier than before. Follow these guidelines, and you’ll avoid many common problems.

Keep your dependencies updated, your module files clean, and use version control wisely. These habits help build reliable applications that are easy to maintain.

Want to try this out? Start by moving an old project to modules, or make something new with these tips. For more Go learning, check out our guide on Building RESTful APIs with Go to see dependency management in real use.

Happy coding!