Package Management

The Deployment That Broke Everything

It was Friday at 4:47 PM. I'd just merged a PR that upgraded our logging library. The build passed. Tests passed. I deployed to staging.

Everything broke.

The error was cryptic:

cannot find package "github.com/sirupsen/logrus"
  in any of:
    /usr/local/go/src/github.com/sirupsen/logrus (from $GOROOT)
    /home/deploy/go/src/github.com/sirupsen/logrus (from $GOPATH)

I spent the next 3 hours debugging. The problem? Our deployment script used go get without version pinning. The library had released v1.9.0 that day, breaking compatibility with v1.8.0. My local machine had v1.8.0 (working), but staging pulled v1.9.0 (broken).

In Python, I would've used requirements.txt with pinned versions:

logrus==1.8.0

In Go (pre-modules), I had to manually vendor dependencies or pray that go get grabbed compatible versions.

That Friday incident taught me: dependency management isn't optional. The next Monday, I learned about Go modules and never looked back.

This article covers everything I wish I'd known about Go's dependency management.

---

What Are Go Modules?

Go modules are Go's official dependency management system (introduced in Go 1.11, default since Go 1.16).

A module is a collection of related Go packages versioned together. It's defined by:

• go.mod - Module definition and dependencies

• go.sum - Cryptographic checksums for reproducible builds

Before Modules (The Dark Ages)

# The old way (GOPATH)
export GOPATH=$HOME/go
go get github.com/sirupsen/logrus
# No version control!
# No reproducible builds!
# Everything in $GOPATH/src!

Problems:

• No version pinning

• No reproducible builds

• Forced directory structure

• Dependency hell

With Modules (The Light)

# Modern way
go mod init github.com/myuser/myproject
go get github.com/sirupsen/[email protected]
# Version pinned in go.mod
# Reproducible builds via go.sum
# Works in any directory

---

Creating Your First Module

Initialize a Module

mkdir myproject
cd myproject

# Initialize module
go mod init github.com/myuser/myproject

# Creates go.mod:

module github.com/myuser/myproject

go 1.23

The module path is typically your repository URL. For local-only projects:

go mod init myproject  # Simple name

Adding Your First Dependency

Create main.go:

package main

import (
    "github.com/sirupsen/logrus"
)

func main() {
    logrus.Info("Hello, modules!")
}

Add the dependency:

# Option 1: Automatic (when you build/run)
go run main.go
# Automatically adds dependency to go.mod

# Option 2: Explicit
go get github.com/sirupsen/[email protected]

Your go.mod now shows:

module github.com/myuser/myproject

go 1.23

require github.com/sirupsen/logrus v1.9.3

require golang.org/x/sys v0.0.0-20220715151400-c0bba94af5f8 // indirect

Note: The // indirect comment means it's a transitive dependency (dependency of a dependency).

The go.sum File

After running go mod download or building, you get go.sum:

github.com/sirupsen/logrus v1.9.3 h1:dueUQJ1C2q9oE3F7wvmSGAaVtTmUizReu6fjN8uqzbQ=
github.com/sirupsen/logrus v1.9.3/go.mod h1:naHLuLoDiP4jHNo9R0sCBMtWGeIprob74mVsIT4qYEQ=
golang.org/x/sys v0.0.0-20220715151400-c0bba94af5f8 h1:0A+M6Uqn+Eje4kHMK80dtF3JCXC4ykBgQG4Fe06QRhQ=
golang.org/x/sys v0.0.0-20220715151400-c0bba94af5f8/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=

This ensures reproducible builds - everyone gets the same versions.

---

Semantic Versioning in Go

Go modules use semantic versioning (semver): vMAJOR.MINOR.PATCH

• MAJOR: Incompatible API changes (v1.x.x → v2.0.0)

• MINOR: New features, backward compatible (v1.1.x → v1.2.0)

• PATCH: Bug fixes, backward compatible (v1.1.1 → v1.1.2)

Version Selection

# Latest version
go get github.com/gin-gonic/gin

# Specific version
go get github.com/gin-gonic/[email protected]

# Specific commit
go get github.com/gin-gonic/gin@abc1234

# Latest minor/patch for v1
go get github.com/gin-gonic/gin@v1

# Latest patch for v1.9
go get github.com/gin-gonic/[email protected]

Major Version Suffixes

For v2+, Go requires the major version in the import path:

// v0 or v1
import "github.com/go-redis/redis"

// v2+
import "github.com/go-redis/redis/v9"

In go.mod:

require github.com/go-redis/redis/v9 v9.0.5

---

Common go mod Commands

go mod init

Initialize a new module:

go mod init github.com/myuser/myproject

go get

Add or update dependencies:

# Add latest version
go get github.com/gin-gonic/gin

# Add specific version
go get github.com/gin-gonic/[email protected]

# Update all dependencies
go get -u ./...

# Update minor/patch versions only
go get -u=patch ./...

go mod tidy

Remove unused dependencies and add missing ones:

go mod tidy

# Output:
# Removes: unused dependencies from go.mod
# Adds: missing dependencies your code imports

Best practice: Run this before committing.

go mod download

Download dependencies to local cache:

go mod download

Useful for CI/CD to cache dependencies.

go mod verify

Verify dependencies haven't been modified:

go mod verify

# Output:
# all modules verified

go mod graph

Show dependency graph:

go mod graph

# Output:
# myproject github.com/gin-gonic/[email protected]
# github.com/gin-gonic/[email protected] github.com/bytedance/[email protected]
# ...

go mod why

Explain why a dependency is needed:

go mod why github.com/bytedance/sonic

# Output:
# # github.com/bytedance/sonic
# myproject
# github.com/gin-gonic/gin
# github.com/bytedance/sonic

---

Upgrading and Downgrading Dependencies

Check for Updates

# List available updates
go list -u -m all

# Output:
# github.com/gin-gonic/gin v1.9.1 [v1.10.0]
# github.com/sirupsen/logrus v1.8.0 [v1.9.3]

Upgrade to Latest

# Upgrade one dependency
go get github.com/gin-gonic/gin@latest

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

# Upgrade to latest patch version only
go get -u=patch ./...

Downgrade

# Downgrade to specific version
go get github.com/gin-gonic/[email protected]

# go.mod updated:
# github.com/gin-gonic/gin v1.8.0

Real Example: The Logging Library Upgrade

After my Friday disaster, here's how I handled upgrades:

# Check what's available
go list -u -m github.com/sirupsen/logrus
# github.com/sirupsen/logrus v1.8.0 [v1.9.3]

# Read the changelog first!
# https://github.com/sirupsen/logrus/releases/tag/v1.9.3

# Test on a branch
git checkout -b upgrade-logrus
go get github.com/sirupsen/[email protected]

# Run tests
go test ./...

# If tests pass, commit
git add go.mod go.sum
git commit -m "Upgrade logrus to v1.9.3"

# If tests fail, investigate or downgrade
go get github.com/sirupsen/[email protected]

---

The Replace Directive

The replace directive lets you override dependencies. Useful for:

• Local development

• Forking libraries

• Testing patches

Replace with Local Path

module github.com/myuser/myproject

go 1.23

require github.com/someuser/library v1.0.0

// Use local version during development
replace github.com/someuser/library => ../library

Replace with Fork

// Use your fork instead of original
replace github.com/original/library => github.com/myuser/library v1.0.1-fork

Real Example: Patching a Bug

I once found a bug in a library we used. While waiting for the fix to be merged:

module github.com/mycompany/myservice

go 1.23

require github.com/somelib/client v2.1.0

// Temporary: use our fork with bugfix
replace github.com/somelib/client => github.com/mycompany/client v2.1.0-bugfix

After the upstream fix was released:

# Remove replace directive
# Update to official version
go get github.com/somelib/[email protected]

# go.mod:
# require github.com/somelib/client v2.1.1
# (replace directive removed)

---

Vendor Directory

The vendor directory stores dependencies in your repository.

Why Vendor?

• Air-gapped environments (no internet access during build)

• Guaranteed availability (dependencies can't disappear)

• Faster CI builds (no download step)

Creating Vendor Directory

go mod vendor

# Creates:
# vendor/
#   github.com/
#     gin-gonic/
#       gin/
#   modules.txt  # List of vendored packages

Using Vendor

# Build using vendor
go build -mod=vendor

# Or set environment variable
export GOFLAGS="-mod=vendor"
go build

Should You Vendor?

Yes, if:

• Deploying to restricted environments

• Repository policy requires it

• Building Docker images (can cache vendor)

No, if:

• Using modern CI/CD (can cache GOMODCACHE)

• Repository size matters

• Team prefers lighter repos

My approach: Don't vendor unless required. Go modules + caching work great.

---

Private Modules

Using Private Repositories

Tell Go to bypass proxy for private repos:

export GOPRIVATE=github.com/mycompany/*

# Or in go env:
go env -w GOPRIVATE=github.com/mycompany/*

Authentication

For HTTPS:

# Configure git to use credentials
git config --global url."https://username:[email protected]/".insteadOf "https://github.com/"

For SSH:

# Configure git to use SSH
git config --global url."[email protected]:".insteadOf "https://github.com/"

Real Example: Internal Libraries

At my company, we had internal Go libraries:

# Set private repos
go env -w GOPRIVATE=github.com/mycompany/*

# Configure SSH
git config --global url."[email protected]:".insteadOf "https://github.com/"

# Now can import internal packages
# go get github.com/mycompany/[email protected]

In code:

import (
    "github.com/mycompany/internal-lib/auth"
    "github.com/mycompany/internal-lib/database"
)

---

Real Example: Complete Project Setup

Here's how I set up new projects after learning modules:

1. Initialize Project

mkdir my-api
cd my-api

go mod init github.com/myuser/my-api

2. Add Dependencies

# Web framework
go get github.com/gin-gonic/[email protected]

# Database
go get github.com/lib/[email protected]

# Configuration
go get github.com/spf13/[email protected]

# Logging
go get github.com/sirupsen/[email protected]

3. Write Code

main.go:

package main

import (
    "github.com/gin-gonic/gin"
    "github.com/sirupsen/logrus"
)

func main() {
    logrus.Info("Starting server...")
    
    r := gin.Default()
    r.GET("/ping", func(c *gin.Context) {
        c.JSON(200, gin.H{"message": "pong"})
    })
    
    r.Run(":8080")
}

4. Clean Up

# Remove unused dependencies
go mod tidy

# Verify everything
go mod verify

5. Final go.mod

module github.com/myuser/my-api

go 1.23

require (
    github.com/gin-gonic/gin v1.9.1
    github.com/lib/pq v1.10.9
    github.com/sirupsen/logrus v1.9.3
    github.com/spf13/viper v1.16.0
)

require (
    // ... indirect dependencies ...
)

6. Commit

git add go.mod go.sum
git commit -m "Add project dependencies"

---

Best Practices

1. Always Commit go.sum

# go.sum ensures reproducible builds
git add go.mod go.sum
git commit -m "Update dependencies"

2. Run go mod tidy Before Committing

# Remove unused, add missing
go mod tidy

# Then commit
git add go.mod go.sum
git commit -m "..."

3. Pin Versions in Production

// Good: Specific version
require github.com/gin-gonic/gin v1.9.1

// Bad: No version (defaults to latest)
require github.com/gin-gonic/gin

4. Review Dependency Updates

# Don't blindly upgrade
go get -u ./...

# Instead, check each update
go list -u -m all
# Read changelogs
# Upgrade one at a time
# Test after each upgrade

5. Use GOPRIVATE for Private Repos

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

6. Minimal Dependencies

Every dependency is a liability:

• Security vulnerabilities

• Compatibility issues

• Build complexity

Ask: Do I really need this library? Can I write it myself?

---

Your Challenge

Create a CLI tool with proper dependency management:

# 1. Initialize module
go mod init github.com/yourusername/weather-cli

# 2. Add dependencies:
#    - cobra for CLI structure
#    - viper for configuration
#    - logrus for logging
#    - a HTTP client library

# 3. Build a weather CLI that:
#    - Fetches weather from an API
#    - Uses structured logging
#    - Accepts command-line flags
#    - Properly manages all dependencies

# 4. Verify:
#    - go.mod has all dependencies
#    - go.sum exists and committed
#    - go mod tidy produces no changes
#    - go mod verify succeeds

---

Key Takeaways

1. go.mod: Defines module and dependencies with versions

2. go.sum: Ensures reproducible builds with checksums

3. Semantic versioning: MAJOR.MINOR.PATCH version scheme

4. go get: Add/update dependencies

5. go mod tidy: Clean up unused dependencies

6. Replace directive: Override dependencies for local dev or forks

7. Vendor: Store dependencies in repository

8. GOPRIVATE: Access private repositories

---

What I Learned

That Friday deployment disaster taught me that dependency management is critical:

• go.mod gave me reproducible builds - same versions everywhere

• go.sum prevented supply chain attacks - cryptographic verification

• Semantic versioning made upgrades predictable - know what breaks

• Zero deployment surprises for 2 years since adopting modules

Coming from Python's virtualenv/requirements.txt chaos and Node's node_modules hell, Go modules felt elegant. One command (go mod tidy), two files (go.mod, go.sum), zero surprises.

The time saved debugging dependency issues? Countless hours.

---

Next: Testing in Go

In the next article, we'll explore Go's testing framework. You'll learn table-driven tests, benchmarks, and the TDD approach that caught bugs before they hit production.