Go Modules — Dependency Management

Go Modules, introduced in Go 1.11, is Go's official dependency management system. It overcomes the limitations of the GOPATH approach and supports versioning and reproducible builds.

Module Initialization — go mod init

# Initialize a new module
go mod init github.com/yourname/myproject

# Local module (not going to be published)
go mod init myproject

Running go mod init creates a go.mod file.

go.mod File Structure

module github.com/yourname/myproject  ← module path

go 1.21                               ← minimum Go version

require (
    github.com/gin-gonic/gin v1.9.1   ← direct dependency
    github.com/stretchr/testify v1.8.4
)

require (
    // Indirect dependencies (required by direct dependencies)
    github.com/bytedance/sonic v1.9.1 // indirect
    github.com/gabriel-vasile/mimetype v1.4.2 // indirect
)

Key go Commands

# Add a package (automatically updates go.mod and go.sum)
go get github.com/gin-gonic/gin

# Specify a version
go get github.com/gin-gonic/gin@v1.9.1

# Upgrade to latest version
go get -u github.com/gin-gonic/gin

# Upgrade all dependencies to latest
go get -u ./...

# Remove unused dependencies + add missing ones
go mod tidy

# Copy dependencies to vendor directory
go mod vendor

# Download dependencies
go mod download

# View dependency graph
go mod graph

# Verify dependencies
go mod verify

go.sum File

go.sum stores cryptographic hashes for each module to ensure build reproducibility and security.

github.com/gin-gonic/gin v1.9.1 h1:4idEAncQnU5cB7BeOkPtxjfCSye0AAm1R0RVIqJ+Jmg=
github.com/gin-gonic/gin v1.9.1/go.mod h1:hPrL7YrpYKXt5YId3A/Tnip5kqbEAP+KLuI3SUcPTeU=

Never manually edit go.sum. It's automatically managed by go mod tidy and go get.

Version Management

Go Modules follows Semantic Versioning (SemVer).

v1.2.3
│ │ │
│ │ └── Patch version (bug fixes)
│ └──── Minor version (new features, backward compatible)
└────── Major version (breaking changes)

Major Version Upgrades (v2+)

// v2 and above include version in the import path
import "github.com/foo/bar/v2"
import "github.com/foo/bar/v3"

go get github.com/foo/bar/v2@v2.0.0

Version Specifiers

v1.9.1          Exact version
>=v1.9.0        Minimum version
latest          Latest release
@main           Main branch (not recommended)
@hash           Commit hash

Local Module References — replace Directive

Use when referencing a package you're developing locally.

// go.mod
module github.com/myorg/myapp

go 1.21

require (
    github.com/myorg/mylib v0.1.0
)

replace (
    // Replace with local path
    github.com/myorg/mylib => ../mylib

    // Replace specific version (e.g., security patch)
    github.com/vulnerable/pkg v1.0.0 => github.com/safe/pkg v1.0.1
)

Real-World Example — Project Setup

# 1. Initialize project
mkdir mywebapp && cd mywebapp
go mod init github.com/yourname/mywebapp

# 2. Add dependencies
go get github.com/gin-gonic/gin@v1.9.1
go get github.com/stretchr/testify@v1.8.4

# 3. Write code

// main.go
package main

import (
    "net/http"

    "github.com/gin-gonic/gin"
)

func main() {
    r := gin.Default()

    r.GET("/ping", func(c *gin.Context) {
        c.JSON(http.StatusOK, gin.H{
            "message": "pong",
        })
    })

    r.Run(":8080")
}

# 4. Clean up unused dependencies
go mod tidy

# 5. Build
go build ./...

# 6. Test
go test ./...

Common go.mod Directives

module  Declare module path
go      Minimum Go version
require Declare dependencies
replace Redefine dependency path
exclude Exclude specific versions
retract Retract published versions (for module authors)

// retract example — retract an incorrectly published version
retract (
    v1.0.5 // Contains critical bug
    [v1.1.0, v1.1.5] // Retract a range
)

GOPATH vs Go Modules

Aspect	GOPATH	Go Modules
Code location	Must be under $GOPATH/src/	Anywhere
Version management	Not supported	SemVer support
Reproducibility	Low	Guaranteed by go.sum
Dependency files	None	go.mod, go.sum
Current status	Legacy	✅ Official standard

GONOSUMCHECK, GONOSUMDB, GOPRIVATE

Configure these when using private internal packages.

# Set for private modules (bypass checksum DB)
go env -w GONOSUMCHECK="*.corp.example.com/*"
go env -w GOPRIVATE="github.com/mycompany/*"
go env -w GOPROXY="https://proxy.golang.org,direct"

Key Takeaways

• go mod init: Initialize module, creates go.mod
• go get: Add or upgrade dependencies
• go mod tidy: Remove unused, add missing dependencies
• go.sum: Hash file for build reproducibility (never edit manually)
• SemVer required: v2+ must include /v2 in import path
• replace directive: Use for local development or security patches