Go Reference ยท Concepts
The Go garbage collector
How Go's concurrent garbage collector works and how to tune it with GOGC, GOMEMLIMIT and runtime/debug, with runnable examples that read memory statistics.
Go manages memory with a concurrent, non-moving, tri-color mark-and-sweep garbage collector. It finds heap objects that are no longer reachable from any goroutine stack, global variable or other live object, and frees them. Most of the work runs alongside your program, with only short stop-the-world pauses at the start and end of each cycle, usually well under a millisecond.
The collector is not generational and does not compact the heap. Its speed therefore depends on how much live data it must scan, not on how much garbage there is. Two settings control how often it runs: GOGC (relative growth) and GOMEMLIMIT (absolute ceiling).
debug.SetGCPercent(200) // same as GOGC=200 debug.SetMemoryLimit(1 << 30) // same as GOMEMLIMIT=1GiB
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.
How the two knobs work
- GOGC (default 100): the next collection starts when the heap has grown by GOGC percent over the live heap left by the previous cycle. With 100 and 50 MiB live, the next cycle begins near 100 MiB. Higher values mean fewer collections and more memory; lower values the reverse.
GOGC=offdisables the collector (unless a memory limit is set). - GOMEMLIMIT: a soft limit for the total memory the Go runtime uses (heap, stacks and runtime structures, but not cgo or the OS). As usage approaches the limit the collector runs more often regardless of GOGC. It is a soft limit: if live data exceeds it, the program keeps running, and the GC is capped at about 50% of CPU to avoid a death spiral.
- A typical container setup is
GOGC=offwithGOMEMLIMITat roughly 90% of the container limit, but only for programs whose live heap is well below that limit.
Usage notes
- Pause times are rarely the problem; CPU spent marking is. Reduce the pointer-rich live data, not the garbage: fewer allocations, pointer-free types (
[]byte,[]int) and pooled buffers lower the work. - Tools:
GODEBUG=gctrace=1prints one line per cycle;runtime/metricsandruntime.ReadMemStatsexpose numbers (ReadMemStatsbriefly stops the world, so do not call it in hot paths);go tool pprofheap and allocation profiles show who allocates. runtime.GC()forces a cycle and is meant for tests and benchmarks, not production code.- Finalizers (
runtime.SetFinalizer) are unreliable. Since Go 1.24, preferruntime.AddCleanup, andweak.Pointerfor caches that must not keep objects alive. - A memory "leak" in Go usually means something still references the data: a global map, a slice that holds a large backing array, a goroutine that never ends.
- The OS may report a higher resident size than
HeapAlloc, because freed memory is returned to the OS lazily in the background. - Since Go 1.25 the runtime can also use a new experimental collector (
GOEXPERIMENT=greenteagc); behavior of GOGC and GOMEMLIMIT stays the same.