Skip to content
Tutorials Center
My learning

Topics

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).

Go
debug.SetGCPercent(200)       // same as GOGC=200
debug.SetMemoryLimit(1 << 30) // same as GOMEMLIMIT=1GiB

Try it

Go Watching collections happen

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.

Go Live heap and the memory limit

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=off disables 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=off with GOMEMLIMIT at 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=1 prints one line per cycle; runtime/metrics and runtime.ReadMemStats expose numbers (ReadMemStats briefly stops the world, so do not call it in hot paths); go tool pprof heap 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, prefer runtime.AddCleanup, and weak.Pointer for 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.