Building Go Programs

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]

# 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

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

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

List Supported Platforms

View all supported OS/architecture combinations:

go tool dist list

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

# 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

# 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/[email protected]

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

go Command

Overview of go command

Testing

Testing Go packages

Modules

Managing dependencies

Compiler

Go compiler reference

Get Started

Language Guide

Standard Library

Core Packages

Tools & Commands

Advanced Topics

Contributing

​Overview

​Basic Usage

​Output Behavior

​Build Flags

​Common Flags

​Compilation Control

​Build Tags

​Compiler and Linker Flags

​Cross-Compilation

​Common Target Platforms

Linux

macOS

Windows

ARM

​Advanced Options

​Build Modes

​Module Flags

​Path Trimming

​Build Examples

​Development Builds

​Production Builds

​Multi-Platform Release

​Build Performance

​Caching

​Parallel Builds

​Incremental Builds

​Troubleshooting

​CI/CD Integration

​GitHub Actions

​See Also

go Command

Testing

Modules

Compiler

Build docs developers (and LLMs) love

Overview

Basic Usage

Output Behavior

Build Flags

Common Flags

Compilation Control

Build Tags

Compiler and Linker Flags

Cross-Compilation

Common Target Platforms

Advanced Options

Build Modes

Module Flags

Path Trimming

Build Examples

Development Builds

Production Builds

Multi-Platform Release

Build Performance

Caching

Parallel Builds

Incremental Builds

Troubleshooting

CI/CD Integration

GitHub Actions

See Also