Building Go Programs

Compile packages and dependencies with go build

The go build command compiles packages and their dependencies, creating executable binaries or verifying that packages can be built.

Overview

Building is one of the most common operations in Go development. The go build command handles dependency resolution, compilation, and linking automatically.

Basic Usage

go build [-o output] [build flags] [packages]

Current Package

# Build current package
go build

# Build with custom output name
go build -o myapp

# Build for current directory
go build .

Output Behavior

Main Packages (Executables)

When building a main package, go build creates an executable file:

# Builds executable named after last path component
go build example.com/myapp     # Creates: myapp
go build example.com/foo/v2    # Creates: foo

On Windows, adds .exe extension automatically.

Non-Main Packages (Libraries)

When building library packages, go build compiles them but discards the result:

# Compiles but doesn't create output file
go build example.com/mylib

This is useful for verifying packages compile successfully.

Custom Output with -o

The -o flag controls output location:

# Specific filename
go build -o bin/myapp

# Directory (must end with / or \\)
go build -o bin/ example.com/myapp

# Multiple packages to directory
go build -o bin/ ./cmd/...

Build Flags

Common Flags

-o · file/directory

Specify output file or directory

go build -o myapp
go build -o bin/

-v · flag

Print names of packages as they are compiled

go build -v

-a · flag

Force rebuilding of packages that are already up-to-date

go build -a

-n · flag

Print commands but do not run them

go build -n

-x · flag

Print commands as they are executed

go build -x

Compilation Control

-p · n

Number of programs to run in parallel (default: GOMAXPROCS)

go build -p 4

-race · flag

Enable data race detection

go build -race

Supported on: darwin/amd64, darwin/arm64, linux/amd64, linux/arm64, windows/amd64

-msan · flag

Enable memory sanitizer (requires Clang/LLVM)

go build -msan

-asan · flag

Enable address sanitizer

go build -asan

-cover · flag

Enable code coverage instrumentation

go build -cover

Build Tags

-tags · tag,list

Comma-separated list of build tags

go build -tags=integration,postgres
go build -tags "debug trace"

Compiler and Linker Flags

-gcflags · '[pattern=]arg list'

Arguments to pass to the Go compiler

# Disable optimizations and inlining
go build -gcflags='-N -l'

# View optimization decisions
go build -gcflags='-m'

# For specific package
go build -gcflags='example.com/myapp=-N -l'

-ldflags · '[pattern=]arg list'

Arguments to pass to the linker

# Set version information
go build -ldflags="-X main.version=1.0.0"

# Strip debug info and reduce binary size
go build -ldflags="-s -w"

# Multiple flags
go build -ldflags="-X main.version=1.0.0 -s -w"

-asmflags · '[pattern=]arg list'

Arguments to pass to the assembler

go build -asmflags="-S"

Cross-Compilation

1. Set Target Platform

   Use GOOS and GOARCH environment variables:

   # Linux AMD64
   GOOS=linux GOARCH=amd64 go build
   
   # Windows
   GOOS=windows GOARCH=amd64 go build -o app.exe
   
   # macOS ARM64 (Apple Silicon)
   GOOS=darwin GOARCH=arm64 go build
   
2. List Supported Platforms

   View all supported OS/architecture combinations:

   go tool dist list
   
3. Build for Multiple Platforms

   Common cross-compilation script:

   #!/bin/bash
   platforms=("linux/amd64" "darwin/amd64" "windows/amd64")
   
   for platform in "${platforms[@]}"; do
       platform_split=(${platform//\// })
       GOOS=${platform_split[0]}
       GOARCH=${platform_split[1]}
       output_name='myapp-'$GOOS'-'$GOARCH
       
       if [ $GOOS = "windows" ]; then
           output_name+='.exe'
       fi
       
       GOOS=$GOOS GOARCH=$GOARCH go build -o bin/$output_name
   done
   

Common Target Platforms

Linux

GOOS=linux GOARCH=amd64 go build
GOOS=linux GOARCH=arm64 go build

macOS

GOOS=darwin GOARCH=amd64 go build
GOOS=darwin GOARCH=arm64 go build

Windows

GOOS=windows GOARCH=amd64 go build
GOOS=windows GOARCH=386 go build

ARM

GOOS=linux GOARCH=arm go build
GOOS=linux GOARCH=arm64 go build

Advanced Options

Build Modes

-buildmode · mode

Specify build mode

# Default executable
go build -buildmode=exe

# Shared library
go build -buildmode=shared

# C shared library
go build -buildmode=c-shared -o mylib.so

# C static library
go build -buildmode=c-archive

# Plugin
go build -buildmode=plugin

Module Flags

-mod · mode

Module download mode: readonly, vendor, or mod

# Read-only mode (default in most cases)
go build -mod=readonly

# Use vendor directory
go build -mod=vendor

# Allow module updates
go build -mod=mod

-modfile · file

Use alternate go.mod file

go build -modfile=go.dev.mod

Path Trimming

-trimpath · flag

Remove file system paths from executable

go build -trimpath

Results in reproducible builds and smaller binaries.

Build Examples

Development Builds

Quick Development Build

# Fast build for local testing
go build -o bin/myapp

# With race detector
go build -race -o bin/myapp

# Verbose output
go build -v -o bin/myapp

Production Builds

Optimized Production Build

# Strip debug info, reduce size
go build -ldflags="-s -w" -trimpath -o bin/myapp

# With version info
VERSION=$(git describe --tags)
go build -ldflags="-s -w -X main.version=$VERSION" -trimpath -o bin/myapp

Multi-Platform Release

Makefile

.PHONY: build-all
build-all:
	@echo "Building for multiple platforms..."
	GOOS=linux GOARCH=amd64 go build -ldflags="-s -w" -o dist/myapp-linux-amd64
	GOOS=linux GOARCH=arm64 go build -ldflags="-s -w" -o dist/myapp-linux-arm64
	GOOS=darwin GOARCH=amd64 go build -ldflags="-s -w" -o dist/myapp-darwin-amd64
	GOOS=darwin GOARCH=arm64 go build -ldflags="-s -w" -o dist/myapp-darwin-arm64
	GOOS=windows GOARCH=amd64 go build -ldflags="-s -w" -o dist/myapp-windows-amd64.exe

Build Performance

Caching

Go automatically caches build artifacts:

# View cache location
go env GOCACHE

# Clear build cache
go clean -cache

# Clear module cache
go clean -modcache

Parallel Builds

# Increase parallelism
go build -p 8

# Set via environment
export GOMAXPROCS=8
go build

Incremental Builds

# Only rebuild changed packages (default)
go build

# Force full rebuild
go build -a

Troubleshooting

Build is slow

# Check what's being compiled
go build -x

# Increase parallelism
go build -p 8

# Check cache
go env GOCACHE

Binary is too large

# Strip debug symbols
go build -ldflags="-s -w"

# Use UPX compression
go build -ldflags="-s -w" && upx myapp

Module version conflicts

# Update dependencies
go get -u
go mod tidy

# Use specific version
go get example.com/pkg@v1.2.3

CI/CD Integration

GitHub Actions

.github/workflows/build.yml

name: Build

on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - uses: actions/setup-go@v5
        with:
          go-version: '1.21'
          
      - name: Build
        run: go build -v ./...
        
      - name: Build release
        run: |
          go build -ldflags="-s -w" -trimpath -o bin/myapp

See Also

go Command

Overview of go command

Testing

Testing Go packages

Modules

Managing dependencies

Compiler

Go compiler reference