# Golang Modules

> When to activate: Go modules, go.mod, go.sum, versioning, workspaces, private modules, dependency management

- Skill: `mattakushi432/golang-modules` (Agent Skill)
- Install (CLI): `npx skillmds@latest add mattakushi432/golang-modules`
- Raw SKILL.md: https://api.skillmd.com/api/skills/mattakushi432/golang-modules/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: Mattakushi432 (https://skillmd.com/u/mattakushi432)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/mattakushi432/golang-modules

---


# Go Modules Patterns

## go.mod Structure

```
module github.com/myorg/myapp

go 1.23

require (
    github.com/gin-gonic/gin              v1.10.0
    github.com/jackc/pgx/v5              v5.6.0
    github.com/golang-jwt/jwt/v5         v5.2.1
    github.com/stretchr/testify          v1.9.0
    golang.org/x/crypto                  v0.24.0
)

require (
    // indirect dependencies (auto-managed)
    github.com/bytedance/sonic v1.11.6 // indirect
)
```

## Common go Commands

```bash
# Initialize a new module
go mod init github.com/myorg/myapp

# Add a dependency (downloads and updates go.mod)
go get github.com/gin-gonic/gin@v1.10.0

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

# Tidy: remove unused, add missing
go mod tidy

# Vendor dependencies for reproducible offline builds
go mod vendor

# Show module dependency graph
go mod graph | head -20

# Verify checksums in go.sum
go mod verify

# Download all dependencies
go mod download

# Show why a package is needed
go mod why github.com/some/pkg
```

## Version Pinning

```bash
# Exact version
go get github.com/some/pkg@v1.2.3

# Latest patch in v1.2.x
go get github.com/some/pkg@v1.2

# Specific commit
go get github.com/some/pkg@abc1234

# Latest pre-release
go get github.com/some/pkg@latest

# Downgrade
go get github.com/some/pkg@v1.1.0
```

## Go Workspaces (go.work)

Workspaces let you develop multiple modules simultaneously without replace directives.

```bash
# Create workspace
go work init ./myapp ./mylib

# Add module to workspace
go work use ./another-module
```

```
# go.work
go 1.23

use (
    ./myapp
    ./mylib
    ./another-module
)
```

## Replace Directives

```go
// go.mod — for local development only; don't commit replaces to libraries
replace (
    github.com/myorg/mylib => ../mylib                 // local path
    github.com/some/buggy  => github.com/fork/fixed v1.2.3  // fork
)
```

## Private Modules

```bash
# Tell go not to use public proxy for private modules
GONOSUMCHECK=github.com/myorg/*
GONOSUMDB=github.com/myorg/*
GOPRIVATE=github.com/myorg/*

# Or set in ~/.config/go/env
go env -w GOPRIVATE=github.com/myorg/*
go env -w GONOSUMDB=github.com/myorg/*
```

## Multi-Module Repository

```
monorepo/
├── go.work            # workspace file
├── svc-user/
│   ├── go.mod         # module github.com/myorg/svc-user
│   └── cmd/server/
├── svc-order/
│   ├── go.mod         # module github.com/myorg/svc-order
│   └── cmd/server/
└── shared/
    ├── go.mod         # module github.com/myorg/shared
    └── pkg/
```

## Common Anti-Patterns

- **`go get` without version** — always pin a version; `@latest` can break builds
- **Committing `replace` directives in library `go.mod`** — they affect all consumers; use workspaces instead
- **Not running `go mod tidy`** — go.sum and go.mod drift; run in CI
- **Checking in `vendor/` alongside `go.sum`** — pick one strategy; both together causes confusion
- **`GOPATH` mode** — Go modules are the standard; never use `GO111MODULE=off` in new projects