The 15-megabyte surprise
You write a twenty-line CLI tool in Go. It prints a greeting, parses a flag, and exits. You run go build and check the file size. Fifteen megabytes. You expected a few hundred kilobytes. The panic is understandable. Go binaries are famously large compared to interpreted languages or dynamically linked C programs. The size isn't a bug. It is a deliberate trade-off for portability, speed, and simplicity. You can shrink that binary without sacrificing reliability. You just need to tell the linker what to throw away.
Why Go binaries weigh what they weigh
Go compiles directly to machine code. It does not rely on a runtime interpreter or a separate virtual machine. Every dependency, including the standard library, gets baked into the final executable. The compiler also embeds debugging information by default. DWARF debug data, symbol tables, and version strings take up space. Think of a Go binary like a fully equipped emergency kit. It contains everything it might need to run on any Linux, macOS, or Windows machine without asking the host system for help. That convenience costs disk space.
The linker is where the weight lives. When go build finishes compiling your code, it hands the object files to the linker. The linker merges them, resolves addresses, and writes the final ELF, Mach-O, or PE file. By default, it keeps every symbol, every debug line number, and every build path. You can trim most of that baggage with a few flags.
The linker packs everything by default. Tell it what to leave behind.
The baseline optimization
Here is the standard production build command. It strips debug symbols, removes the DWARF table, and cleans up build paths.
// main.go
package main
import "fmt"
// Greet prints a simple message to stdout.
func Greet(name string) {
// fmt.Printf handles formatting without allocating extra buffers
fmt.Printf("Hello, %s\n", name)
}
func main() {
// Entry point calls the single exported function
Greet("world")
}
Run go build -o app main.go and check the size. Now run the optimized version:
# Strip debug info and build paths to shrink the output
go build -ldflags="-s -w" -trimpath -o app-optimized main.go
The -s flag drops the symbol table. The -w flag drops the DWARF debug information. Together they remove the mapping between machine addresses and your source code. The -trimpath flag strips absolute file paths from the binary. That path information helps debuggers but inflates the executable and leaks your local directory structure. You lose stack trace readability, but production binaries rarely need line numbers. You gain a smaller file and faster load times.
The linker packs everything by default. Tell it what to leave behind.
What happens under the hood
When you pass -ldflags="-s -w", you are speaking directly to the Go linker. The linker reads those flags and changes its output strategy. Without -s, it writes a .symtab section that maps function names to memory addresses. Without -w, it writes a .debug_info section that maps memory addresses back to file names and line numbers. Both sections are useful when you attach gdb or delve. Both are dead weight when the program runs in production.
The -trimpath flag works earlier in the pipeline. The compiler embeds the absolute path of every source file into the object files. If you build inside /home/developer/projects/myapp, that string gets baked into the binary. The linker copies it over. -trimpath tells the compiler to replace those paths with a relative workspace root. The binary still knows where functions live, but it stops advertising your home directory.
Go also caches compiled packages in the build cache. If you change build flags, the cache might serve an older, unoptimized object file. The toolchain is smart about invalidating cache entries, but sometimes it holds on to a larger version. You can force a clean rebuild with go clean -cache or go build -a. The -a flag forces rebuilding of all packages, including cached ones. Use it when the binary size refuses to drop after changing flags.
The Go community convention is to keep build commands explicit in Makefiles or CI scripts rather than hiding them in wrapper tools. Readability beats cleverness when debugging pipeline failures.
Cache hits save time. Cache misses save space.
Realistic build pipeline
Production projects rarely use a single go build command. They use Makefiles, CI scripts, or build wrappers. Here is a realistic setup that handles cross-compilation, stripping, and size verification.
# Cross-compile for Linux amd64 with production flags
GOOS=linux GOARCH=amd64 go build \
-ldflags="-s -w -X main.version=1.0.0" \
-trimpath \
-o dist/myapp-linux-amd64 \
./cmd/myapp
The -X main.version=1.0.0 flag injects a string variable at link time. It replaces the need to embed version files or generate code. The linker patches the variable in the data section. You get version information without bloating the source tree. The ./cmd/myapp path tells the compiler to build the main package in that directory. The dist/ folder keeps artifacts separate from source code.
Check the final size with ls -lh dist/myapp-linux-amd64. A typical CLI tool drops from 12 megabytes to 4 megabytes with these flags. A web server with routing, JSON parsing, and TLS drops from 25 megabytes to 8 megabytes. The exact numbers depend on your dependencies. The standard library alone weighs about 2 megabytes when stripped. Every third-party package adds its own weight.
Version strings belong in the linker. File trees belong in git.
Pitfalls and silent failures
Stripping debug information breaks interactive debugging. If you run dlv debug ./main.go on a stripped binary, the debugger cannot map addresses to source lines. You get raw memory dumps instead of stack traces. Keep unstripped binaries for development. Use stripped binaries for deployment.
Some packages rely on reflection or embedded assets. If a library expects debug symbols for runtime inspection, stripping them causes panics. The error usually looks like runtime error: invalid memory address or nil pointer dereference when the reflection package tries to read a missing symbol table. This is rare in modern Go. The standard library does not depend on debug symbols at runtime. Third-party C bindings via cgo sometimes do. If you use cgo, verify that the linked C library does not require symbol resolution.
Accidentally importing heavy packages inflates the binary. golang.org/x/exp or full database drivers pull in megabytes of code. The compiler includes everything you import, even if you only call one function. Run go mod why -m <package> to trace why a dependency exists. Remove unused imports. The compiler will reject the program with imported and not used if you leave dead imports behind.
Another trap is the build cache. You change -ldflags, run go build, and the size stays the same. The compiler reused a cached object file that was compiled without your new flags. The fix is go clean -cache followed by a fresh build. The cache directory can grow to gigabytes over time. Clear it monthly in CI pipelines.
Dead imports waste bytes. The compiler catches them. Trust the error.
When to optimize and when to stop
Binary size matters in specific environments. It matters less in others. Pick the right strategy for your deployment target.
Use -ldflags="-s -w" -trimpath when you deploy to production servers, Docker containers, or serverless platforms where cold start time and disk quota matter. Use go build -a when the build cache serves stale object files and your size metrics refuse to update. Use go mod tidy and go mod why when third-party dependencies inflate the binary with unused code. Use cross-compilation with GOOS and GOARCH when you need to ship binaries for multiple platforms from a single machine. Use plain go build without flags when you are debugging locally and need full stack traces and symbol resolution.
Strip for production. Keep debug symbols for development. Never optimize blindly.