Escape Analysis in Go: Stack vs. Heap Allocations Explained

The IDE for professional development in Go

One of the design choices Google made when developing Go was to abstract memory management away from developers so they could focus on what really matters – writing code. Things like escape analysis and garbage collection are thus automatic, and the Go compiler works in almost mystical ways.

That’s one of the best features of Go, so long as your program works. But when memory issues arise, and you need to demystify the process to optimize it, that’s when the perspective shifts and the mystery is no longer so appealing.

In this article, we’ll explain one of the most confusing performance optimization problems – escape analysis, i.e. how the compiler decides what stays on the stack, and what moves to the heap. We’ll cover what escape analysis is and how it works, what the most common escape cases are and how to inspect them, why inspections might be hard to use, and even how GoLand can perhaps help with that.

Escape analysis is a compiler optimization that determines whether a value can be allocated on the stack or must be moved to the heap. In other words, in Golang, the escape analysis process inspects every value your program creates to answer the question: Can this safely live on the stack, or does something outside the current function still need it after the function returns (and therefore it needs to live on the heap)?

The stack is a per-goroutine region where allocations are significantly cheaper and reclaimed automatically when a function returns, so storage happens fast but is short-lived. The heap is a shared, longer-lived memory space that the garbage collector must track and clean up, so it’s more resource-intensive. Escape analysis is the bridge between the two.

A value is said to “escape” when the compiler can’t prove that it’s done being used by the time the function exits, as explained in the Go documentation . For each value, it asks whether any reference to that value can outlive the function that created it. If the answer is no, the value stays on the stack. If the answer is yes – or if the compiler simply can’t prove the answer is no – the value is allocated on the heap to be safe. The classic example is returning a pointer to a local variable – the function ends, but a reference to that variable lives on, so the value can’t sit on the stack frame that’s about to be discarded. It escapes to the heap instead.

It’s worth pointing out here that escape decisions are not set in stone. They can change depending on how you structure your code, the Go version you’re compiling with , as well as on the environment (OS/architecture), compiler settings, and other optimization decisions like inlining. That’s why you can’t assume a value will or will not always escape in a given context – you need to check every time.

Unlike in some other languages, in Go you don’t manually choose between stack and heap allocation the way you might with malloc and free in C. Instead, the compiler makes the call. Go also manages memory safety for you, so as to prevent escaped values from being unsafe.

Many developers stop there and never bother with escape analysis. After all, the documentation says that “ you don’t need to know ”, and if it works, it works, right?

Having said that, you do still have agency and can write code in ways that influence these compiler decisions – in a good way or indeed in a bad way. That’s why an understanding of escape analysis is actually a must-have skill for any Go developer.

Most of the time, when a value escapes to the heap, it’s for one of a handful of recurring reasons. Recognizing these patterns helps you read compiler output faster and tells you whether a given allocation needs investigation or is simply the best way to run your code.

It’s important to note that not every escape is a problem – programs with any degree of complexity will inevitably have things living on the heap. The goal here is to recognize the patterns, not to eliminate them all.

Returning a pointer to a local value is probably the most common cause of an escape. The value is created inside the function, but the caller holds onto a reference after the function returns, so it can’t live on the stack frame that’s being torn down.

func NewUser(name string) *User { u := User{Name: name} // u escapes to the heap return &u } This is safe in Go – the compiler notices that &u outlives NewUser and moves the value to the heap automatically. Whether you should care depends on context. Returning pointers is idiomatic and often the right call for API clarity and readability. The right choice depends on your API design and measured performance impact, not on a blanket rule about avoiding pointers.

Captured variables will escape when a closure or goroutine may outlive the function that created them. The compiler has to assume the captured value is still reachable, so it allocates it on the heap.

func process(data []byte) { go func() { handle(data) // data may escape: the goroutine can outlive the process }() } Goroutines are a frequent source of confusion here, precisely because they can keep running after the parent function has returned. From the compiler’s point of view, anything the goroutine touches might be needed indefinitely, so it plays it safe.

Passing a concrete value through an interface can sometimes lead to a heap allocation. This most often occurs in formatting, logging, and interface-based APIs, where values are boxed into an interface{} (any) before they are handled.

func logValue(v int) { fmt.Println(v) // v is passed as an interface and may escape } However, interface use does not automatically cause heap allocation. Plenty of interface calls don’t allocate at all, and the compiler keeps getting better at this. Treat interfaces as something to check rather than avoid entirely.

Values can escape when they’re stored inside a data structure that outlives the current function. If you put a pointer into a map, a slice, or a struct field, and that container lives longer than the function, the stored value has to live just as long.

type Cache struct { items map[string]*Item } func (c *Cache) Add(key string, it *Item) { c.items[key] = it // it escapes: stored in a structure that outlives the call } The relationship between the container and the value it holds is crucial here. A slice that never leaves the function may keep its contents on the stack; the same slice returned to a caller or stored in a long-lived struct will push its contents to the heap.

The good news is you don’t really need to remember any common reasons for escapes or guess whether a value escaped or not in a particular instant. The Go compiler flags can tell you that, and in fact, inspecting the compiler’s output is the only reliable way to know what’s happening for sure.

The log covers more than just escapes, though. Alongside allocation decisions, the compiler reports inlining details and other diagnostics, so you get a fairly complete picture of the optimization choices it made for a given build. The downside is that the output isn’t precisely user-friendly or easy to navigate, but we will come back to that later.

The Go compiler surfaces escape analysis information through the -gcflags debug flag with the -m option:

go build -gcflags="-m" ./... The -m flag asks the compiler to print its optimization decisions, including whether a value escaped. The output looks roughly like this:

./user.go:6:2: moved to heap: u ./user.go:7:9: &u escapes to heap You can pass -m twice ( -gcflags="-m -m" ) for more detailed reasoning, though that quickly becomes verbose. There are more flag variations, but -gcflags="-m" is the one you’ll probably reach for most.

As you can see, the output is keyed by file, line, and column, and escape analysis can be buried among other comments. This means the real work is mapping each message back to the relevant source code so you can understand it in context.

While compiler flags are the only way to reliably see what decisions the compiler made, they are arguably not the most ergonomic one. The report may be perfectly readable when you work with a small file, but in larger projects and with daily use, it can quickly become frustrating. No wonder then that it’s a heavily underutilized feature of the Go SDK.

A few common pain points have come up in our discussions with Go developers:

None of this makes command-line escape analysis bad. It’s a genuinely powerful diagnostic that’s just not always convenient, especially when you’re trying to answer a focused question inside a large codebase. Because escape analysis has been locked behind obscure compiler flags and hard-to-parse logs, it’s become a niche practice even among experienced Go developers. That’s why our GoLand team has designed a tool that lowers the barrier to entry and bridges the gap between “powerful” and “convenient”.

The GoLand escape analysis support that arrived in the 2026.2 release was built to address the pain points we’d heard from developers. Under the hood, the tool largely does what you would do manually, running the go build command with the -gcflags="-m -m" flag. (To be precise, GoLand runs -gcflags="-m=2 -json=0,<path>" , since we found that storing logs in JSON format provides a more structured and stable output).

But the tool now also adds a layer that parses that raw gcflags output and brings it directly into the editor, so you can stay close to your code while investigating allocation decisions instead of bouncing between the terminal and your files.

The workflow is pretty straightforward. You open the Go Optimization window, choose Escape analysis , pick a scope, and run it.

You can analyze a single file or a whole package – the file-scoped option is handy for tightly focused units of code, such as an individual AWS Lambda handler, where you only care about one function’s allocations.

You can also choose which message types to show (see: How to read escape messages ) and set environment variables for the Go process before running. The most frequently used are compiler flags ( goflags ) – on top of the standard -m , you might also be interested in -N (disables compiler optimizations) and -l (disables function inlining). The values of the GOARCH and GOOS environment variables can also affect your output, as some compiler decisions are target-dependent and can affect inlining, allocation decisions, and the diagnostics reported by gcflags .

Once the analysis finishes, you’ll find the results where they’re most useful:

After you make changes to your code, you can rerun the analysis and compare results in separate tabs to see whether the allocation actually moved off the heap. This is important for iterative work and making sure the changes you make actually move the needle. If you’re already used to profiling your programs, this is a natural extension of that process. And if not, you can read more on how to profile Go code with GoLand to get a more detailed picture.

The console messages are generic. The two you’ll see most often are escapes to heap and moved to heap . Both indicate that a value couldn’t stay on the stack. Others describe inlining and parameter behavior.

Treat these as the diagnostic signals that they are, not as refactoring instructions. A moved to heap message is just information about what the compiler did. Whether it’s worth acting on depends entirely on how that affects performance.

Here are the message types that the GoLand tool surfaces and what they mean – they map directly to the compiler reports:

To read more about this and see examples, go to the GoLand documentation .

Escape analysis matters for performance because heap allocations aren’t free. Every value on the heap generates more work for the garbage collector to track and reclaim, and the allocation itself carries overhead that stack allocation doesn’t. If you reduce unnecessary heap allocations on a hot path, you can potentially meaningfully cut both