Mastering the Green Tea Garbage Collector: A Practical Guide for Go Developers

Overview

Go 1.25 introduces an exciting experimental garbage collector named Green Tea. This new collector is designed to reduce the time your Go programs spend in garbage collection, freeing up CPU cycles for actual work. Early benchmarks show that many workloads experience a 10% reduction in GC pause time, with some workloads seeing up to 40% less! Green Tea is already proven in production at Google, so it's ready for you to try. However, it's still experimental—your feedback will help shape its future. The Go team plans to make it the default in Go 1.26.

This guide will walk you through enabling, testing, and understanding the Green Tea GC. Whether you're optimizing a high-throughput web server or a latency-sensitive microservice, you'll learn how to evaluate and potentially benefit from this new garbage collector.

Prerequisites

Before diving in, make sure you have:

• Go 1.25 or later installed. You can download it from go.dev/dl.
• A working build environment (terminal or IDE) with go build access.
• Basic familiarity with garbage collection concepts (objects, pointers, heap). Not required but helpful.
• A representative Go application to test—preferably one with non-trivial memory allocation.
• No other GOEXPERIMENT flags that conflict (e.g., arenas). Check go env GOEXPERIMENT.

Step-by-Step Instructions

1. Enable Green Tea GC via GOEXPERIMENT

The Green Tea GC is controlled by an environment variable GOEXPERIMENT=greenteagc. You set this when building your application, not at runtime. For a single build:

GOEXPERIMENT=greenteagc go build -o myapp main.go

To make it persistent for a session, export it:

export GOEXPERIMENT=greenteagc
go build -o myapp main.go

Your application binary is now built with the Green Tea GC. You can verify that the experiment is active by running:

go version -m myapp | grep GOEXPERIMENT

Look for GOEXPERIMENT=greenteagc in the output.

2. Build and Run Your Application

Once built, run your application normally. The GC behavior changes internally; you don't need to modify any code. For example:

./myapp --some-args

The same binary can be deployed anywhere—no special runtime environment needed.

3. Measure GC Performance

To see how much Green Tea improves your workload, you'll need to measure GC activity. Use these tools:

• GODEBUG=gctrace=1: Prints GC pause times and memory stats to stderr. Compare with and without Green Tea.
• pprof: Use go tool pprof to profile CPU usage and identify GC overhead.
• Execution tracer: Use go tool trace to visualize GC pauses.

Here's a typical measurement command:

GODEBUG=gctrace=1 ./myapp

Look for lines starting with gc #—the pause time (in milliseconds) is the second field. For a precise comparison, run the same workload multiple times with each GC version (default vs. Green Tea).

4. Interpret the Results

Green Tea focuses on reducing stack scanning and write barriers overhead, especially for programs with many goroutines or high allocation rates. If your workload spends significant time in these areas, you'll see the biggest gains. However, some workloads—especially those with low allocation or that are CPU-bound on non-GC tasks—may see minimal improvement.

Check the gc pause total from GODEBUG=gctrace. If it's 10-40% lower with Green Tea, you're benefiting!

5. Report Your Experiences

The Go team values your feedback. If you encounter issues, file a new issue at go.dev/issue/new. If you see great results, reply to the Green Tea tracking issue (see official Go blog post for exact link). Please include:

• Your Go version (go version)
• Workload description
• Before/after metrics (GC pause times, CPU usage)
• Any observations or problems

Common Mistakes

• Forgetting to rebuild: The GOEXPERIMENT flag only affects the compiled binary. Running the old binary won't use Green Tea. Always rebuild after changing the flag.
• Expecting improvement on every workload: Green Tea isn't a silver bullet. If your app rarely triggers GC (e.g., small heaps, short-lived), you won't see much change. Test realistic scenarios.
• Not measuring correctly: Comparing GC times from a single run can be misleading due to variance. Use multiple runs and statistical tools.
• Conflicting experiments: Using GOEXPERIMENT with multiple comma-separated values may cause issues. Stick to one experiment at a time unless documented otherwise.
• Ignoring runtime trade-offs: While Green Tea reduces CPU in GC, it may increase memory footprint slightly. Monitor RSS too.

Summary

The Green Tea garbage collector in Go 1.25 offers a promising performance boost for many applications, with up to 40% less GC CPU time. It's easy to test: just set GOEXPERIMENT=greenteagc when building. Measure your workload's GC pauses and report your findings to the Go team. Based on current data, Green Tea is on track to become the default in Go 1.26. Try it out today and help shape the future of Go's memory management!