Skip to main content
Go modules are the standard way to manage dependencies in Go. A module is a collection of related Go packages versioned together as a single unit.

​
Overview

Introduced in Go 1.11, modules provide:
  • Version management - Explicit dependency versions
  • Reproducible builds - Lock files ensure consistency
  • Decentralized - No central repository required
  • Semantic versioning - v1.2.3 version scheme
Modules are enabled by default in Go 1.16+. The GO111MODULE environment variable is no longer needed for most cases.

​
Creating a Module

1

Initialize Module

Create a new module in your project directory:
go mod init example.com/myapp
This creates a go.mod file:
module example.com/myapp

go 1.21
2

Add Dependencies

Import packages in your code:
import "github.com/gorilla/mux"
Then run:
go mod tidy
This updates go.mod and creates go.sum.
3

Build or Test

go build
go test ./...
Dependencies are automatically downloaded.

​
The go.mod File

The go.mod file defines the module and its dependencies:
go.mod
module example.com/myapp

go 1.21

require (
    github.com/gorilla/mux v1.8.0
    golang.org/x/sync v0.3.0
)

require (
    github.com/stretchr/testify v1.8.4 // indirect
)

replace github.com/old/package => github.com/new/package v1.0.0

exclude github.com/broken/package v1.2.3

​
Directives

Declares the module path:
module example.com/myapp
Specifies the Go version:
go 1.21
Lists dependencies:
require (
    github.com/pkg/errors v0.9.1
    golang.org/x/sync v0.3.0 // indirect
)
// indirect means the dependency is not directly imported.
Replaces a module version or path:
// Replace with local version
replace example.com/old => ./local/path

// Replace with different module
replace example.com/old => example.com/new v1.0.0

// Replace specific version
replace example.com/pkg v1.0.0 => example.com/pkg v1.1.0
Excludes specific versions:
exclude github.com/broken/pkg v1.2.3
Marks versions as retracted:
// Published accidentally
retract v1.0.0

// Range of versions
retract [v1.0.0, v1.2.0]

​
Module Commands

​
go mod init

Initialize a new module: 
# With module path
go mod init example.com/myapp

# Infer from VCS (if in Git repo)
go mod init

# Using current directory name
go mod init

​
go mod tidy

Add missing and remove unused dependencies: 
go mod tidy

# Verbose output
go mod tidy -v

# Specify Go version
go mod tidy -go=1.21
Run go mod tidy regularly to keep dependencies clean and up-to-date.

​
go mod download

Download modules to local cache: 
# Download all dependencies
go mod download

# Download specific module
go mod download github.com/gorilla/[email protected]

# Output JSON
go mod download -json

​
go mod verify

Verify dependencies haven’t been modified: 
go mod verify
Outputs: 
all modules verified

​
go mod graph

Print module dependency graph: 
go mod graph

# Example output:
example.com/myapp github.com/gorilla/[email protected]
example.com/myapp golang.org/x/[email protected]

​
go mod why

Explain why packages or modules are needed: 
# Why is this package needed?
go mod why github.com/pkg/errors

# Why is this module needed?
go mod why -m github.com/gorilla/mux

# Check multiple packages
go mod why github.com/pkg1 github.com/pkg2

​
go mod edit

Edit go.mod programmatically: 
# Add requirement
go mod edit -require=github.com/pkg/[email protected]

# Drop requirement
go mod edit -droprequire=github.com/pkg/errors

​
go mod vendor

Create vendor directory: 
# Create vendor directory
go mod vendor

# Verbose output
go mod vendor -v

# Build using vendor
go build -mod=vendor

​
Adding and Upgrading Dependencies

​
Adding Dependencies

1

Import Package

Add import to your code:
import "github.com/gorilla/mux"
2

Run go mod tidy

go mod tidy
This automatically adds the dependency to go.mod.
Or use go get: 
# Add latest version
go get github.com/gorilla/mux

# Add specific version
go get github.com/gorilla/[email protected]

# Add latest patch release
go get github.com/gorilla/[email protected]

​
Upgrading Dependencies

# Upgrade to latest
go get -u github.com/gorilla/mux

# Upgrade to specific version
go get github.com/gorilla/[email protected]

# Upgrade to latest patch
go get -u=patch github.com/gorilla/mux

​
Removing Dependencies

# Remove from go.mod (if not used)
go mod tidy

# Remove specific dependency
go get example.com/pkg@none

​
Version Selection

​
Version Queries

# Latest version
go get example.com/pkg@latest

# Specific version
go get example.com/[email protected]

# Version prefix
go get example.com/[email protected]

# Commit hash
go get example.com/pkg@abc123

# Branch
go get example.com/pkg@master
go get example.com/pkg@main

# Upgrade (latest with same major version)
go get -u example.com/pkg

# Upgrade to latest patch
go get -u=patch example.com/pkg

# Remove dependency
go get example.com/pkg@none

​
Listing Versions

# List available versions
go list -m -versions github.com/gorilla/mux

# Show current version
go list -m github.com/gorilla/mux

# Show all dependencies
go list -m all

# Show as JSON
go list -m -json all

​
Semantic Versioning

Go modules use semantic versioning: 
v1.2.3
│ │ └─ Patch: Bug fixes
│ └─── Minor: New features (backward compatible)
└───── Major: Breaking changes

​
Major Versions

module example.com/myapp

require example.com/pkg v1.5.0

import "example.com/pkg"

module example.com/myapp/v2

require example.com/pkg/v2 v2.1.0

import "example.com/pkg/v2"

​
Version Compatibility

// Can use v1.2.0, v1.2.1, v1.3.0, etc.
require example.com/pkg v1.2.0

// Cannot automatically upgrade to v2.0.0
// Must explicitly import v2:
import "example.com/pkg/v2"

​
Module Cache

​
Cache Location

# View cache directory
go env GOMODCACHE

# Default: $GOPATH/pkg/mod

​
Cache Management

# Clear module cache
go clean -modcache

# Download without installing
go mod download

# Verify cache integrity
go mod verify

​
Private Modules

​
Configuring Private Repositories

1

Set GOPRIVATE

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

# Multiple patterns
go env -w GOPRIVATE=github.com/mycompany/*,gitlab.com/myorg/*
2

Configure Git

# Use SSH instead of HTTPS
git config --global url."[email protected]:".insteadOf "https://github.com/"
3

Set Credentials (if needed)

# Using .netrc
cat >> ~/.netrc << EOF
machine github.com
    login $USERNAME
    password $TOKEN
EOF

​
Environment Variables

  • GOPRIVATE - Skip proxy and checksum database
  • GONOPROXY - Skip proxy (but not checksum)
  • GONOSUMDB - Skip checksum database
# Set multiple
go env -w GOPRIVATE=github.com/company1/*,github.com/company2/*
go env -w GONOPROXY=github.com/company1/*
go env -w GONOSUMDB=github.com/company1/*

​
Working with Replacements

​
Local Development

# Replace with local directory
go mod edit -replace=example.com/pkg=../pkg
go.mod
replace example.com/pkg => ../pkg

​
Forked Repositories

# Replace with fork
go mod edit -replace=original/pkg=github.com/myuser/[email protected]
go.mod
replace original/pkg => github.com/myuser/pkg v1.2.3

​
Best Practices

Run go mod tidy Regularly

Keep dependencies clean and minimal

Commit go.sum

Ensures reproducible builds

Use Semantic Versioning

Follow semver for your modules

Pin Dependencies

Use specific versions in production

​
Vendoring

Consider vendoring for:
  • Offline builds
  • Guaranteed availability
  • Build reproducibility
# Create vendor directory
go mod vendor

# Verify vendor is in sync
go mod vendor -v

# Build with vendor
go build -mod=vendor

​
Troubleshooting

# Update module cache
go get -u example.com/pkg

# Clear cache and retry
go clean -modcache
go mod download

# See dependency tree
go mod graph

# Find why package is needed
go mod why -m example.com/pkg

# Force specific version
go get example.com/[email protected]

# Verify checksums
go mod verify

# Regenerate go.sum
rm go.sum
go mod tidy

​
See Also

go Command

Overview of go command

Workspaces

Multi-module development

Building

Building Go programs

Build docs developers (and LLMs) love

Get started for freeTalk to us