go build, run, install & clean

These four commands cover how Go turns source into binaries, executes them locally, installs tools globally, and resets caches when debugging stale builds.

Summary

go build compiles packages into artifacts you ship.

go run is a dev shortcut that compiles to a temp file and runs it immediately.

go install places command binaries on your PATH via GOBIN or GOPATH/bin.

go clean removes build outputs and cache entries when you need a cold rebuild.

All four share the same package loader and honor build tags, GOOS, GOARCH, and module settings.

Recipe

Quick-reference recipe card - copy-paste ready.

# Build a service binary with size-focused flags
go build -trimpath -ldflags="-s -w" -o bin/api ./cmd/api
 
# Run locally with arguments
go run ./cmd/api --addr :8080
 
# Install a CLI tool at the module version in go.mod
go install golang.org/x/tools/cmd/goimports@latest
 
# Clear test result cache after fixing a flaky test
go clean -testcache

When to reach for this:

• Use go build for release artifacts, Docker images, and CI binaries.
• Use go run for quick iteration on main packages.
• Use go install for developer tools (goimports, staticcheck, codegen CLIs).
• Use go clean -cache only when diagnosing corrupted or impossible cache hits.

Working Example

# Module layout:
# .
# ├── go.mod
# ├── cmd/seed/main.go
# └── internal/seed/seed.go
 
go build -o bin/seed ./cmd/seed
./bin/seed --count 5
 
go run ./cmd/seed --count 3
 
go install ./cmd/seed   # installs to $(go env GOPATH)/bin or GOBIN
 
go clean -i ./cmd/seed  # remove installed binary for this import path

// cmd/seed/main.go
package main
 
import (
    "flag"
    "fmt"
    "example.com/tooldemo/internal/seed"
)
 
func main() {
    n := flag.Int("count", 1, "records to create")
    flag.Parse()
    fmt.Println(seed.Generate(*n))
}

// internal/seed/seed.go
package seed
 
import "fmt"
 
func Generate(n int) string {
    return fmt.Sprintf("generated %d records", n)
}

What this demonstrates:

• go build -o names the output explicitly for deploy scripts.
• go run accepts the same package path and forwards flags after -- when needed.
• go install with a relative ./cmd/seed installs from the current module without a separate go get.
• go clean -i removes the installed binary matching that package's import path.

Deep Dive

How It Works

• The loader resolves the package pattern to a import path, applies build constraints, and builds an action graph.
• Compile steps write archive files to GOCACHE; link steps combine archives into executables.
• go run links to a temporary executable in the OS temp directory and deletes it after exit (unless -work leaves intermediates for inspection).
• go install skips copying into the current directory; it only updates the install destination.

Build Flags at a Glance

go clean Targets

Go Notes

# Inspect where artifacts go
go env GOCACHE GOMODCACHE GOPATH GOBIN
 
# Print linker-invoked build ID embedded in binaries
go tool buildid bin/seed

Gotchas

• Using go run in production scripts - compiles on every invocation and hides the artifact path. Fix: go build once, run the binary.
• Forgetting -o in CI - default output names collide when building multiple commands in one directory. Fix: always set -o bin/<name>.
• go install without a version outside a module - @latest may jump ahead of CI pins. Fix: run from a module with a recorded require or pin @v1.2.3.
• go clean -modcache in shared CI - forces full re-download and slows every job. Fix: cache GOMODCACHE between runs; clean only on corruption errors.
• Cross-compiling cgo packages - needs a cross C toolchain, not just GOOS/GOARCH. Fix: disable cgo (CGO_ENABLED=0) or install the matching cross compiler.
• Stale -trimpath expectations - panics still include function names; only file paths are trimmed. Fix: upload symbols separately if you need path-level debugging.

Alternatives

FAQs

Related

• The go Command: Build, Test, and Module Lifecycle - action graph and caches
• Go Toolchain Basics - introductory command examples
• Build Tags & Conditional Compilation - tag-gated sources
• Cross-Compilation & Private Module Proxies - GOOS/GOARCH matrix
• Go Toolchain Best Practices - reproducible release builds

Stack versions: This page was written for Go 1.26.x (Green Tea GC default, go fix modernizers - verify patch at build), chi (latest - verify at build), gin (latest - verify at build), echo (latest - verify at build), google.golang.org/grpc (latest - verify at build), sigs.k8s.io/controller-runtime (latest - verify at build), kubebuilder (latest - verify at build), tinygo (latest - verify board targets at build), wazero (latest - verify at build), and golangci-lint (latest - verify linter set at build).