I used to assume that every time I wrote &someStruct{} or returned a pointer from a function, I was creating a heap allocation. I was wrong — and the wrongness mattered for how I was designing APIs. After learning about escape analysis, I stopped guessing and started asking the compiler directly. This changed how I write Go.
The Problem
Go has two places to put data: the stack and the heap. Stack allocations are cheap — they’re just a pointer bump, and the stack frame is reclaimed automatically when the function returns. Heap allocations go through the memory allocator, require garbage collection, and have non-trivial overhead.
The question is: when you allocate something in Go, where does it land? The answer is not always what you’d expect. A value allocated with new or &T{} does not necessarily land on the heap. Equally, a local variable does not necessarily stay on the stack.
The Go compiler performs escape analysis — a static analysis pass that determines whether a value’s lifetime can be bounded to the function’s stack frame, or whether it might “escape” to be referenced after the function returns, requiring heap allocation.
If you don’t understand escape analysis, you’ll make API decisions that accidentally cause heap allocations in hot paths, and you’ll have no principled way to reason about your program’s allocation behavior.
The Idiomatic Way
The primary tool for understanding escape analysis is the compiler flag -gcflags="-m". Pass -m -m for more detail:
go build -gcflags="-m" ./...
# or for a specific file:
go tool compile -m main.go
The output tells you exactly which variables escape to the heap and why. Let’s look at the most common escape reasons:
package main
import "fmt"
// Case 1: returning a pointer — does NOT escape if inlined,
// but typically DOES escape because the value outlives the function
func newInt() *int {
x := 42 // x escapes to heap
return &x // we're returning a pointer — x must outlive this stack frame
}
// Case 2: storing in interface — always escapes (interface holds a pointer)
func storeInInterface() interface{} {
x := 42
return x // x escapes to heap (stored in interface data word)
}
// Case 3: captured by closure — may escape
func makeAdder(base int) func(int) int {
// base escapes if the closure outlives this function call
return func(n int) int {
return base + n
}
}
// Case 4: local variable — stays on stack
func sumLocal() int {
x := 10
y := 20
return x + y // x and y stay on stack — they don't outlive sumLocal
}
func main() {
p := newInt()
fmt.Println(*p)
v := storeInInterface()
fmt.Println(v)
add5 := makeAdder(5)
fmt.Println(add5(3))
fmt.Println(sumLocal())
}
Run this with go build -gcflags="-m" . and you’ll see annotations like:
./main.go:8:2: x escapes to heap
./main.go:14:9: x escapes to heap
./main.go:19:2: base escapes to heap
Now let’s look at a case that surprises many developers — large structs passed by value versus pointer:
package main
import "fmt"
type SmallPoint struct {
X, Y float64
}
type LargeMatrix struct {
data [1024]float64
}
// Passing by value: for small types, cheaper than pointer + GC overhead
func processPoint(p SmallPoint) SmallPoint {
return SmallPoint{X: p.X * 2, Y: p.Y * 2}
}
// For large types, pointer avoids copying — but the tradeoff depends on escape
func processMatrix(m *LargeMatrix) {
for i := range m.data {
m.data[i] *= 2
}
}
// This might surprise you: creating a large value locally does NOT escape
// if it doesn't leave this function
func computeLocally() float64 {
var m LargeMatrix // stays on stack — never escapes!
for i := range m.data {
m.data[i] = float64(i)
}
sum := 0.0
for _, v := range m.data {
sum += v
}
return sum // only the result escapes, not the matrix
}
func main() {
p := SmallPoint{X: 1.0, Y: 2.0}
fmt.Println(processPoint(p))
m := &LargeMatrix{}
processMatrix(m)
fmt.Println(computeLocally())
}
computeLocally creates a 8KB array on the stack. This is fine — Go has growable stacks starting at 8KB (as of Go 1.4+), so there’s typically room. The key insight is that the large local variable doesn’t escape because no pointer to it leaves the function.
In The Wild
Understanding escape analysis helps you write better APIs. Consider a common pattern: building a result struct:
package main
import "fmt"
type Config struct {
Host string
Port int
Timeout int
Debug bool
}
// Pattern A: returns pointer — Config always escapes to heap
func newConfigPtr(host string, port int) *Config {
return &Config{
Host: host,
Port: port,
Timeout: 30,
}
}
// Pattern B: returns value — Config stays on stack if caller doesn't take address
func newConfigVal(host string, port int) Config {
return Config{
Host: host,
Port: port,
Timeout: 30,
}
}
// For hot paths, you might use an output parameter to avoid allocations entirely
func initConfig(cfg *Config, host string, port int) {
cfg.Host = host
cfg.Port = port
cfg.Timeout = 30
}
func main() {
// newConfigPtr: heap allocation
c1 := newConfigPtr("localhost", 8080)
fmt.Println(c1.Host)
// newConfigVal: stack allocation if c2 doesn't escape
c2 := newConfigVal("localhost", 8080)
fmt.Println(c2.Host)
// initConfig: caller controls allocation
var c3 Config
initConfig(&c3, "localhost", 8080)
fmt.Println(c3.Host)
}
The output parameter pattern (initConfig) is used throughout the standard library — json.Unmarshal, binary.Read, etc. — precisely because it lets the caller decide where the data lives.
Another real-world example: sync.Pool works best when you understand escape analysis:
package main
import (
"bytes"
"fmt"
"sync"
)
var bufPool = sync.Pool{
New: func() interface{} {
return new(bytes.Buffer)
},
}
func processRequest(data string) string {
// Get a buffer from pool — reuse heap allocations
buf := bufPool.Get().(*bytes.Buffer)
buf.Reset()
defer bufPool.Put(buf)
buf.WriteString("processed: ")
buf.WriteString(data)
return buf.String() // String() allocates — but buf itself is reused
}
func main() {
fmt.Println(processRequest("hello"))
fmt.Println(processRequest("world"))
}
The buffer itself doesn’t escape repeatedly — it’s reused from the pool. Only the final string value escapes, which is unavoidable since strings are immutable and must outlive the buffer.
The Gotchas
fmt.Println causes everything to escape: passing values to fmt.Println (or any function taking interface{}) causes the values to escape to the heap, because the interface boxing allocates. This is why you should use concrete-typed functions in hot paths:
package main
import "fmt"
func main() {
x := 42
fmt.Println(x) // x escapes to heap — interface boxing
// In hot paths, prefer:
// log.Printf with format string keeps values on stack better
// or use a typed writer that avoids interface{}
_ = x
}
Compiler optimizations can inline and eliminate escapes: if a function is small enough to be inlined, a “returning pointer” scenario might not actually cause a heap allocation because the callee’s stack frame merges with the caller’s. Don’t assume — measure with -gcflags="-m".
Stack size limits: Go’s goroutine stack starts small and grows dynamically, but there’s still a limit (default 1GB). Extremely large stack allocations can cause issues in concurrent programs with many goroutines. If you’re allocating multi-megabyte arrays per goroutine, consider heap allocation explicitly.
package main
import (
"fmt"
"runtime"
)
func checkAllocations(f func()) uint64 {
var before, after runtime.MemStats
runtime.GC()
runtime.ReadMemStats(&before)
f()
runtime.ReadMemStats(&after)
return after.TotalAlloc - before.TotalAlloc
}
func main() {
// Measure allocations of two approaches
allocated := checkAllocations(func() {
for i := 0; i < 1000; i++ {
x := i * 2 // stack — no allocation
_ = x
}
})
fmt.Printf("Loop with stack var: %d bytes allocated\n", allocated)
allocated2 := checkAllocations(func() {
for i := 0; i < 1000; i++ {
x := new(int) // heap — allocation
*x = i * 2
_ = x
}
})
fmt.Printf("Loop with heap var: %d bytes allocated\n", allocated2)
}
Key Takeaway
Go’s escape analysis determines at compile time whether a value lives on the stack or the heap. Stack allocation is free (pointer bump) and requires no GC. Heap allocation goes through the memory allocator and must be collected. Values escape to the heap when their lifetimes exceed the stack frame — typically when returning pointers, boxing into interfaces, capturing in closures, or sending on channels.
The practical tools:
- Use
go build -gcflags="-m"to see exactly what escapes and why - Use
runtime.ReadMemStatsortesting.B.ReportAllocsto measure allocations - Prefer value returns for small types in hot paths; let the compiler keep them on stack
- Use output parameters (
func fill(dst *T)) when the caller should control allocation - Benchmark before optimizing — the compiler is smarter than you think, and inlining often eliminates expected allocations
Series: Go Memory Model & Internals
← Lesson 3: Method Sets and Addressability | Lesson 5: GC Behavior and Tuning →