The Go Blog

Type Construction and Cycle Detection

2026-03-24T00:00:00+00:00

The Go Blog

Type Construction and Cycle Detection

Mark Freeman
24 March 2026

Go’s static typing is an important part of why Go is a good fit for production systems that have to be robust and reliable. When a Go package is compiled, it is first parsed—meaning that the Go source code within that package is converted into an abstract syntax tree (or AST). This AST is then passed to the Go type checker.

In this blog post, we’ll dive into a part of the type checker we significantly improved in Go 1.26. How does this change things from a Go user’s perspective? Unless one is fond of arcane type definitions, there’s no observable change here. This refinement was intended to reduce corner cases, setting us up for future improvements to Go. Also, it’s a fun look at something that seems quite ordinary to Go programmers, but has some real subtleties hiding within.

But first, what exactly is type checking? It’s a step in the Go compiler that eliminates whole classes of errors at compile time. Specifically, the Go type checker verifies that:

Types appearing in the AST are valid (for example, a map’s key type must be comparable).
Operations involving those types (or their values) are valid (for example, one can’t add an int and a string).

To accomplish this, the type checker constructs an internal representation for each type it encounters while traversing the AST—a process informally called type construction.

As we’ll soon see, even though Go is known for its simple type system, type construction can be deceptively complex in certain corners of the language.

Type construction

Let’s start by considering a simple pair of type declarations:

type T []U
type U *int

When the type checker is invoked, it first encounters the type declaration for T. Here, the AST records a type definition of a type name T and a type expression []U. T is a defined type; to represent the actual data structure that the type checker uses when constructing defined types, we’ll use a Defined struct.

The Defined struct contains a pointer to the type for the type expression to the right of the type name. This underlying field is relevant for sourcing the type’s underlying type. To help illustrate the type checker’s state, let’s see how walking the AST fills in the data structures, starting with:

At this point, T is under construction, indicated by the color yellow. Since we haven’t evaluated the type expression []U yet—it’s still black—underlying points to nil, indicated by an open arrow.

When we evaluate []U, the type checker constructs a Slice struct, the internal data structure used to represent slice types. Similarly to Defined, it contains a pointer to the element type for the slice. We don’t yet know what the name U refers to, though we expect it to refer to a type. So, again, this pointer is nil. We are left with:

By now you might be getting the gist, so we’ll pick up the pace a bit.

To convert the type name U to a type, we first locate its declaration. Upon seeing that it represents another defined type, we construct a separate Defined for U accordingly. Inspecting the right side of U, we see the type expression *int, which evaluates to a Pointer struct, with the base type of the pointer being the type expression int.

When we evaluate int, something special happens: we get back a predeclared type. Predeclared types are constructed before the type checker even begins walking the AST. Since the type for int is already constructed, there’s nothing for us to do but point to that type.

We now have:

Note that the Pointer type is complete at this point, indicated by the color green. Completeness means that the type’s internal data structure has all of its fields populated and any types pointed to by those fields are complete. Completeness is an important property of a type because it ensures that accessing the internals, or deconstruction, of that type is sound: we have all the information describing the type.

In the image above, the Pointer struct only contains a base field, which points to int. Since int has no fields to populate, it’s “vacuously” complete, making the type for *int complete.

From here, the type checker begins unwinding the stack. Since the type for *int is complete, we can complete the type for U, meaning we can complete the type for []U, and so on for T. When this process ends, we are left with only complete types, as shown below:

The numbering above shows the order in which the types were completed (after the Pointer). Note that the type on the bottom completed first. Type construction is naturally a depth-first process, since completing a type requires its dependencies to be completed first.

Recursive types

With this simple example out of the way, let’s add a bit more nuance. Go’s type system also allows us to express recursive types. A typical example is something like:

type Node struct {
  next *Node
}

If we reconsider our example from above, we can add a bit of recursion by swapping *int for *T like so:

type T []U
type U *T

Now for a trace: let’s start once more with T, but skip ahead to illustrate the effects of this change. As one might suspect from our previous example, the type checker will approach the evaluation of *T with the below state:

The question is what to do with the base type for *T. We have an idea of what T is (a Defined), but it’s currently being constructed (its underlying is still nil).

We simply point the base type for *T to T, even though T is incomplete:

We do this assuming that T will complete when it finishes construction in the future (by pointing to a complete type). When that happens, base will point to a complete type, thus making *T complete.

In the meantime, we’ll begin heading back up the stack:

When we get back to the top and finish constructing T, the “loop” of types will close, completing each type in the loop simultaneously:

Before we considered recursive types, evaluating a type expression always returned a complete type. That was a convenient property because it meant the type checker could always deconstruct (look inside) a type returned from evaluation.

But in the example above, evaluation of T returned an incomplete type, meaning deconstructing T is unsound until it completes. Generally speaking, recursive types mean that the type checker can no longer assume that types returned from evaluation will be complete.

Yet, type checking involves many checks which require deconstructing a type. A classic example is confirming that a map key is comparable, which requires inspecting the underlying field. How do we safely interact with incomplete types like T?

Recall that type completeness is a prerequisite for deconstructing a type. In this case, type construction never deconstructs a type, it merely refers to types. In other words, type completeness does not block type construction here.

Because type construction isn’t blocked, the type checker can simply delay such checks until the end of type checking, when all types are complete (note that the checks themselves also do not block type construction). If a type were to reveal a type error, it makes no difference when that error is reported during type checking—only that it is reported eventually.

With this knowledge in mind, let’s examine a more complex example involving values of incomplete types.

Recursive types and values

Let’s take a brief detour and have a look at Go’s array types. Importantly, array types have a size, which is a constant that is part of the type. Some operations, like the built-in functions unsafe.Sizeof and len can return constants when applied to certain values or expressions, meaning they can appear as array sizes. Importantly, the values passed to those functions can be of any type, even an incomplete type. We call these incomplete values.

Let’s consider this example:

type T [unsafe.Sizeof(T{})]int

In the same way as before, we’ll reach a state like the one below:

To construct the Array, we must calculate its size. From the value expression unsafe.Sizeof(T{}), that’s the size of T. For array types (such as T), calculating their size requires deconstruction: we need to look inside the type to determine the length of the array and size of each element.

In other words, type construction for the Array does deconstruct T, meaning the Array cannot finish construction (let alone complete) before T completes. The “loop” trick that we used earlier—where a loop of types simultaneously completes as the type starting the loop finishes construction—doesn’t work here.

This leaves us in a bind:

T cannot be completed until the Array completes.
The Array cannot be completed until T completes.
They cannot be completed simultaneously (unlike before).

Clearly, this is impossible to satisfy. What is the type checker to do?

Cycle detection

Fundamentally, code such as this is invalid because the size of T cannot be determined without knowing the size of T, regardless of how the type checker operates. This particular instance—cyclic size definition—is part of a class of errors called cycle errors, which generally involve cyclic definition of Go constructs. As another example, consider type T T, which is also in this class, but for different reasons. The process of finding and reporting cycle errors in the course of type checking is called cycle detection.

Now, how does cycle detection work for type T [unsafe.Sizeof(T{})]int? To answer this, let’s look at the inner T{}. Because T{} is a composite literal expression, the type checker knows that its resulting value is of type T. Because T is incomplete, we call the value T{} an incomplete value.

We must be cautious—operating on an incomplete value is only sound if it doesn’t deconstruct the value’s type. For example, type T [unsafe.Sizeof(new(T))]int is sound, since the value new(T) (of type *T) is never deconstructed—all pointers have the same size. To reiterate, it is sound to size an incomplete value of type *T, but not one of type T.

This is because the “pointerness” of *T provides enough type information for unsafe.Sizeof, whereas just T does not. In fact, it’s never sound to operate on an incomplete value whose type is a defined type, because a mere type name conveys no (underlying) type information at all.

Where to do it

Up to now we’ve focused on unsafe.Sizeof directly operating on potentially incomplete values. In type T [unsafe.Sizeof(T{})]int, the call to unsafe.Sizeof is just the “root” of the array length expression. We can readily imagine the incomplete value T{} as an operand in some other value expression.

For example, it could be passed to a function (i.e. type T [unsafe.Sizeof(f(T{}))]int), sliced (i.e. type T [unsafe.Sizeof(T{}[:])]int), indexed (i.e. type T [unsafe.Sizeof(T{}[0])]int), etc. All of these are invalid because they require deconstructing T. For instance, indexing T requires checking the underlying type of T. Because these expressions “consume” potentially incomplete values, let’s call them downstreams. There are many more examples of downstream operators, some of which are not syntactically obvious.

Similarly, T{} is just one example of an expression that “produces” a potentially incomplete value—let’s call these kinds of expressions upstreams:

Comparatively, there are fewer and more syntactically obvious value expressions that might result in incomplete values. Also, it’s rather simple to enumerate these cases by inspecting Go’s syntax definition. For these reasons, it’ll be simpler to implement our cycle detection logic via the upstreams, where potentially incomplete values originate. Below are some examples of them:


type T [unsafe.Sizeof(T(42))]int                // conversion

func f() T
type T [unsafe.Sizeof(f())]int                  // function call

var i interface{}
type T [unsafe.Sizeof(i.(T))]int                // assertion

type T [unsafe.Sizeof(<-(make(<-chan T)))]int   // channel receive

type T [unsafe.Sizeof(make(map[int]T)[42])]int  // map access

type T [unsafe.Sizeof(*new(T))]int              // dereference

// ... and a handful more

For each of these cases, the type checker has extra logic where that particular kind of value expression is evaluated. As soon as we know the type of the resulting value, we insert a simple test that checks that the type is complete.

For instance, in the conversion example type T [unsafe.Sizeof(T(42))]int, there is a snippet in the type checker that resembles:

func callExpr(call *syntax.CallExpr) operand {
  x := typeOrValue(call.Fun)
  switch x.mode() {
  // ... other cases
  case typeExpr:
    // T(), meaning it's a conversion
    T := x.typ()
    // ... handle the conversion, T *is not* safe to deconstruct
  }
}

As soon as we observe that the CallExpr is a conversion to T, we know that the resulting type will be T (assuming no preceding errors). Before we pass back a value (here, an operand) of type T to the rest of the type checker, we need to check for completeness of T:

func callExpr(call *syntax.CallExpr) operand {
  x := typeOrValue(call.Fun)
  switch x.mode() {
  // ... other cases
  case typeExpr:
    // T(), meaning it's a conversion
    T := x.typ()
+   if !isComplete(T) {
+     reportCycleErr(T)
+     return invalid
+   }
    // ... handle the conversion, T *is* safe to deconstruct
  }
}

Instead of returning an incomplete value, we return a special invalid operand, which signals that the call expression could not be evaluated. The rest of the type checker has special handling for invalid operands. By adding this, we prevented incomplete values from “escaping” downstream—both into the rest of the type conversion logic and to downstream operators—and instead reported a cycle error describing the problem with T.

A similar code pattern is used in all other cases, implementing cycle detection for incomplete values.

Conclusion

Systematic cycle detection involving incomplete values is a new addition to the type checker. Before Go 1.26, we used a more complex type construction algorithm, which involved more bespoke cycle detection that didn’t always work. Our new, simpler approach addressed a number of (admittedly esoteric) compiler panics (issues #75918, #76383, #76384, #76478, and more), resulting in a more stable compiler.

As programmers, we’ve become accustomed to features like recursive type definitions and sized array types such that we might overlook the nuance of their underlying complexity. While this post does skip over some finer details, hopefully we’ve conveyed a deeper understanding of (and perhaps appreciation for) the problems surrounding type checking in Go.

Previous article: //go:fix inline and the source-level inliner
Blog Index

//go:fix inline and the source-level inliner

2026-03-10T00:00:00+00:00

The Go Blog

//go:fix inline and the source-level inliner

Alan Donovan
10 March 2026

Go 1.26 contains an all-new implementation of the go fix subcommand, designed to help you keep your Go code up-to-date and modern. For an introduction, start by reading our recent post on the topic. In this post, we’ll look at one particular feature, the source-level inliner.

While go fix has several bespoke modernizers for specific new language and library features, the source-level inliner is the first fruit of our efforts to provide “self-service” modernizers and analyzers. It enables any package author to express simple API migrations and updates in a straightforward and safe way. We’ll first explain what the source-level inliner is and how you can use it, then we’ll dive into some aspects of the problem and the technology behind it.

Source-level inlining

In 2023, we built an algorithm for source-level inlining of function calls in Go. To “inline” a call means to replace the call by a copy of the body of the called function, substituting arguments for parameters. We call it “source-level” inlining because it durably modifies the source code. By contrast, the inlining algorithm found in a typical compiler, including Go’s, applies a similar transformation, but to the compiler’s ephemeral intermediate representation, to generate more efficient code.

If you’ve ever invoked gopls’ “Inline call” interactive refactoring, you’ve used the source-level inliner. (In VS Code, this code action can be found on the “Source Action…” menu.) The before-and-after screenshots below show the effect of inlining the call to sum from the function named six.

The inliner is a crucial building block for a number of source transformation tools. For example, gopls uses it for the “Change signature” and “Remove unused parameter” refactorings because, as we’ll see below, it takes care of many subtle correctness issues that arise when refactoring function calls.

This same inliner is also one of the analyzers in the all-new go fix command. In go fix, it enables self-service API migration and upgrades using a new //go:fix inline directive comment. Let’s take a look at a few examples of how this works and what it can be used for.

Example: renaming `ioutil.ReadFile`

In Go 1.16, the ioutil.ReadFile function, which reads the content of a file, was deprecated in favor of the new os.ReadFile function. In effect, the function was renamed, though of course Go’s compatibility promise prevents us from ever removing the old name.

package ioutil

import "os"

// ReadFile reads the file named by filename…
// Deprecated: As of Go 1.16, this function simply calls [os.ReadFile].
func ReadFile(filename string) ([]byte, error) {
    return os.ReadFile(filename)
}

Ideally, we would like to change every Go program in the world to stop using ioutil.ReadFile and to call os.ReadFile instead. The inliner can help us do that. First we annotate the old function with //go:fix inline. This comment tells the tool that any time it sees a call to this function, it should inline the call.

package ioutil

import "os"

// ReadFile reads the file named by filename…
// Deprecated: As of Go 1.16, this function simply calls [os.ReadFile].
//go:fix inline
func ReadFile(filename string) ([]byte, error) {
    return os.ReadFile(filename)
}

When we run go fix on a file containing a call to ioutil.ReadFile, it applies the replacement:

$ go fix -diff ./...
-import "io/ioutil"
+import "os"

-   data, err := ioutil.ReadFile("hello.txt")
+   data, err := os.ReadFile("hello.txt")

The call has been inlined, in effect replacing a call to one function by a call to another.

Because the inliner replaces a function call by a copy of the body of the called function, not by some arbitrary expression, in principle the transformation should not change the program’s behavior (barring code that inspects the call stack, of course). This differs from other tools that allow for arbitrary rewrites, such as gofmt -r, which are very powerful but need to be watched closely.

For many years now, our Google colleagues on the teams supporting Java, Kotlin, and C++ have been using source-level inliner tools like this. To date, these tools have eliminated millions of calls to deprecated functions in Google’s code base. Users simply add the directives, and wait. During the night, robots quietly prepare, test, and submit batches of code changes across a monorepo of billions of lines of code. If all goes well, by the morning the old code is no longer in use and can be safely deleted. Go’s inliner is a relative newcomer, but it has already been used to prepare more than 18,000 changelists to Google’s monorepo.

Example: fixing API design flaws

With a little creativity, a variety of migrations can be expressed as inlinings. Consider this hypothetical oldmath package:

// Package oldmath is the bad old math package.
package oldmath

// Sub returns x - y.
func Sub(y, x int) int

// Inf returns positive infinity.
func Inf() float64

// Neg returns -x.
func Neg(x int) int

It has several design flaws: the Sub function declares its parameters in the wrong order; the Inf function implicitly prefers one of the two infinities; and the Neg function is redundant with Sub. Fortunately we have a newmath package that avoids these mistakes, and we’d like to get users to switch to it. The first step is to implement the old API in terms of the new package and to deprecate the old functions. Then we add inliner directives:

// Package oldmath is the bad old math package.
package oldmath

import "newmath"

// Sub returns x - y.
// Deprecated: the parameter order is confusing.
//go:fix inline
func Sub(y, x int) int {
    return newmath.Sub(x, y)
}

// Inf returns positive infinity.
// Deprecated: there are two infinite values; be explicit.
//go:fix inline
func Inf() float64 {
    return newmath.Inf(+1)
}

// Neg returns -x.
// Deprecated: this function is unnecessary.
//go:fix inline
func Neg(x int) int {
    return newmath.Sub(0, x)
}

Now, when users of oldmath run the go fix command on their code, it will replace all calls to the old functions by their new counterparts. By the way, gopls has included inline in its analyzer suite for some time, so if your editor uses gopls, the moment you add the //go:fix inline directives you should start seeing a diagnostic at each call site, such as “call of oldmath.Sub should be inlined”, along with a suggested fix that inlines that particular call.

For example, this old code:

import "oldmath"

var nine = oldmath.Sub(1, 10) // diagnostic: "call to oldmath.Sub should be inlined"

will be transformed to:

import "newmath"

var nine = newmath.Sub(10, 1)

Observe that after the fix, the arguments to Sub are in the logical order. This is progress! If you’re in luck, the inliner will succeed at removing every call to the functions in oldmath, perhaps allowing you to delete it as a dependency.

The inline analyzer works on types and constants too. If our oldmath package had originally declared a data type for rational numbers and a constant for π, we could use the following forwarding declarations to migrate them to the newmath package while preserving the behavior of existing code:

package oldmath

//go:fix inline
type Rational = newmath.Rational

//go:fix inline
const Pi = newmath.Pi

Each time the inline analyzer encounters a reference to oldmath.Rational or oldmath.Pi, it will update them to refer instead to newmath.

Under the hood of the inliner

At a glance, source inlining seems straightforward: just replace the call with the body of the callee function, introduce variables for the function parameters, and bind the call arguments to those variables. But handling all of the complexities and corner cases correctly while producing acceptable results is no small technical challenge: the inliner is about 7,000 lines of dense, compiler-like logic. Let’s look at six aspects of the problem that make it so tricky.

1. Parameter elimination

One of the inliner’s most important tasks is to attempt to replace each occurrence of a parameter in the callee by its corresponding argument from the call. In the simplest case, the argument is a trivial literal such as 0 or "", so the replacement is straightforward and the parameter can be eliminated.

//go:fix inline
func show(prefix, item string) {
    fmt.Println(prefix, item)
}

show("", "hello")

fmt.Println("", "hello")

For less trivial literals such as 404 or "go.dev", the replacement is equally straightforward, so long as the parameter appears in the callee at most once. But if it appears multiple times, it would be bad style to sprinkle copies of these magic values throughout the code as it would obscure the relationship between them; a later change to only one of them might create an inconsistency.

In such cases the inliner must tread carefully and emit a more conservative result. Whenever one or more parameters cannot be completely substituted for any reason, the inliner inserts an explicit “parameter binding” declaration:

//go:fix inline
func printPair(before, x, y, after string) {
    fmt.Println(before, x, after)
    fmt.Println(before, y, after)
}

printPair("[", "one", "two", "]")

// a “parameter binding” declaration
var before, after = "[", "]"
fmt.Println(before, "one", after)
fmt.Println(before, "two", after)

2. Side effects

In Go, as in all imperative programming languages, calling a function may have the side effect of updating variables, which in turn may affect the behavior of other functions. Consider the call to add below:

func add(x, y int) int { return y + x }

z = add(f(), g())

A trivial inlining of the call would replace x with f() and y with g(), with this result:

z = g() + f()

But this result is incorrect because evaluation of g() now occurs before f(); if the two functions have side effects, those effects will now be observed in a different order and may affect the result of the expression. Of course, it is bad form to write code that relies on effect ordering among call arguments, but that doesn’t mean people don’t do it, and our tools have to get it right.

So, the inliner must attempt to prove that f() and g() do not have side effects on each other. On success, it can safely proceed with the result above. Otherwise, it must fall back to an explicit parameter binding:

var x = f()
z = g() + x

When considering side effects, it’s not only the argument expressions that matter. Also significant is the order in which parameters are evaluated relative to other code in the callee. Consider this call to add2:

//go:fix inline
func add2(x, y int) int {
    return x + other() + y
}

add2(f(), g())

This time, parameters x and y are used in the same order they are declared, so the substitution f() + other() + g() won’t change the order of effects of f() and g()—but it will change the order of any effects of other() and g(). Furthermore, if the function body uses a parameter within a loop, substitution might change the cardinality of effects.

The inliner uses a novel hazard analysis to model the order of effects in each callee function. Nonetheless, its ability to construct the necessary safety proofs is quite limited. For example, if the calls f() and g() are simple accessors, it would be perfectly safe to call them in either order. Indeed, an optimizing compiler might use its knowledge of the internals of f and g to safely reorder the two calls. But unlike a compiler, which generates object code that reflects the source at a specific moment, the purpose of the inliner is to make permanent changes to the source, so it can’t take advantage of ephemeral details. As an extreme example, consider this start function:

func start() { /* TODO: implement */ }

An optimizing compiler is free to delete each call to start() because it has no effects today, but the inliner is not, because it may become important tomorrow.

In short, the inliner may produce results that—to the informed eye of a project maintainer—are clearly too conservative. In such cases, the fixed code would benefit stylistically from a little manual cleanup.

3. “Fallible” constant expressions

You might imagine (as I once did) that it would always be safe to replace a parameter variable by a constant argument of the same type. Surprisingly, this turns out not to be the case, because some checks previously done at run time would now happen—and fail—at compile time. Consider this call to the index function:

//go:fix inline
func index(s string, i int) byte {
    return s[i]
}

index("", 0)

A naive inliner might replace s with "" and i with 0, resulting in ""[0], but this is not actually a legal Go expression because this particular index is out of bounds for this particular string. Because the expression ""[0] is composed of constants, it is evaluated at compile time, and a program that contains it will not even build. By contrast, the original program would fail only if execution reaches this call to index, which presumably in a working program it does not.

Consequently, the inliner must keep track of all expressions and their operands that might become constant during parameter substitution, triggering additional compile-time checks. It builds a constraint system and attempts to solve it. Each unsatisfied constraint is resolved by adding an explicit binding for the constrained parameters.

4. Shadowing

Typical argument expressions contain one or more identifiers that refer to symbols (variables, functions, and so on) in the caller’s file. The inliner must make sure that each name in the argument expression would refer to the same symbol after parameter substitution; in other words, none of the caller’s names is shadowed in the callee. If this fails, the inliner must again insert parameter bindings, as in this example:

//go:fix inline
func f(val string) {
    x := 123
    fmt.Println(val, x)
}

x := "hello"
f(x)

x := "hello"
{
    // another “parameter binding” declaration
    // to read the caller's x before shadowing it
    var val string = x
    x := 123
    fmt.Println(val, x)
}

Conversely, the inliner must also check that each name in the callee function body would refer to the same thing when it is spliced into the call site. In other words, none of the callee’s names is shadowed or missing in the caller. For missing names, the inliner may need to insert additional imports.

5. Unused variables

When an argument expression has no effects and its corresponding parameter is never used, the expression may be eliminated. However, if the expression contains the last reference to a local variable at the caller, this may cause a compile error because the variable is now unused.

//go:fix inline
func f(_ int) { print("hello") }

x := 42
f(x)

x := 42 // error: unused variable: x
print("hello")

So the inliner must account for references to local variables and avoid removing the last one. (Of course it is still possible that two different inliner fixes each remove the second-to-last reference to a variable, so the two fixes are valid in isolation but not together; see the discussion of semantic conflicts in the previous post. Unfortunately manual cleanup is inevitably required in this case.)

6. Defer

In some cases, it is simply impossible to inline away the call. Consider a call to a function that uses a defer statement: if we were to eliminate the call, the deferred function would execute when the caller function returns, which is too late. All we can safely do when the callee uses defer is to put the body of the callee in a function literal and immediately call it. This function literal, func() { … }(), delimits the lifetime of the defer statement, as in this example:

//go:fix inline
func callee() {
    defer f()
    …
}

callee()

func() {
    defer f()
    …
}()

If you invoke the inliner in gopls, you’ll see that it makes the change shown above and introduces the function literal. This result may be appropriate in an interactive setting, since you are likely to immediately tweak the code (or undo the fix) as you prefer, but it is rarely desirable in a batch tool, so as a matter of policy the analyzer in go fix refuses to inline such “literalized” calls.

An optimizing compiler for “tidiness”

We’ve now seen half a dozen examples of how the inliner handles tricky semantic edge cases correctly. (Many thanks to Rob Findley, Jonathan Amsterdam, Olena Synenka, and Lasse Folger for insights, discussions, reviews, features, and fixes.) By putting all of the smarts into the inliner, users can simply apply an “Inline call” refactoring in their IDE or add a //go:fix inline directive to their own functions and be confident that the resulting code transformations can be applied with only the most cursory review.

Although we have made good progress toward that goal, we have not yet fully attained it, and it is likely that we never will. Consider a compiler. A sound compiler produces correct output for any input and never miscompiles your code; this is the fundamental expectation that every user should have of their compiler. An optimizing compiler produces code carefully chosen for speed without compromising on safety. Similarly, an inliner is a bit like an optimizing compiler whose goal is not speed but tidiness: inlining a call must never change the behavior of your program, and ideally it produces code that is maximally neat and tidy. Unfortunately, an optimizing compiler is provably never done: showing that two different programs are equivalent is an undecidable problem, and there will always be improvements that an expert knows are safe but the compiler cannot prove. So too with the inliner: there will always be cases where the inliner’s output is too fussy or otherwise stylistically inferior to that of a human expert, and there will always be more “tidiness optimizations” to add.

Try it out!

We hope this tour of the inliner gives you a sense of some of the challenges involved, and of our priorities and directions in providing sound, self-service code transformation tools. Please try out the inliner, either interactively in your IDE, or through //go:fix inline directives and the go fix command, and share with us your experiences and any ideas you have for further improvements or new tools.

Next article: Type Construction and Cycle Detection
Previous article: Allocating on the Stack
Blog Index

Allocating on the Stack

2026-02-27T00:00:00+00:00

The Go Blog

Allocating on the Stack

Keith Randall
27 February 2026

We’re always looking for ways to make Go programs faster. In the last 2 releases, we have concentrated on mitigating a particular source of slowness, heap allocations. Each time a Go program allocates memory from the heap, there’s a fairly large chunk of code that needs to run to satisfy that allocation. In addition, heap allocations present additional load on the garbage collector. Even with recent enhancements like Green Tea, the garbage collector still incurs substantial overhead.

So we’ve been working on ways to do more allocations on the stack instead of the heap. Stack allocations are considerably cheaper to perform (sometimes completely free). Moreover, they present no load to the garbage collector, as stack allocations can be collected automatically together with the stack frame itself. Stack allocations also enable prompt reuse, which is very cache friendly.

Stack allocation of constant-sized slices

Consider the task of building a slice of tasks to process:

func process(c chan task) {
    var tasks []task
    for t := range c {
        tasks = append(tasks, t)
    }
    processAll(tasks)
}

Let’s walk through what happens at runtime when pulling tasks from the channel c and adding them to the slice tasks.

On the first loop iteration, there is no backing store for tasks, so append has to allocate one. Because it doesn’t know how big the slice will eventually be, it can’t be too aggressive. Currently, it allocates a backing store of size 1.

On the second loop iteration, the backing store now exists, but it is full. append again has to allocate a new backing store, this time of size 2. The old backing store of size 1 is now garbage.

On the third loop iteration, the backing store of size 2 is full. append again has to allocate a new backing store, this time of size 4. The old backing store of size 2 is now garbage.

On the fourth loop iteration, the backing store of size 4 has only 3 items in it. append can just place the item in the existing backing store and bump up the slice length. Yay! No call to the allocator for this iteration.

On the fifth loop iteration, the backing store of size 4 is full, and append again has to allocate a new backing store, this time of size 8.

And so on. We generally double the size of the allocation each time it fills up, so we can eventually append most new tasks to the slice without allocation. But there is a fair amount of overhead in the “startup” phase when the slice is small. During this startup phase we spend a lot of time in the allocator, and produce a bunch of garbage, which seems pretty wasteful. And it may be that in your program, the slice never really gets large. This startup phase may be all you ever encounter.

If this code was a really hot part of your program, you might be tempted to start the slice out at a larger size, to avoid all of these allocations.

func process2(c chan task) {
    tasks := make([]task, 0, 10) // probably at most 10 tasks
    for t := range c {
        tasks = append(tasks, t)
    }
    processAll(tasks)
}

This is a reasonable optimization to do. It is never incorrect; your program still runs correctly. If the guess is too small, you get allocations from append as before. If the guess is too large, you waste some memory.

If your guess for the number of tasks was a good one, then there’s only one allocation site in this program. The make call allocates a slice backing store of the correct size, and append never has to do any reallocation.

The surprising thing is that if you benchmark this code with 10 elements in the channel, you’ll see that you didn’t reduce the number of allocations to 1, you reduced the number of allocations to 0!

The reason is that the compiler decided to allocate the backing store on the stack. Because it knows what size it needs to be (10 times the size of a task) it can allocate storage for it in the stack frame of process2 instead of on the heap¹. Note that this depends on the fact that the backing store does not escape to the heap inside of processAll.

Stack allocation of variable-sized slices

But of course, hard coding a size guess is a bit rigid. Maybe we can pass in an estimated length?

func process3(c chan task, lengthGuess int) {
    tasks := make([]task, 0, lengthGuess)
    for t := range c {
        tasks = append(tasks, t)
    }
    processAll(tasks)
}

This lets the caller pick a good size for the tasks slice, which may vary depending on where this code is being called from.

Unfortunately, in Go 1.24 the non-constant size of the backing store means the compiler can no longer allocate the backing store on the stack. It will end up on the heap, converting our 0-allocation code to 1-allocation code. Still better than having append do all the intermediate allocations, but unfortunate.

But never fear, Go 1.25 is here!

Imagine you decide to do the following, to get the stack allocation only in cases where the guess is small:

func process4(c chan task, lengthGuess int) {
    var tasks []task
    if lengthGuess <= 10 {
        tasks = make([]task, 0, 10)
    } else {
        tasks = make([]task, 0, lengthGuess)
    }
    for t := range c {
        tasks = append(tasks, t)
    }
    processAll(tasks)
}

Kind of ugly, but it would work. When the guess is small, you use a constant size make and thus a stack-allocated backing store, and when the guess is larger you use a variable size make and allocate the backing store from the heap.

But in Go 1.25, you don’t need to head down this ugly road. The Go 1.25 compiler does this transformation for you! For certain slice allocation locations, the compiler automatically allocates a small (currently 32-byte) slice backing store, and uses that backing store for the result of the make if the size requested is small enough. Otherwise, it uses a heap allocation as normal.

In Go 1.25, process3 performs zero heap allocations, if lengthGuess is small enough that a slice of that length fits into 32 bytes. (And of course that lengthGuess is a correct guess for how many items are in c.)

We’re always improving the performance of Go, so upgrade to the latest Go release and be surprised by how much faster and memory efficient your program becomes!

Stack allocation of append-allocated slices

Ok, but you still don’t want to have to change your API to add this weird length guess. Anything else you could do?

Upgrade to Go 1.26!

func process(c chan task) {
    var tasks []task
    for t := range c {
        tasks = append(tasks, t)
    }
    processAll(tasks)
}

In Go 1.26, we allocate the same kind of small, speculative backing store on the stack, but now we can use it directly at the append site.

On the first loop iteration, there is no backing store for tasks, so append uses a small, stack-allocated backing store as the first allocation. If, for instance, we can fit 4 tasks in that backing store, the first append allocates a backing store of length 4 from the stack.

The next 3 loop iterations append directly to the stack backing store, requiring no allocation.

On the 4th iteration, the stack backing store is finally full and we have to go to the heap for more backing store. But we have avoided almost all of the startup overhead described earlier in this article. No heap allocations of size, 1, 2, and 4, and none of the garbage that they eventually become. If your slices are small, maybe you will never have a heap allocation.

Stack allocation of append-allocated escaping slices

Ok, this is all good when the tasks slice doesn’t escape. But what if I’m returning the slice? Then it can’t be allocated on the stack, right?

Right! The backing store for the slice returned by extract below can’t be allocated on the stack, because the stack frame for extract disappears when extract returns.

func extract(c chan task) []task {
    var tasks []task
    for t := range c {
        tasks = append(tasks, t)
    }
    return tasks
}

But you might think, the returned slice can’t be allocated on the stack. But what about all those intermediate slices that just become garbage? Maybe we can allocate those on the stack?

func extract2(c chan task) []task {
    var tasks []task
    for t := range c {
        tasks = append(tasks, t)
    }
    tasks2 := make([]task, len(tasks))
    copy(tasks2, tasks)
    return tasks2
}

Then the tasks slice never escapes extract2. It can benefit from all of the optimizations described above. Then at the very end of extract2, when we know the final size of the slice, we do one heap allocation of the required size, copy our tasks into it, and return the copy.

But do you really want to write all that additional code? It seems error prone. Maybe the compiler can do this transformation for us?

In Go 1.26, it can!

For escaping slices, the compiler will transform the original extract code to something like this:

func extract3(c chan task) []task {
    var tasks []task
    for t := range c {
        tasks = append(tasks, t)
    }
    tasks = runtime.move2heap(tasks)
    return tasks
}

runtime.move2heap is a special compiler+runtime function that is the identity function for slices that are already allocated in the heap. For slices that are on the stack, it allocates a new slice on the heap, copies the stack-allocated slice to the heap copy, and returns the heap copy.

This ensures that for our original extract code, if the number of items fits in our small stack-allocated buffer, we perform exactly 1 allocation of exactly the right size. If the number of items exceeds the capacity of our small stack-allocated buffer, we do our normal doubling-allocation once the stack-allocated buffer overflows.

The optimization that Go 1.26 does is actually better than the hand-optimized code, because it does not require the extra allocation+copy that the hand-optimized code always does at the end. It requires the allocation+copy only in the case that we’ve exclusively operated on a stack-backed slice up to the return point.

We do pay the cost for a copy, but that cost is almost completely offset by the copies in the startup phase that we no longer have to do. (In fact, the new scheme at worst has to copy one more element than the old scheme.)

Wrapping up

Hand optimization can still be beneficial, especially if you have a good estimate of the slice size ahead of time. But hopefully the compiler will now catch a lot of the simple cases for you and allow you to focus on the remaining ones that really matter.

There are a lot of details that the compiler needs to ensure to get all these optimizations right. If you think that one of these optimizations is causing correctness or (negative) performance issues for you, you can turn them off with -gcflags=all=-d=variablemakehash=n. If turning these optimizations off helps, please file an issue so we can investigate.

Footnotes

¹ Go stacks do not have any alloca-style mechanism for dynamically-sized stack frames. All Go stack frames are constant sized.

Next article: //go:fix inline and the source-level inliner
Previous article: Using go fix to modernize Go code
Blog Index

Using go fix to modernize Go code

2026-02-17T00:00:00+00:00

The Go Blog

Using go fix to modernize Go code

Alan Donovan
17 February 2026

The 1.26 release of Go this month includes a completely rewritten go fix subcommand. Go fix uses a suite of algorithms to identify opportunities to improve your code, often by taking advantage of more modern features of the language and library. In this post, we’ll first show you how to use go fix to modernize your Go codebase. Then in the second section we’ll dive into the infrastructure behind it and how it is evolving. Finally, we’ll present the theme of “self-service” analysis tools to help module maintainers and organizations encode their own guidelines and best practices.

Running go fix

The go fix command, like go build and go vet, accepts a set of patterns that denote packages. This command fixes all packages beneath the current directory:

$ go fix ./...

On success, it silently updates your source files. It discards any fix that touches generated files since the appropriate fix in that case is to the logic of the generator itself. We recommend running go fix over your project each time you update your build to a newer Go toolchain release. Since the command may fix hundreds of files, start from a clean git state so that the change consists only of edits from go fix; your code reviewers will thank you.

To preview the changes the above command would have made, use the -diff flag:

$ go fix -diff ./...
--- dir/file.go (old)
+++ dir/file.go (new)
-                       eq := strings.IndexByte(pair, '=')
-                       result[pair[:eq]] = pair[1+eq:]
+                       before, after, _ := strings.Cut(pair, "=")
+                       result[before] = after
…

You can list the available fixers by running this command:

$ go tool fix help
…
Registered analyzers:
    any          replace interface{} with any
    buildtag     check //go:build and // +build directives
    fmtappendf   replace []byte(fmt.Sprintf) with fmt.Appendf
    forvar       remove redundant re-declaration of loop variables
    hostport     check format of addresses passed to net.Dial
    inline       apply fixes based on 'go:fix inline' comment directives
    mapsloop     replace explicit loops over maps with calls to maps package
    minmax       replace if/else statements with calls to min or max
…

Adding the name of a particular analyzer shows its complete documentation:

$ go tool fix help forvar

forvar: remove redundant re-declaration of loop variables

The forvar analyzer removes unnecessary shadowing of loop variables.
Before Go 1.22, it was common to write `for _, x := range s { x := x ... }`
to create a fresh variable for each iteration. Go 1.22 changed the semantics
of `for` loops, making this pattern redundant. This analyzer removes the
unnecessary `x := x` statement.

This fix only applies to `range` loops.

By default, the go fix command runs all analyzers. When fixing a large project it may reduce the burden of code review if you apply fixes from the most prolific analyzers as separate code changes. To enable only specific analyzers, use the flags matching their names. For example, to run just the any fixer, specify the -any flag. Conversely, to run all the analyzers except selected ones, negate the flags, for instance -any=false.

As with go build and go vet, each run of the go fix command analyzes only a specific build configuration. If your project makes heavy use of files tagged for different CPUs or platforms, you may wish to run the command more than once with different values of GOARCH and GOOS for better coverage:

$ GOOS=linux   GOARCH=amd64 go fix ./...
$ GOOS=darwin  GOARCH=arm64 go fix ./...
$ GOOS=windows GOARCH=amd64 go fix ./...

Running the command more than once also provides opportunities for synergistic fixes, as we’ll see below.

Modernizers

The introduction of generics in Go 1.18 marked the end of an era of very few changes to the language spec and the start of a period of more rapid—though still careful—change, especially in the libraries. Many of the trivial loops that Go programmers routinely write, such as to gather the keys of a map into a slice, can now be conveniently expressed as a call to a generic function such as maps.Keys. Consequently these new features create many opportunities to simplify existing code.

In December 2024, during the frenzied adoption of LLM coding assistants, we became aware that such tools tended—unsurprisingly—to produce Go code in a style similar to the mass of Go code used during training, even when there were newer, better ways to express the same idea. Less obviously, the same tools often refused to use the newer ways even when directed to do so in general terms such as “always use the latest idioms of Go 1.25.” In some cases, even when explicitly told to use a feature, the model would deny that it existed. (See my 2025 GopherCon talk for more exasperating details.) To ensure that future models are trained on the latest idioms, we need to ensure that these idioms are reflected in the training data, which is to say the global corpus of open-source Go code.

Over the past year, we have built dozens of analyzers to identify opportunities for modernization. Here are three examples of the fixes they suggest:

minmax replaces an if statement by a use of Go 1.21’s min or max functions:

x := f()
if x < 0 {
    x = 0
}
if x > 100 {
    x = 100
}

x := min(max(f(), 0), 100)

rangeint replaces a 3-clause for loop by a Go 1.22 range-over-int loop:

for i := 0; i < n; i++ {
    f()
}

for range n {
    f()
}

stringscut (whose -diff output we saw earlier) replaces uses of strings.Index and slicing by Go 1.18’s strings.Cut:

i := strings.Index(s, ":")
if i >= 0 {
     return s[:i]
}

before, _, ok := strings.Cut(s, ":")
if ok {
    return before
}

These modernizers are included in gopls, to provide instant feedback as you type, and in go fix, so that you can modernize several entire packages at once in a single command. In addition to making code clearer, modernizers may help Go programmers learn about newer features. As part of the process of approving each new change to the language and standard library, the proposal review group now considers whether it should be accompanied by a modernizer. We expect to add more modernizers with each release.

Example: a modernizer for Go 1.26’s new(expr)

Go 1.26 includes a small but widely useful change to the language specification. The built-in new function creates a new variable and returns its address. Historically, its sole argument was required to be a type, such as new(string), and the new variable was initialized to its “zero” value, such as "". In Go 1.26, the new function may be called with any value, causing it to create a variable initialized to that value, avoiding the need for an additional statement. For example:

ptr := new(string)
*ptr = "go1.25"

ptr := new("go1.26")

This feature filled a gap that had been discussed for over a decade and resolved one of the most popular proposals for a change to the language. It is especially convenient in code that uses a pointer type *T to indicate an optional value of type T, as is common when working with serialization packages such as json.Marshal or protocol buffers. This is such a common pattern that people often capture it in a helper, such as the newInt function below, saving the caller from the need to break out of an expression context to introduce additional statements:

type RequestJSON struct {
    URL      string
    Attempts *int  // (optional)
}

data, err := json.Marshal(&RequestJSON{
    URL:      url,
    Attempts: newInt(10),
})

func newInt(x int) *int { return &x }

Helpers such as newInt are so frequently needed with protocol buffers that the proto API itself provides them as proto.Int64, proto.String, and so on. But Go 1.26 makes all these helpers unnecessary:

data, err := json.Marshal(&RequestJSON{
    URL:      url,
    Attempts: new(10),
})

To help you take advantage of this feature, the go fix command now includes a fixer, newexpr, that recognizes “new-like” functions such as newInt and suggests fixes to replace the function body with return new(x) and to replace every call, whether in the same package or an importing package, with a direct use of new(expr).

To avoid introducing premature uses of new features, modernizers offer fixes only in files that require at least the minimum appropriate version of Go (1.26 in this instance), either through a go 1.26 directive in the enclosing go.mod file or a //go:build go1.26 build constraint in the file itself.

Run this command to update all calls of this form in your source tree:

$ go fix -newexpr ./...

At this point, with luck, all of your newInt-like helper functions will have become unused and may be safely deleted (assuming they aren’t part of a stable published API). A few calls may remain where it would be unsafe to suggest a fix, such as when the name new is locally shadowed by another declaration. You can also use the deadcode command to help identify unused functions.

Synergistic fixes

Applying one modernization may create opportunities to apply another. For example, this snippet of code, which clamps x to the range 0–100, causes the minmax modernizer to suggest a fix to use max. Once that fix is applied it suggests a second fix, this time to use min.

x := f()
if x < 0 {
    x = 0
}
if x > 100 {
    x = 100
}

x := min(max(f(), 0), 100)

Synergies may also occur between different analyzers. For example, a common mistake is to repeatedly concatenate strings within a loop, resulting in quadratic time complexity—a bug and a potential vector for a denial-of-service attack. The stringsbuilder modernizer recognizes the problem and suggests using Go 1.10’s strings.Builder:

s := ""
for _, b := range bytes {
    s += fmt.Sprintf("%02x", b)
}
use(s)

var s strings.Builder
for _, b := range bytes {
    s.WriteString(fmt.Sprintf("%02x", b))
}
use(s.String())

Once this fix is applied, a second analyzer may recognize that the WriteString and Sprintf operations can be combined as fmt.Fprintf(&s, "%02x", b), which is both cleaner and more efficient, and offer a second fix. (This second analyzer is QF1012 from Dominik Honnef’s staticcheck, which is already enabled in gopls but not yet in go fix, though we plan to add staticcheck analyzers to the go command starting in Go 1.27.)

Consequently, it may be worth running go fix more than once until it reaches a fixed point; twice is usually enough.

Merging fixes and conflicts

A single run of go fix may apply dozens of fixes within the same source file. All fixes are conceptually independent, analogous to a set of git commits with the same parent. The go fix command uses a simple three-way merge algorithm to reconcile the fixes in sequence, analogous to the task of merging a set of git commits that edit the same file. If a fix conflicts with the list of edits accumulated so far, it is discarded, and the tool issues a warning that some fixes were skipped and that the tool should be run again.

This reliably detects syntactic conflicts arising from overlapping edits, but another class of conflict is possible: a semantic conflict occurs when two changes are textually independent but their meanings are incompatible. As an example consider two fixes that each remove the second-to-last use of a local variable: each fix is fine by itself, but when both are applied together the local variable becomes unused, and in Go that’s a compilation error. Neither fix is responsible for removing the variable declaration, but someone has to do it, and that someone is the user of go fix.

A similar semantic conflict arises when a set of fixes causes an import to become unused. Because this case is so common, the go fix command applies a final pass to detect unused imports and remove them automatically.

Semantic conflicts are relatively rare. Fortunately they usually reveal themselves as compilation errors, making them impossible to overlook. Unfortunately, when they happen, they do demand some manual work after running go fix.

Let’s now delve into the infrastructure beneath these tools.

The Go analysis framework

Since the earliest days of Go, the go command has had two subcommands for static analysis, go vet and go fix, each with its own suite of algorithms: “checkers” and “fixers”. A checker reports likely mistakes in your code, such as passing a string instead of an integer as the operand of a fmt.Printf("%d") conversion. A fixer safely edits your code to fix a bug or to express the same thing in a better way, perhaps more clearly, concisely, or efficiently. Sometimes the same algorithm appears in both suites when it can both report a mistake and safely fix it.

In 2017 we redesigned the then-monolithic go vet program to separate the checker algorithms (now called “analyzers”) from the “driver”, the program that runs them; the result was the Go analysis framework. This separation enables an analyzer to be written once then run in a diverse range of drivers for different environments, such as:

unitchecker, which turns a suite of analyzers into a subcommand that can be run by the go command’s scalable incremental build system, analogous to a compiler in go build. This is the basis of go fix and go vet.
nogo, the analogous driver for alternative build systems such as Bazel and Blaze.
singlechecker, which turns an analyzer into a standalone command that loads, parses, and type-checks a set of packages (perhaps a whole program) and then analyzes them. We often use it for ad hoc experiments and measurements over the module mirror (proxy.golang.org) corpus.
multichecker, which does the same thing for a suite of analyzers with a ‘swiss-army knife’ CLI.
gopls, the language server behind VS Code and other editors, which provides real-time diagnostics from analyzers after each editor keystroke.
the highly configurable driver used by the staticcheck tool. (Staticcheck also provides a large suite of analyzers that can be run in other drivers.)
Tricorder, the batch static analysis pipeline used by Google’s monorepo and integrated with its code review system.
gopls’ MCP server, which makes diagnostics available to LLM-based coding agents, providing more robust “guardrails”.
analysistest, the analysis framework’s test harness.

One benefit of the framework is its ability to express helper analyzers that don’t report diagnostics or suggest fixes of their own but instead compute some intermediate data structure that may be useful to many other analyzers, amortizing the costs of its construction. Examples include control-flow graphs, the SSA representation of function bodies, and data structures for optimized AST navigation.

Another benefit of the framework is its support for making deductions across packages. An analyzer can attach a “fact” to a function or other symbol so that information learned while analyzing the function’s body can be used when later analyzing a call to the function, even if the call appears in another package or the later analysis occurs in a different process. This makes it easy to define scalable interprocedural analyses. For example, the printf checker can tell when a function such as log.Printf is really just a wrapper around fmt.Printf, so it knows that calls to log.Printf should be checked in a similar manner. This process works by induction, so the tool will also check calls to further wrappers around log.Printf, and so on. An example of an analyzer that makes heavy use of facts is Uber’s nilaway, which reports potential mistakes resulting in nil pointer dereferences.

The process of “separate analysis” in go fix is analogous to the process of separate compilation in go build. Just as the compiler builds packages starting from the bottom of the dependency graph and passing type information up to importing packages, the analysis framework works from the bottom of the dependency graph up, passing facts (and types) up to importing packages.

In 2019, as we started developing gopls, the language server for Go, we added the ability for an analyzer to suggest a fix when reporting a diagnostic. The printf analyzer, for example, offers to replace fmt.Printf(msg) with fmt.Printf("%s", msg) to avoid misformatting should the dynamic msg value contain a % symbol. This mechanism has become the basis for many of the quick fixes and refactoring features of gopls.

While all these developments were happening to go vet, go fix remained stuck as it was back before the Go compatibility promise, when early adopters of Go used it to maintain their code during the rapid and sometimes incompatible evolution of the language and libraries.

The Go 1.26 release brings the Go analysis framework to go fix. The go vet and go fix commands have converged and are now almost identical in implementation. The only differences between them are the criteria for the suites of algorithms they use, and what they do with computed diagnostics. Go vet analyzers must detect likely mistakes with low false positives; their diagnostics are reported to the user. Go fix analyzers must generate fixes that are safe to apply without regression in correctness, performance, or style; their diagnostics may not be reported, but the fixes are directly applied. Aside from this difference of emphasis, the task of developing a fixer is no different from that of developing a checker.

Improving analysis infrastructure

As the number of analyzers in go vet and go fix continues to grow, we have been investing in infrastructure both to improve the performance of each analyzer and to make it easier to write each new analyzer.

For example, most analyzers start by traversing the syntax trees of each file in the package looking for a particular kind of node such as a range statement or function literal. The existing inspector package makes this scan efficient by pre-computing a compact index of a complete traversal so that later traversals can quickly skip subtrees that don’t contain any nodes of interest. Recently we extended it with the Cursor datatype to allow flexible and efficient navigation between nodes in all four cardinal directions—up, down, left, and right, similar to navigating the elements of an HTML DOM—making it easy and efficient to express a query such as “find each go statement that is the first statement of a loop body”:

    var curFile inspector.Cursor = ...

    // Find each go statement that is the first statement of a loop body.
    for curGo := range curFile.Preorder((*ast.GoStmt)(nil)) {
        kind, index := curGo.ParentEdge()
        if kind == edge.BlockStmt_List && index == 0 {
            switch curGo.Parent().ParentEdgeKind() {
            case edge.ForStmt_Body, edge.RangeStmt_Body:
                ...
            }
        }
    }

Many analyzers start by searching for calls to a specific function, such as fmt.Printf. Function calls are among the most numerous expressions in Go code, so rather than search every call expression and test whether it is a call to fmt.Printf, it is much more efficient to pre-compute an index of symbol references, which is done by typeindex and its [email protected]/internal/analysis/typeindex" rel="noreferrer" target="_blank">helper analyzer. Then the calls to fmt.Printf can be enumerated directly, making the cost proportional to the number of calls instead of to the size of the package. For an analyzer such as hostport that seeks an infrequently used symbol (net.Dial), this can easily make it 1,000× faster.

Some other infrastructural improvements over the past year include:

a dependency graph of the standard library that analyzers can consult to avoid introducing import cycles. For example, we can’t introduce a call to strings.Cut in a package that is itself imported by strings.
support for querying the effective Go version of a file as determined by the enclosing go.mod file and build tags, so that analyzers don’t insert uses of features that are “too new”.
a richer library of refactoring primitives (e.g. “delete this statement”) that correctly handle adjacent comments and other tricky edge cases.

We have come a long way, but there remains much to do. Fixer logic can be tricky to get right. Since we expect users to apply hundreds of suggested fixes with only cursory review, it’s critical that fixers are correct even in obscure edge cases. As just one example (see my GopherCon talk for several more), we built a modernizer that replaces calls such as append([]string{}, slice...) by the clearer slices.Clone(slice) only to discover that, when slice is empty, the result of Clone is nil, a subtle behavior change that in rare cases can cause bugs; so we had to exclude that modernizer from the go fix suite.

Some of these difficulties for authors of analyzers can be ameliorated with better documentation (both for humans and LLMs), particularly checklists of surprising edge cases to consider and test. A pattern-matching engine for syntax trees, similar to those in staticcheck and Tree Sitter, could simplify the fiddly task of efficiently identifying the locations that need fixing. A richer library of operators for computing accurate fixes would help avoid common mistakes. A better test harness would let us check that fixes don’t break the build, and preserve dynamic properties of the target code. These are all on our roadmap.

The “self-service” paradigm

More fundamentally, we are turning our attention in 2026 to a “self-service” paradigm.

The newexpr analyzer we saw earlier is a typical modernizer: a bespoke algorithm tailored to a particular feature. The bespoke model works well for features of the language and standard library, but it doesn’t really help update uses of third-party packages. Although there’s nothing to stop you from writing a modernizer for your own public APIs and running it on your own project, there’s no automatic way to get users of your API to run it too. Your modernizer probably wouldn’t belong in gopls or the go vet suite unless your API is particularly widely used across the Go ecosystem. Even in that case you would have to obtain code reviews and approvals and then wait for the next release.

Under the self-service paradigm, Go programmers would be able to define modernizations for their own APIs that their users can apply without all the bottlenecks of the current centralized paradigm. This is especially important as the Go community and global Go corpus are growing much faster than the ability of our team to review analyzer contributions.

The go fix command in Go 1.26 includes a preview of the first fruits of this new paradigm: the annotation-driven source-level inliner, which is described in a follow-up post. In the coming year, we plan to investigate two more approaches within this paradigm.

First, we will be exploring the possibility of dynamically loading modernizers from the source tree and securely executing them, either in gopls or go fix. In this approach a package that provides an API for, say, a SQL database could additionally provide a checker for misuses of the API, such as SQL injection vulnerabilities or failure to handle critical errors. The same mechanism could be used by project maintainers to encode internal housekeeping rules, such as avoiding calls to certain problematic functions or enforcing stronger coding disciplines in critical parts of the code.

Second, many existing checkers can be informally described as “don’t forget to X after you Y!”, such as “close the file after you open it”, “cancel the context after you create it”, “unlock the mutex after you lock it”, “break out of the iterator loop after yield returns false”, and so on. What such checkers have in common is that they enforce certain invariants on all execution paths. We plan to explore generalizations and unifications of these control-flow checkers so that Go programmers can easily apply them to new domains, without complex analytical logic, simply by annotating their own code.

We hope that these new tools will save you effort during maintenance of your Go projects and help you learn about and benefit from newer features sooner. Please try out go fix on your projects and report any problems you find, and do share any ideas you have for new modernizers, fixers, checkers, or self-service approaches to static analysis.

Next article: Allocating on the Stack
Previous article: Go 1.26 is released
Blog Index

Go 1.26 is released

2026-02-10T00:00:00+00:00

The Go Blog

Go 1.26 is released

Carlos Amedee, on behalf of the Go team
10 February 2026

Today the Go team is pleased to release Go 1.26. You can find its binary archives and installers on the download page.

Language changes

Go 1.26 introduces two significant refinements to the language syntax and type system.

First, the built-in new function, which creates a new variable, now allows its operand to be an expression, specifying the initial value of the variable.

A simple example of this change means that code such as this:

x := int64(300)
ptr := &x

Can be simplified to:

ptr := new(int64(300))

Second, generic types may now refer to themselves in their own type parameter list. This change simplifies the implementation of complex data structures and interfaces.

Performance improvements

The previously experimental Green Tea garbage collector is now enabled by default.

The baseline cgo overhead has been reduced by approximately 30%.

The compiler can now allocate the backing store for slices on the stack in more situations, which improves performance.

Tool improvements

The go fix command has been completely rewritten to use the Go analysis framework, and now includes a couple dozen “modernizers”, analyzers that suggest safe fixes to help your code take advantage of newer features of the language and standard library. It also includes the inline analyzer, which attempts to inline all calls to each function annotated with a //go:fix inline directive. Two upcoming blog posts will address these features in more detail.

More improvements and changes

Go 1.26 introduces many improvements over Go 1.25 across its tools, the runtime, compiler, linker, and the standard library. This includes the addition of three new packages: crypto/hpke, crypto/mlkem/mlkemtest, and testing/cryptotest. There are port-specific changes and GODEBUG settings updates.

Some of the additions in Go 1.26 are in an experimental stage and become exposed only when you explicitly opt in. Notably:

An experimental simd/archsimd package provides access to “single instruction, multiple data” (SIMD) operations.
An experimental runtime/secret package provides a facility for securely erasing temporaries used in code that manipulates secret information, typically cryptographic in nature.
An experimental goroutineleak profile in the runtime/pprof package that reports leaked goroutines.

These experiments are all expected to be generally available in a future version of Go. We encourage you to try them out ahead of time. We really value your feedback!

Please refer to the Go 1.26 Release Notes for the complete list of additions, changes, and improvements in Go 1.26.

Over the next few weeks, follow-up blog posts will cover some of the topics relevant to Go 1.26 in more detail. Check back later to read those posts.

Thanks to everyone who contributed to this release by writing code, filing bugs, trying out experimental additions, sharing feedback, and testing the release candidates. Your efforts helped make Go 1.26 as stable as possible. As always, if you notice any problems, please file an issue.

We hope you enjoy using the new release!

Next article: Using go fix to modernize Go code
Previous article: Results from the 2025 Go Developer Survey
Blog Index

Results from the 2025 Go Developer Survey

2026-01-21T00:00:00+00:00

The Go Blog

Results from the 2025 Go Developer Survey

Todd Kulesza, on behalf of the Go team
21 January 2026

Hello! In this article we’ll discuss the results of the 2025 Go Developer Survey, conducted during September 2025.

Thank you to the 5,379 Go developers who responded to our survey invitation this year. Your feedback helps both the Go team at Google and the wider Go community understand the current state of the Go ecosystem and prioritize projects for the year ahead.

Our three biggest findings are:

Broadly speaking, Go developers asked for help with identifying and applying best practices, making the most of the standard library, and expanding the language and built-in tooling with more modern capabilities.
Most Go developers are now using AI-powered development tools when seeking information (e.g., learning how to use a module) or toiling (e.g., writing repetitive blocks of similar code), but their satisfaction with these tools is middling due, in part, to quality concerns.
A surprisingly high proportion of respondents said they frequently need to review documentation for core go subcommands, including go build, go run, and go mod, suggesting meaningful room for improvement with the go command’s help system.

Read on for the details about these findings, and much more.

Sections

Who did we hear from?

Most survey respondents self-identified as professional developers (87%) who use Go for their primary job (82%). A large majority also uses Go for personal or open-source projects (72%). Most respondents were between 25 – 45 years old (68%) with at least six years of professional development experience (75%). Going deeper, 81% of respondents told us they had more professional development experience than Go-specific experience, strong evidence that Go is usually not the first language developers work with. In fact, one of the themes that repeatedly surfaced during this year’s survey analysis seems to stem from this fact: when the way to do a task in Go is substantially different from a more familiar language, it creates friction for developers to first learn the new (to them) idiomatic Go pattern, and then to consistently recall these differences as they continue to work with multiple languages. We’ll return to this theme later.

The single most common industry respondents work in was “Technology” (46%), but a majority of respondents work outside of the tech industry (54%). We saw representation of all sizes of organizations, with a bare majority working somewhere with 2 – 500 employees (51%), 9% working alone, and 30% working at enterprises of over 1,000 employees. As in prior years, a majority of responses come from North America and Europe.

This year we observed a decrease in the proportion of respondents who said they were fairly new to Go, having worked with it for less than one year (13%, vs. 21% in 2024). We suspect this is related to industry-wide declines in entry-level software engineering roles; we commonly hear from people that they learned Go for a specific job, so a downturn in hiring would be expected to reduce the number of developers learning Go in that year. This hypothesis is further supported by our finding that over 80% of respondents learned Go after beginning their professional career.

Other than the above, we found no significant changes in other demographics since our 2024 survey.

How do people feel about Go?

The vast majority of respondents (91%) said they felt satisfied while working with Go. Almost ⅔ were “very satisfied”, the highest rating. Both of these metrics are incredibly positive, and have been stable since we began asking this question in 2019. The stability over time is really what we monitor from this metric — we view it as a lagging indicator, meaning by the time this satisfaction metric shows a meaningful change, we would expect to already have seen earlier signals from issue reports, mailing lists, or other community feedback.

Why were respondents so positive about Go? Looking at open-text responses to several different survey questions suggests that it’s the gestalt, rather than any one thing. These folks are telling us that they find tremendous value in Go as a holistic platform. That doesn’t mean it supports all programming domains equally well (it surely does not), but that developers’ value the domains it does nicely support via stdlib and built-in tooling.

Below are some representative quotations from respondents. To provide context for each quote, we also identify the satisfaction level, years of experience with Go, and industry of the respondent.

“Go is by far my favorite language; other languages feel far too complex and unhelpful. The fact that Go is comparatively small, simple, with fewer bells and whistles plays a massive role in making it such a good long-lasting foundation for building programs with it. I love that it scales well to being used by a single programmer and in large teams.” — Very satisfied / 10+ years / Technology company

“The entire reason I use Go is the great tooling and standard library. I’m very thankful to the team for focusing on great HTTP, crypto, math, sync, and other tools that make developing service-oriented applications easy and reliable.” — Very satisfied / 10+ years / Energy company

“[The] Go ecosystem is the reason why I really like the programming language. There are a lot of npm issues lately but not with Go.” — Very satisfied / 3 – 10 years / Financial services

This year we also asked about the other languages that people use. Survey respondents said that besides Go, they enjoy working with Python, Rust, and TypeScript, among a long tail of other languages. Some shared characteristics of these languages align with common points of friction reported by Go developers, including areas like error handling, enums, and object-oriented design patterns. For example, when we sum the proportion of respondents who said their next-favorite language included one of the following factors, we found that majorities of respondents enjoy using languages with inheritance, type-safe enums, and exceptions, with only a bare majority of these languages including a static type system by default.

Concept or feature	Proportion of respondents
Inheritance	71%
Type-safe enums	65%
Exceptions	60%
Static typing	51%

We think this is important because it reveals the larger environment in which developers operate — it suggests that people need to use different design patterns for fairly mundane tasks, depending on the language of the codebase they’re currently working on. This leads to additional cognitive load and confusion, not only among developers new to Go (who must learn idiomatic Go design patterns), but also among the many developers who work in multiple codebases or projects. One way to alleviate this additional load is context-specific guidance, such as a tutorial on “Error handling in Go for Java developers”. There may even be opportunities to build some of this guidance into code analyzers, making it easier to surface directly in an IDE.

This year we asked the Go community to share their sentiment towards the Go project itself. These results were quite different from the 91% satisfaction rate we discussed above, and point to areas the Go Team plans to invest our energy during 2026. In particular, we want to encourage more contributors to get involved, and ensure the Go Team accurately understands the challenges Go developers currently face. We hope this focus, in turn, will help to increase developer trust in both the Go project and the Go Team leadership. As one respondent explained the problem:

“Now that the founding first generation of Go Team members [are] not involved much anymore in the decision making, I am a bit worried about the future of Go in terms of quality of maintenance, and its balanced decisions so far wrt to changes in the language and std lib. More presence in form of talks [by] the new core team members about the current state and future plans might be helpful to strengthen trust.” — Very satisfied / 10+ years / Technology company

What are people building with Go?

We revised this list of “what types of things do you build with Go?” from 2024 with the intent of more usefully teasing apart what people are building with Go, and avoid confusion around evolving terms like “agents”. Respondent’s top use cases remain CLIs and API services, with no meaningful change in either since 2024. In fact, a majority of respondents (55%) said they build both CLIs and API services with Go. Over ⅓ of respondents specifically build cloud infrastructure tooling (a new category), and 11% work with ML models, tools, or agents (an expanded category). Unfortunately embedded use cases were left off of the revised list, but we’ll fix this for next year’s survey.

Most respondents said they are not currently building AI-powered features into the Go software they work on (78%), with ⅔ reporting that their software does not use AI functionality at all (66%). This appears to be a decrease in production-related AI usage year-over-year; in 2024, 59% of respondents were not involved in AI feature work, while 39% indicated some level of involvement. That marks a shift of 14 points away from building AI-powered systems among survey respondents, and may reflect some natural pullback from the early hype around AI-powered applications: it’s plausible that lots of folks tried to see what they could do with this technology during its initial rollout, with some proportion deciding against further exploration (at least at this time).

Among respondents who are building AI- or LLM-powered functionality, the most common use case was to create summaries of existing content (45%). Overall, however, there was little difference between most uses, with between 28% – 33% of respondents adding AI functionality to support classification, generation, solution identification, chatbots, and software development.

What are the biggest challenges facing Go developers?

One of the most helpful types of feedback we receive from developers are details about the challenges people run into while working with Go. The Go Team considers this information holistically and over long time horizons, because there is often tension between improving Go’s rougher edges and keeping the language and tooling consistent for developers. Beyond technical factors, every change also incurs some cost in terms of developer attention and cognitive disruption. Minimizing disruption may sound a bit dull or boring, but we view this as an important strength of Go. As Russ Cox wrote in 2023, “Boring is good… Boring means being able to focus on your work, not on what’s different about Go.”.

In that spirit, this year’s top challenges are not radically different from last year’s. The top three frustrations respondents reported were “Ensuring our Go code follows best practices / Go idioms” (33% of respondents), “A feature I value from another language isn’t part of Go” (28%), and “Finding trustworthy Go modules and packages” (26%). We examined open-text responses to better understand what people meant. Let’s take a minute to dig into each.

Respondents who were most frustrated by writing idiomatic Go were often looking for more official guidance, as well as tooling support to help enforce this guidance in their codebase. As in prior surveys, questions about how to structure Go projects were also a common theme. For example:

“The simplicity of go helps to read and understand code from other developers, but there are still some aspects that can differ quite a lot between programmers. Especially if developers come from other languages, e.g. Java.” — Very satisfied / 3 – 10 years / Healthcare and life sciences

“More opinionated way to write go code. Like how to structure a Go project for services/cli tool.” — Very satisfied / < 3 years / Technology

“It’s hard to figure out what are good idioms. Especially since the core team doesn’t keep Effective Go up-to-date.” — Very satisfied / 3 – 10 years / Technology

The second major category of frustrations were language features that developers enjoyed working with in other ecosystems. These open-text comments largely focused on error handling and reporting patterns, enums and sum types, nil pointer safety, and general expressivity / verbosity:

“Still not sure what is the best way to do error handling.” — Very satisfied / 3 – 10 years / Retail and consumer goods

“Rust’s enums are great, and lead to writing great type safe code.” — Somewhat satisfied / 3 – 10 years / Healthcare and life sciences

“There is nothing (in the compiler) that stops me from using a maybe nil pointer, or using a value without checking the err first. That should be [baked into] the type system.” — Somewhat satisfied / < 3 years / Technology

“I like [Go] but I didn’t expect it to have nil pointer exceptions :)” — Somewhat satisfied / 3 – 10 years / Financial services

“I often find it hard to build abstractions and to provide clear intention to the future readers of my code.” — Somewhat dissatisfied / < 3 years / Technology

The third major frustration was finding trustworthy Go modules. Respondents often described two aspects to this problem. One is that they considered many 3rd-party modules to be of marginal quality, making it hard for really good modules to stand out. The second is identifying which modules are commonly used and under which types of conditions (including recent trends over time). These are both problems that could be addressed by showing what we’ll vaguely call “quality signals” on pkg.go.dev. Respondents provided helpful explanations of the signals they use to identify trustworthy modules, including project activity, code quality, recent adoption trends, or the specific organizations that support or rely upon the module.

“Being able to filter by criteria like stable version, number of users and last update age at pkg.go.dev could make things a bit easier.” — Very satisfied / < 3 years / Technology

“Many pacakges are just clones/forks or one-off pojects with no history/maintenance. [sic]” — Very satisfied / 10+ years / Financial services

“Maybe flagging trustworthy packages based on experience, maturity and community feedback?” — Very satisfied / 3 – 10 years / Healthcare and life sciences

We agree that these are all areas where the developer experience with Go could be improved. The challenge, as discussed earlier, is doing so in such a way that doesn’t lead to breaking changes, increased confusion among Go developers, or otherwise gets in the way of people trying to get their work done with Go. Feedback from this survey is a major source of information we use when discussing proposals, but if you’d like to get involved more directly or follow along with other contributors, visit the Go proposals on GitHub; please be sure to follow this process if you’d like to add a new proposal.

In addition to these (potentially) ecosystem-wide challenges, this year we also asked specifically about working with the go command. We’ve informally heard from developers that this tool’s help system can be confusing to navigate, but we haven’t had a great sense of how frequently people find themselves reviewing this documentation.

Respondents told us that except for go test, between 15% – 25% of them felt they “often needed to review documentation” with working with these tools. This was surprising, especially for commonly-used subcommands like build and run. Common reasons included remembering specific flags, understanding what different options do, and navigating the help system itself. Participants also confirmed that infrequent use was one reason for frustration, but navigating and parsing command help appears to be the underlying cause. In other words, we all expect to need to review documentation sometimes, but we don’t expect to need help navigating the documentation system itself. As on respondent described their journey:

“Accessing the help is painful. go test –help # didn’t work, but tell[s] me to type go help test instead… go help test # oh, actually, the info I’m looking for is in testflag go help testflag # visually parsing through text that looks all the same without much formatting… I just lack time to dig into this rabbit hole.” — Very satisfied / 10+ years / Technology

What does their development environment look like?

Operating systems and architectures

Generally, respondents told us their development platforms are UNIX-like. Most respondents develop on macOS (60%) or Linux (58%) and deploy to Linux-based systems, including containers (96%). The largest year-over-year change was among “embedded devices / IoT” deployments, which increased from 2% -> 8% of respondents; this was the only meaningful change in deployment platforms since 2024.

The vast majority of respondents develop on x86-64 or ARM64 architectures, with a sizable group (25%) still potentially working on 32-bit x86 systems. However, we believe the wording of this question was confusing to respondents; next year we’ll clarify the 32-bit vs. 64-bit distinction for each architecture.

Code editors

Several new code editors have become available in the past two years, and we expanded our survey question to include the most popular ones. While we saw some evidence of early adoption, most respondents continued to favor VS Code (37%) or GoLand (28%). Of the newer editors, Zed and Cursor were the highest ranked, each becoming the preferred editor of 4% of respondents. To put those numbers in context, we looked back at when VS Code and GoLand were first introduced. VS Code (released in 2015) was favored by 16% of respondents one year after its release. IntelliJ has had a community-led Go plugin longer than we’ve been surveying Go developers (💙), but if we look at when JetBrains began officially supporting Go in IntelliJ (2016), within one year IntelliJ was preferred by 20% of respondents.

Note: This analysis of code editors does not include respondents who were referred to the survey directly from VS Code or GoLand.

Cloud environments

The most common deployment environments for Go continue to be Amazon Web Services (AWS) at 46% of respondents, company-owned servers (44%), and Google Cloud Platform (GCP) at 26%. These numbers show minor shifts since 2024, but nothing statistically significant. We found that the “Other” category increased to 11% this year, and this was primarily driven by Hetzner (20% of Other responses); we plan to include Hetzner as a response choice in next year’s survey.

We also asked respondents about their development experience of working with different cloud providers. The most common responses, however, showed that respondents weren’t really sure (46%) or don’t directly interact with public cloud providers (21%). The biggest driver behind these responses was a theme we’ve heard often before: with containers, it’s possible to abstract many details of the cloud environment away from the developer, so that they don’t meaningfully interact with most provider-specific technologies. This result suggests that even developers whose work is deployed to clouds may have limited experience with the larger suite of tools and technology associated with each cloud provider. For example:

“Kinda abstract to the platform, Go is very easy to put in a container and so pretty easy to deploy anywhere: one of its big strength[s].” — [no satisfaction response] / 3 – 10 years / Technology

“The cloud provider really doesn’t make much difference to me. I write code and deploy it to containers, so whether that’s AWS or GCP I don’t really care.” — Somewhat satisfied / 3 – 10 years / Financial services

We suspect this level of abstraction is dependant on the use case and requirements of the service that’s being deployed — it may not always make sense or be possible to keep it highly abstracted. In the future, we plan to further investigate how Go developers tend to interact with the platforms where their software is ultimately deployed.

Developing with AI

Finally, we can’t discuss development environments in 2025 without also mentioning AI-powered software development tools. Our survey suggests bifurcated adoption — while a majority of respondents (53%) said they use such tools daily, there is also a large group (29%) who do not use these at all, or only used them a few times during the past month. We expected this to negatively correlate with age or development experience, but were unable to find strong evidence supporting this theory except for very new developers: respondents with less than one year of professional development experience (not specific to Go) did report more AI use than every other cohort, but this group only represented 2% of survey respondents.

At this time, agentic use of AI-powered tools appears nascent among Go developers, with only 17% of respondents saying this is their primary way of using such tools, though a larger group (40%) are occasionally trying agentic modes of operation.

The most commonly used AI assistants remain ChatGPT, GitHub Copilot, and Claude. Most of these agents show lower usage numbers compared with our 2024 survey (Claude and Cursor are notable exceptions), but due to a methodology change, this is not an apples-to-apples comparison. It is, however, plausible that developers are “shopping around” less than they were when these tools were first released, resulting in more people using a single assistant for most of their work.

We also asked about overall satisfaction with AI-powered development tools. A majority (55%) reported being satisfied, but this was heavily weighted towards the “Somewhat satisfied” category (42%) vs. the “Very satisfied” group (13%). Recall that Go itself consistently shows a 90%+ satisfaction rate each year; this year, 62% of respondents said they are “Very satisfied” with Go. We add this context to show that while AI-powered tooling is starting to see adoption and finding some successful use cases, developer sentiment towards them remains much softer than towards more established tooling (among Go developers, at least).

What is driving this lower rate of satisfaction? In a word: quality. We asked respondents to tell us something good they’ve accomplished with these tools, as well as something that didn’t work out well. A majority said that creating non-functional code was their primary problem with AI developer tools (53%), with 30% lamenting that even working code was of poor quality. The most frequently cited benefits, conversely, were generating unit tests, writing boilerplate code, enhanced autocompletion, refactoring, and documentation generation. These appear to be cases where code quality is perceived as less critical, tipping the balance in favor of letting AI take the first pass at a task. That said, respondents also told us the AI-generated code in these successful cases still required careful review (and often, corrections), as it can be buggy, insecure, or lack context.

“I’m never satisfied with code quality or consistency, it never follows the practices I want to.” — [no satisfaction response] / 3 – 10 years / Financial services

“All AI tools tend to hallucinate quickly when working with medium-to-large codebases (10k+ lines of code). They can explain code effectively but struggle to generate new, complex features” — Somewhat satisfied / 3 – 10 years / Retail and consumer goods

“Despite numerous efforts to make it write code in an established codebase, it would take too much effort to steer it to follow the practices in the project, and it would add subtle behaviour paths - i.e. if it would miss some method it would try to find its way around it or rely on some side effect. Sometimes those things are hard to recognize during code review. I also found it mentally taxing to review ai generated code and that overhead kills the productivity potential in writing code.” — Very satisfied / 10+ years / Technology

When we asked developers what they used these tools for, a pattern emerged that is consistent with these quality concerns. The tasks with most adoption (green in the chart below) and least resistance (red) deal with bridging knowledge gaps, improving local code, and avoiding toil. The frustrations that developers talk about with code-generating tools were much less evident when they’re seeking information, like how to use a specific API or configure test coverage, and perhaps as a result, we see higher usage of AI in these areas. Another spot that stood out was local code review and related suggestions — people were less interested in using AI to review other people’s code than in reviewing their own. Surprisingly, “testing code” showed lower AI adoption than other toilsome tasks, though we don’t yet have strong understanding of why.

Of all the tasks we asked about, “Writing code” was the most bifurcated, with 66% of respondents already or hoping to soon use AI for this, while ¼ of respondents didn’t want AI involved at all. Open-ended responses suggest developers primarily use this for toilsome, repetitive code, and continue to have concerns about the quality of AI-generated code.

Closing

Once again, a tremendous thank-you to everyone who responded to this year’s Go Developer Survey!

We plan to share the raw survey dataset in Q1 2026, so the larger community can also explore the data underlying these findings. This will only include responses from people who opted in to share this data (82% of all respondents), so there may be some differences from the numbers we reference in this post.

Survey methodology

This survey was conducted between Sept 9 - Sept 30, 2025. Participants were publicly invited to respond via the Go Blog, invitations on social media channels (including Bluesky, Mastodon, Reddit, and X), as well as randomized in-product invitations to people using VS Code and GoLand to write Go software. We received a total of 7,070 responses. After data cleaning to remove bots and other very low quality responses, 5,379 were used for the remainder of our analysis. The median survey response time was between 12 – 13 minutes.

Throughout this report we use charts of survey responses to provide supporting evidence for our findings. All of these charts use a similar format. The title is the exact question that survey respondents saw. Unless otherwise noted, questions were multiple choice and participants could only select a single response choice; each chart’s subtitle will tell the reader if the question allowed multiple response choices or was an open-ended text box instead of a multiple choice question. For charts of open-ended text responses, a Go team member read and manually categorized all of the responses. Many open-ended questions elicited a wide variety of responses; to keep the chart sizes reasonable, we condensed them to a maximum of the top 10-12 themes, with additional themes all grouped under “Other”. The percentage labels shown in charts are rounded to the nearest integer (e.g., 1.4% and 0.8% will both be displayed as 1%), but the length of each bar and row ordering are based on the unrounded values.

To help readers understand the weight of evidence underlying each finding, we included error bars showing the 95% confidence interval for responses; narrower bars indicate increased confidence. Sometimes two or more responses have overlapping error bars, which means the relative order of those responses is not statistically meaningful (i.e., the responses are effectively tied). The lower right of each chart shows the number of people whose responses are included in the chart, in the form “n = [number of respondents]”.

Next article: Go 1.26 is released
Previous article: Go’s Sweet 16
Blog Index

Go’s Sweet 16

2025-11-14T00:00:00+00:00

The Go Blog

Go’s Sweet 16

Austin Clements, for the Go team
14 November 2025

This past Monday, November 10th, we celebrated the 16th anniversary of Go’s open source release!

We released Go 1.24 in February and Go 1.25 in August, following our now well-established and dependable release cadence. Continuing our mission to build the most productive language platform for building production systems, these releases included new APIs for building robust and reliable software, significant advances in Go’s track record for building secure software, and some serious under-the-hood improvements. Meanwhile, no one can ignore the seismic shifts in our industry brought by generative AI. The Go team is applying its thoughtful and uncompromising mindset to the problems and opportunities of this dynamic space, working to bring Go’s production-ready approach to building robust AI integrations, products, agents, and infrastructure.

Core language and library improvements

First released in Go 1.24 as an experiment and then graduated in Go 1.25, the new testing/synctest package significantly simplifies writing tests for concurrent, asynchronous code. Such code is particularly common in network services, and is traditionally very hard to test well. The synctest package works by virtualizing time itself. It takes tests that used to be slow, flaky, or both, and makes them easy to rewrite into reliable and nearly instantaneous tests, often with just a couple extra lines of code. It’s also a great example of Go’s integrated approach to software development: behind an almost trivial API, the synctest package hides a deep integration with the Go runtime and other parts of the standard library.

This isn’t the only boost the testing package got over the past year. The new testing.B.Loop API is both easier to use than the original testing.B.N API and addresses many of the traditional—and often invisible!—pitfalls of writing Go benchmarks. The testing package also has new APIs that make it easy to cleanup in tests that use Context, and that make it easy to write to the test’s log.

Go and containerization grew up together and work great with each other. Go 1.25 launched container-aware scheduling, making this pairing even stronger. Without developers having to lift a finger, this transparently adjusts the parallelism of Go workloads running in containers, preventing CPU throttling that can impact tail latency and improving Go’s out-of-the-box production-readiness.

Go 1.25’s new flight recorder builds on our already powerful execution tracer, enabling deep insights into the dynamic behavior of production systems. While the execution tracer generally collected too much information to be practical in long-running production services, the flight recorder is like a little time machine, allowing a service to snapshot recent events in great detail after something has gone wrong.

Secure software development

Go continues to strengthen its commitment to secure software development, making significant strides in its native cryptography packages and evolving its standard library for enhanced safety.

Go ships with a full suite of native cryptography packages in the standard library, which reached two major milestones over the past year. A security audit conducted by independent security firm Trail of Bits yielded excellent results, with only a single low-severity finding. Furthermore, through a collaborative effort between the Go Security Team and Geomys, these packages achieved CAVP certification, paving the way for full FIPS 140-3 certification. This is a vital development for Go users in certain regulated environments. FIPS 140 compliance, previously a source of friction due to the need for unsupported solutions, will now be seamlessly integrated, addressing concerns related to safety, developer experience, functionality, release velocity, and compliance.

The Go standard library has continued to evolve to be safe by default and safe by design. For example, the os.Root API—added in Go 1.24—enables traversal-resistant file system access, effectively combating a class of vulnerabilities where an attacker could manipulate programs into accessing files intended to be inaccessible. Such vulnerabilities are notoriously challenging to address without underlying platform and operating system support, and the new os.Root API offers a straightforward, consistent, and portable solution.

Under-the-hood improvements

In addition to user-visible changes, Go has made significant improvements under the hood over the past year.

For Go 1.24, we completely redesigned the map implementation, building on the latest and greatest ideas in hash table design. This change is completely transparent, and brings significant improvements to map performance, lower tail latency of map operations, and in some cases even significant memory wins.

Go 1.25 includes an experimental and significant advancement in Go’s garbage collector called Green Tea. Green Tea reduces garbage collection overhead in many applications by at least 10% and sometimes as much as 40%. It uses a novel algorithm designed for the capabilities and constraints of today’s hardware and opens up a new design space that we’re eagerly exploring. For example, in the forthcoming Go 1.26 release, Green Tea will achieve an additional 10% reduction in garbage collector overhead on hardware that supports AVX-512 vector instructions—something that would have been nigh impossible to take advantage of in the old algorithm. Green Tea will be enabled by default in Go 1.26; users need only upgrade their Go version to benefit.

Furthering the software development stack

Go is about far more than the language and standard library. It’s a software development platform, and over the past year, we’ve also made four regular releases of the gopls language server, and have formed partnerships to support emerging new frameworks for agentic applications.

Gopls provides Go support to VS Code and other LSP-powered editors and IDEs. Every release sees a litany of features and improvements to the experience of reading and writing Go code (see the v0.17.0, v0.18.0, v0.19.0, and v0.20.0 release notes for full details, or our new gopls feature documentation!). Some highlights include many new and enhanced analyzers to help developers write more idiomatic and robust Go code; refactoring support for variable extraction, variable inlining, and JSON struct tags; and an experimental built-in server for the Model Context Protocol (MCP) that exposes a subset of gopls’ functionality to AI assistants in the form of MCP tools.

With gopls v0.18.0, we began exploring automatic code modernizers. As Go evolves, every release brings new capabilities and new idioms; new and better ways to do things that Go programmers have been finding other ways to do. Go stands by its compatibility promise—the old way will continue to work in perpetuity—but nevertheless this creates a bifurcation between old idioms and new idioms. Modernizers are static analysis tools that recognize old idioms and suggest faster, more readable, more secure, more modern replacements, and do so with push-button reliability. What gofmt did for stylistic consistency, we hope modernizers can do for idiomatic consistency. We’ve integrated modernizers as IDE suggestions, where they can help developers not only maintain more consistent coding standards, but where we believe they will help developers discover new features and keep up with the state of the art. We believe modernizers can also help AI coding assistants keep up with the state of the art and combat their proclivity to reinforce outdated knowledge of the Go language, APIs, and idioms. The upcoming Go 1.26 release will include a total overhaul of the long-dormant go fix command to make it apply the full suite of modernizers in bulk, a return to its pre-Go 1.0 roots.

At the end of September, in collaboration with Anthropic and the Go community, we released v1.0.0 of the official Go SDK for the Model Context Protocol (MCP). This SDK supports both MCP clients and MCP servers, and underpins the new MCP functionality in gopls. Contributing this work in open source helps empower other areas of the growing open source agentic ecosystem built around Go, such as the recently released Agent Development Kit (ADK) for Go from Google. ADK Go builds on the Go MCP SDK to provide an idiomatic framework for building modular multi-agent applications and systems. The Go MCP SDK and ADK Go demonstrate how Go’s unique strengths in concurrency, performance, and reliability differentiate Go for production AI development and we are expecting more AI workloads to be written in Go in the coming years.

Looking ahead

Go has an exciting year ahead of it.

We’re working on advancing developer productivity through the brand new go fix command, deeper support for AI coding assistants, and ongoing improvements to gopls and VS Code Go. General availability of the Green Tea garbage collector, native support for Single Instruction Multiple Data (SIMD) hardware features, and runtime and standard library support for writing code that scales even better to massive multicore hardware will continue to align Go with modern hardware and improve production efficiency. We’re focusing on Go’s “production stack” libraries and diagnostics, including a massive (and long in the making) upgrade to encoding/json, driven by Joe Tsai and people across the Go community; leaked goroutine profiling, contributed by Uber’s Programming Systems team; and many other improvements to net/http, unicode, and other foundational packages. We’re working to provide well-lit paths for building with Go and AI, evolving the language platform with care for the evolving needs of today’s developers, and building tools and capabilities that help both human developers and AI assistants and systems alike.

On this 16th anniversary of Go’s open source release, we’re also looking to the future of the Go open source project itself. From its humble beginnings, Go has formed a thriving contributor community. To continue to best meet the needs of our ever-expanding user base, especially in a time of upheaval in the software industry, we’re working on ways to better scale Go’s development processes—without losing sight of Go’s fundamental principles—and more deeply involve our wonderful contributor community.

Go would not be where it is today without our incredible user and contributor communities. We wish you all the best in the coming year!

Next article: Results from the 2025 Go Developer Survey
Previous article: The Green Tea Garbage Collector
Blog Index

The Green Tea Garbage Collector

2025-10-29T00:00:00+00:00

The Go Blog

The Green Tea Garbage Collector

Michael Knyszek and Austin Clements
29 October 2025

Go 1.25 includes a new experimental garbage collector called Green Tea, available by setting GOEXPERIMENT=greenteagc at build time. Many workloads spend around 10% less time in the garbage collector, but some workloads see a reduction of up to 40%!

It’s production-ready and already in use at Google, so we encourage you to try it out. We know some workloads don’t benefit as much, or even at all, so your feedback is crucial to helping us move forward. Based on the data we have now, we plan to make it the default in Go 1.26.

To report back with any problems, file a new issue.

To report back with any successes, reply to the existing Green Tea issue.

What follows is a blog post based on Michael Knyszek’s GopherCon 2025 talk.

Tracing garbage collection

Before we discuss Green Tea let’s get us all on the same page about garbage collection.

Objects and pointers

The purpose of garbage collection is to automatically reclaim and reuse memory no longer used by the program.

To this end, the Go garbage collector concerns itself with objects and pointers.

In the context of the Go runtime, objects are Go values whose underlying memory is allocated from the heap. Heap objects are created when the Go compiler can’t figure out how else to allocate memory for a value. For example, the following code snippet allocates a single heap object: the backing store for a slice of pointers.

var x = make([]*int, 10) // global

The Go compiler can’t allocate the slice backing store anywhere except the heap, since it’s very hard, and maybe even impossible, for it to know how long x will refer to the object for.

Pointers are just numbers that indicate the location of a Go value in memory, and they’re how a Go program references objects. For example, to get the pointer to the beginning of the object allocated in the last code snippet, we can write:

&x[0] // 0xc000104000

The mark-sweep algorithm

Go’s garbage collector follows a strategy broadly referred to as tracing garbage collection, which just means that the garbage collector follows, or traces, the pointers in the program to identify which objects the program is still using.

More specifically, the Go garbage collector implements the mark-sweep algorithm. This is much simpler than it sounds. Imagine objects and pointers as a sort of graph, in the computer science sense. Objects are nodes, pointers are edges.

The mark-sweep algorithm operates on this graph, and as the name might suggest, proceeds in two phases.

In the first phase, the mark phase, it walks the object graph from well-defined source edges called roots. Think global and local variables. Then, it marks everything it finds along the way as visited, to avoid going in circles. This is analogous to your typical graph flood algorithm, like a depth-first or breadth-first search.

Next is the sweep phase. Whatever objects were not visited in our graph walk are unused, or unreachable, by the program. We call this state unreachable because it is impossible with normal safe Go code to access that memory anymore, simply through the semantics of the language. To complete the sweep phase, the algorithm simply iterates through all the unvisited nodes and marks their memory as free, so the memory allocator can reuse it.

That’s it?

You may think I’m oversimplifying a bit here. Garbage collectors are frequently referred to as magic, and black boxes. And you’d be partially right, there are more complexities.

For example, this algorithm is, in practice, executed concurrently with your regular Go code. Walking a graph that’s mutating underneath you brings challenges. We also parallelize this algorithm, which is a detail that’ll come up again later.

But trust me when I tell you that these details are mostly separate from the core algorithm. It really is just a simple graph flood at the center.

Graph flood example

Let’s walk through an example. Navigate through the slideshow below to follow along.

Scroll horizontally through the slideshow!

Here we have a diagram of some global variables and Go heap. Let's break it down, piece by piece.

On the left here we have our roots. These are global variables x and y. They will be the starting point of our graph walk. Since they're marked blue, according to our handy legend in the bottom left, they're currently on our work list.

On the right side, we have our heap. Currently, everything in our heap is grayed out because we haven't visited any of it yet.

Each one of these rectangles represents an object. Each object is labeled with its type. This object in particular is an object of type T, whose type definition is on the top left. It's got a pointer to an array of children, and some value. We can surmise that this is some kind of recursive tree data structure.

In addition to the objects of type T, you'll also notice that we have array objects containing *Ts. These are pointed to by the "children" field of objects of type T.

Each square inside of the rectangle represents 8 bytes of memory. A square with a dot is a pointer. If it has an arrow, it is a non-nil pointer pointing to some other object.

And if it doesn't have a corresponding arrow, then it's a nil pointer.

Next, these dotted rectangles represents free space, what I'll call a free "slot." We could put an object there, but there currently isn't one.

You'll also notice that objects are grouped together by these labeled, dotted rounded rectangles. Each of these represents a page, which is a contiguous block of fixed-size, aligned memory. In Go, pages are 8 KiB (regardless of the hardware virtual memory page size). These pages are labeled A, B, C, and D, and I'll refer to them that way.

In this diagram, each object is allocated as part of some page. Like in the real implementation, each page here only contains objects of a certain size. This is just how the Go heap is organized.

Pages are also how we organize per-object metadata. Here you can see seven boxes, each corresponding to one of the seven object slots in page A.

Each box represents one bit of information: whether or not we have seen the object before. This is actually how the real runtime manages whether an object has been visited, and it'll be an important detail later.

That was a lot of detail, so thanks for reading along. This will all come into play later. For now, let's just see how our graph flood applies to this picture.

We start by taking a root off of the work list. We mark it red to indicate that it's now active.

Following that root's pointer, we find an object of type T, which we add to our work list. Following our legend, we draw the object in blue to indicate that it's on our work list. Note also that we set the seen bit corresponding to this object in our metadata.

Same goes for the next root.

Now that we've taken care of all the roots, we're left with two objects on our work list. Let's take an object off the work list.

What we're going to do now is walk the pointers of the objects, to find more objects. By the way, we call walking the pointers of an object "scanning" the object.

We find this valid array object…

… and add it to our work list.

From here, we proceed recursively.

We walk the array's pointers.

Find some more objects…

Then we walk the objects that the array object referred to!

And note that we still have to walk over all pointers, even if they're nil. We don't know ahead of time if they will be.

One more object down this branch…

And now we've reached the other branch, starting from that object in page A we found much earlier from one of the roots.

You may be noticing a last-in-first-out discipline for our work list here, indicating that our work list is a stack, and hence our graph flood is approximately depth-first. This is intentional, and reflects the actual graph flood algorithm in the Go runtime.

Let's keep going…

Next we find another array object…

And walk it…

Just one more object left on our work list…

Let's scan it…

And we're done with the mark phase! There's nothing we're actively working on and there's nothing left on our work list. Every object drawn in black is reachable, and every object drawn in gray is unreachable. Let's sweep the unreachable objects, all in one go.

We've converted those objects into free slots, ready to hold new objects.

The problem

After all that, I think we have a handle on what the Go garbage collector is actually doing. This process seems to work well enough today, so what’s the problem?

Well, it turns out we can spend a lot of time executing this particular algorithm in some programs, and it adds substantial overhead to nearly every Go program. It’s not that uncommon to see Go programs spending 20% or more of their CPU time in the garbage collector.

Let’s break down where that time is being spent.

Garbage collection costs

At a high level, there are two parts to the cost of the garbage collector. The first is how often it runs, and the second is how much work it does each time it runs. Multiply those two together, and you get the total cost of the garbage collector.

Total GC cost = Number of GC cycles × Average cost per GC cycle

Over the years we’ve tackled both terms in this equation, and for more on how often the garbage collector runs, see Michael’s GopherCon EU talk from 2022 about memory limits. The guide to the Go garbage collector also has a lot to say about this topic, and is worth a look if you want to dive deeper.

But for now let’s focus only on the second part, the cost per cycle.

From years of poring over CPU profiles to try to improve performance, we know two big things about Go’s garbage collector.

The first is that about 90% of the cost of the garbage collector is spent marking, and only about 10% is sweeping. Sweeping turns out to be much easier to optimize than marking, and Go has had a very efficient sweeper for many years.

The second is that, of that time spent marking, a substantial portion, usually at least 35%, is simply spent stalled on accessing heap memory. This is bad enough on its own, but it completely gums up the works on what makes modern CPUs actually fast.

“A microarchitectural disaster”

What does “gum up the works” mean in this context? The specifics of modern CPUs can get pretty complicated, so let’s use an analogy.

Imagine the CPU driving down a road, where that road is your program. The CPU wants to ramp up to a high speed, and to do that it needs to be able to see far ahead of it, and the way needs to be clear. But the graph flood algorithm is like driving through city streets for the CPU. The CPU can’t see around corners and it can’t predict what’s going to happen next. To make progress, it constantly has to slow down to make turns, stop at traffic lights, and avoid pedestrians. It hardly matters how fast your engine is because you never get a chance to get going.

Let’s make that more concrete by looking at our example again. I’ve overlaid the heap here with the path that we took. Each left-to-right arrow represents a piece of scanning work that we did and the dashed arrows show how we jumped around between bits of scanning work.

The path through the heap the garbage collector took in our graph flood example.

Notice that we were jumping all over memory doing tiny bits of work in each place. In particular, we’re frequently jumping between pages, and between different parts of pages.

Modern CPUs do a lot of caching. Going to main memory can be up to 100x slower than accessing memory that’s in our cache. CPU caches are populated with memory that’s been recently accessed, and memory that’s nearby to recently accessed memory. But there’s no guarantee that any two objects that point to each other will also be close to each other in memory. The graph flood doesn’t take this into account.

Quick side note: if we were just stalling fetches to main memory, it might not be so bad. CPUs issue memory requests asynchronously, so even slow ones could overlap if the CPU could see far enough ahead. But in the graph flood, every bit of work is small, unpredictable, and highly dependent on the last, so the CPU is forced to wait on nearly every individual memory fetch.

And unfortunately for us, this problem is only getting worse. There’s an adage in the industry of “wait two years and your code will get faster.”

But Go, as a garbage collected language that relies on the mark-sweep algorithm, risks the opposite. “Wait two years and your code will get slower.” The trends in modern CPU hardware are creating new challenges for garbage collector performance:

Non-uniform memory access. For one, memory now tends to be associated with subsets of CPU cores. Accesses by other CPU cores to that memory are slower than before. In other words, the cost of a main memory access depends on which CPU core is accessing it. It’s non-uniform, so we call this non-uniform memory access, or NUMA for short.

Reduced memory bandwidth. Available memory bandwidth per CPU is trending downward over time. This just means that while we have more CPU cores, each core can submit relatively fewer requests to main memory, forcing non-cached requests to wait longer than before.

Ever more CPU cores. Above, we looked at a sequential marking algorithm, but the real garbage collector performs this algorithm in parallel. This scales well to a limited number of CPU cores, but the shared queue of objects to scan becomes a bottleneck, even with careful design.

Modern hardware features. New hardware has fancy features like vector instructions, which let us operate on a lot of data at once. While this has the potential for big speedups, it’s not immediately clear how to make that work for marking because marking does so much irregular and often small pieces of work.

Green Tea

Finally, this brings us to Green Tea, our new approach to the mark-sweep algorithm. The key idea behind Green Tea is astonishingly simple:

Work with pages, not objects.

Sounds trivial, right? And yet, it took a lot of work to figure out how to order the object graph walk and what we needed to track to make this work well in practice.

More concretely, this means:

Instead of scanning objects we scan whole pages.
Instead of tracking objects on our work list, we track whole pages.
We still need to mark objects at the end of the day, but we’ll track marked objects locally to each page, rather than across the whole heap.

Green Tea example

Let’s see what this means in practice by looking at our example heap again, but this time running Green Tea instead of the straightforward graph flood.

As above, navigate through the annotated slideshow to follow along.

Scroll horizontally through the slideshow!

This is the same heap as before, but now with two bits of metadata per object rather than one. Again, each bit, or box, corresponds to one of the object slots in the page. In total, we now have fourteen bits that correspond to the seven slots in page A.

The top bits represent the same thing as before: whether or not we've seen a pointer to the object. I'll call these the "seen" bits. The bottom set of bits are new. These "scanned" bits track whether or not we've scanned the object.

This new piece of metadata is necessary because, in Green tea, the work list tracks pages, not objects. We still need to track objects at some level, and that's the purpose of these bits.

We start off the same as before, walking objects from the roots.

But this time, instead of putting an object on the work list, we put a whole page–in this case page A–on the work list, indicated by shading the whole page blue.

The object we found is also blue to indicate that when we do take this page off of the work list, we will need to look at that object. Note that the object's blue hue directly reflects the metadata in page A. Its corresponding seen bit is set, but its scanned bit is not.

We follow the next root, find another object, and again put the whole page–page C–on the work list and set the object's seen bit.

We're done following roots, so we turn to the work list and take page A off the work list.

Using the seen and scanned bits, we can tell there's one object to scan on page A.

We scan that object, following its pointers. And as a result, we add page B to the work list, since the first object in page A points to an object in page B.

We're done with page A. Next we take page C off the work list.

Similar to page A, there's a single object on page C to scan.

We found a pointer to another object in page B. Page B is already on the work list, so we don't need to add anything to the work list. We simply have to set the seen bit for the target object.

Now it's page B's turn. We've accumulated two objects to scan on page B, and we can process both of these objects in a row, in memory order!

We walk the pointers of the first object…

We find a pointer to an object in page A. Page A was previously on the work list, but isn't at this point, so we put it back on the work list. Unlike the original mark-sweep algorithm, where any given object is only added to the work list at most once per whole mark phase, in Green Tea, a given page can reappear on the work list several times during a mark phase.

We scan the second seen object in the page immediately after the first.

We find a few more objects in page A…

We're done scanning page B, so we pull page A off the work list.

This time we only need to scan three objects, not four, since we already scanned the first object. We know which objects to scan by looking at the difference between the "seen" and "scanned" bits.

We'll scan these objects in sequence.

We're done! There are no more pages on the work list and there's nothing we're actively looking at. Notice that the metadata now all lines up nicely, since all reachable objects were both seen and scanned.

You may have also noticed during our traversal that the work list order is a little different from the graph flood. Where the graph flood had a last-in-first-out, or stack-like, order, here we're using a first-in-first-out, or queue-like, order for the pages on our work list.

This is intentional. We let seen objects accumulate on each page while the page sits on the queue, so we can process as many as we can at once. That's how we were able to hit so many objects on page A at once. Sometimes laziness is a virtue.

And finally we can sweep away the unvisited objects, as before.

Getting on the highway

Let’s come back around to our driving analogy. Are we finally getting on the highway?

Let’s recall our graph flood picture before.

The path the original graph flood took through the heap required 7 separate scans.

We jumped around a whole lot, doing little bits of work in different places. The path taken by Green Tea looks very different.

The path taken by Green Tea requires only 4 scans.

Green Tea, in contrast, makes fewer, longer left-to-right passes over pages A and B. The longer these arrows, the better, and with bigger heaps, this effect can be much stronger. That’s the magic of Green Tea.

It’s also our opportunity to ride the highway.

This all adds up to a better fit with the microarchitecture. We can now scan objects closer together with much higher probability, so there’s a better chance we can make use of our caches and avoid main memory. Likewise, per-page metadata is more likely to be in cache. Tracking pages instead of objects means work lists are smaller, and less pressure on work lists means less contention and fewer CPU stalls.

And speaking of the highway, we can take our metaphorical engine into gears we’ve never been able to before, since now we can use vector hardware!

Vector acceleration

If you’re only vaguely familiar with vector hardware, you might be confused as to how we can use it here. But besides the usual arithmetic and trigonometric operations, recent vector hardware supports two things that are valuable for Green Tea: very wide registers, and sophisticated bit-wise operations.

Most modern x86 CPUs support AVX-512, which has 512-bit wide vector registers. This is wide enough to hold all of the metadata for an entire page in just two registers, right on the CPU, enabling Green Tea to work on an entire page in just a few straight-line instructions. Vector hardware has long supported basic bit-wise operations on whole vector registers, but starting with AMD Zen 4 and Intel Ice Lake, it also supports a new bit vector “Swiss army knife” instruction that enables a key step of the Green Tea scanning process to be done in just a few CPU cycles. Together, these allow us to turbo-charge the Green Tea scan loop.

This wasn’t even an option for the graph flood, where we’d be jumping between scanning objects that are all sorts of different sizes. Sometimes you needed two bits of metadata and sometimes you needed ten thousand. There simply wasn’t enough predictability or regularity to use vector hardware.

If you want to nerd out on some of the details, read along! Otherwise, feel free to skip ahead to the evaluation.

AVX-512 scanning kernel

To get a sense of what AVX-512 GC scanning looks like, take a look at the diagram below.

The AVX-512 vector kernel for scanning.

There’s a lot going on here and we could probably fill an entire blog post just on how this works. For now, let’s just break it down at a high level:

First we fetch the “seen” and “scanned” bits for a page. Recall, these are one bit per object in the page, and all objects in a page have the same size.
Next, we compare the two bit sets. Their union becomes the new “scanned” bits, while their difference is the “active objects” bitmap, which tells us which objects we need to scan in this pass over the page (versus previous passes).
We take the difference of the bitmaps and “expand” it, so that instead of one bit per object, we have one bit per word (8 bytes) of the page. We call this the “active words” bitmap. For example, if the page stores 6-word (48-byte) objects, each bit in the active objects bitmap will be copied to 6 bits in the active words bitmap. Like so:

0 0 1 1 ...

→

000000 000000 111111 111111 ...

Next we fetch the pointer/scalar bitmap for the page. Here, too, each bit corresponds to a word (8 bytes) of the page, and it tells us whether that word stores a pointer. This data is managed by the memory allocator.
Now, we take the intersection of the pointer/scalar bitmap and the active words bitmap. The result is the “active pointer bitmap”: a bitmap that tells us the location of every pointer in the entire page contained in any live object we haven’t scanned yet.
Finally, we can iterate over the memory of the page and collect all the pointers. Logically, we iterate over each set bit in the active pointer bitmap, load the pointer value at that word, and write it back to a buffer that will later be used to mark objects seen and add pages to the work list. Using vector instructions, we’re able to do this 64 bytes at a time, in just a couple instructions.

Part of what makes this fast is the VGF2P8AFFINEQB instruction, part of the “Galois Field New Instructions” x86 extension, and the bit manipulation Swiss army knife we referred to above. It’s the real star of the show, since it lets us do step (3) in the scanning kernel very, very efficiently. It performs a bit-wise affine transformations, treating each byte in a vector as itself a mathematical vector of 8 bits and multiplying it by an 8x8 bit matrix. This is all done over the Galois field GF(2), which just means multiplication is AND and addition is XOR. The upshot of this is that we can define a few 8x8 bit matrices for each object size that perform exactly the 1:n bit expansion we need.

For the full assembly code, see this file. The “expanders” use different matrices and different permutations for each size class, so they’re in a separate file that’s written by a code generator. Aside from the expansion functions, it’s really not a lot of code. Most of it is dramatically simplified by the fact that we can perform most of the above operations on data that sits purely in registers. And, hopefully soon this assembly code will be replaced with Go code!

Credit to Austin Clements for devising this process. It’s incredibly cool, and incredibly fast!

Evaluation

So that’s it for how it works. How much does it actually help?

It can be quite a lot. Even without the vector enhancements, we see reductions in garbage collection CPU costs between 10% and 40% in our benchmark suite. For example, if an application spends 10% of its time in the garbage collector, then that would translate to between a 1% and 4% overall CPU reduction, depending on the specifics of the workload. A 10% reduction in garbage collection CPU time is roughly the modal improvement. (See the GitHub issue for some of these details.)

We’ve rolled Green Tea out inside Google, and we see similar results at scale.

We’re still rolling out the vector enhancements, but benchmarks and early results suggest this will net an additional 10% GC CPU reduction.

While most workloads benefit to some degree, there are some that don’t.

Green Tea is based on the hypothesis that we can accumulate enough objects to scan on a single page in one pass to counteract the costs of the accumulation process. This is clearly the case if the heap has a very regular structure: objects of the same size at a similar depth in the object graph. But there are some workloads that often require us to scan only a single object per page at a time. This is potentially worse than the graph flood because we might be doing more work than before while trying to accumulate objects on pages and failing.

The implementation of Green Tea has a special case for pages that have only a single object to scan. This helps reduce regressions, but doesn’t completely eliminate them.

However, it takes a lot less per-page accumulation to outperform the graph flood than you might expect. One surprise result of this work was that scanning a mere 2% of a page at a time can yield improvements over the graph flood.

Availability

Green Tea is already available as an experiment in the recent Go 1.25 release and can be enabled by setting the environment variable GOEXPERIMENT to greenteagc at build time. This doesn’t include the aforementioned vector acceleration.

We expect to make it the default garbage collector in Go 1.26, but you’ll still be able to opt-out with GOEXPERIMENT=nogreenteagc at build time. Go 1.26 will also add vector acceleration on newer x86 hardware, and include a whole bunch of tweaks and improvements based on feedback we’ve collected so far.

If you can, we encourage you to try at Go tip-of-tree! If you prefer to use Go 1.25, we’d still love your feedback. See this GitHub comment with some details on what diagnostics we’d be interested in seeing, if you can share, and the preferred channels for reporting feedback.

The journey

Before we wrap up this blog post, let’s take a moment to talk about the journey that got us here. The human element of the technology.

The core of Green Tea may seem like a single, simple idea. Like the spark of inspiration that just one single person had.

But that’s not true at all. Green Tea is the result of work and ideas from many people over several years. Several people on the Go team contributed to the ideas, including Michael Pratt, Cherry Mui, David Chase, and Keith Randall. Microarchitectural insights from Yves Vandriessche, who was at Intel at the time, also really helped direct the design exploration. There were a lot of ideas that didn’t work, and there were a lot of details that needed figuring out. Just to make this single, simple idea viable.

A timeline depicting a subset of the ideas we tried in this vein before getting to where we are today.

The seeds of this idea go all the way back to 2018. What’s funny is that everyone on the team thinks someone else thought of this initial idea.

Green Tea got its name in 2024 when Austin worked out a prototype of an earlier version while cafe crawling in Japan and drinking LOTS of matcha! This prototype showed that the core idea of Green Tea was viable. And from there we were off to the races.

Throughout 2025, as Michael implemented and productionized Green Tea, the ideas evolved and changed even further.

This took so much collaborative exploration because Green Tea is not just an algorithm, but an entire design space. One that we don’t think any of us could’ve navigated alone. It’s not enough to just have the idea, but you need to figure out the details and prove it. And now that we’ve done it, we can finally iterate.

The future of Green Tea is bright.

Once again, please try it out by setting GOEXPERIMENT=greenteagc and let us know how it goes! We’re really excited about this work and want to hear from you!

Next article: Go’s Sweet 16
Previous article: Flight Recorder in Go 1.25
Blog Index

Flight Recorder in Go 1.25

2025-09-26T00:00:00+00:00

The Go Blog

Flight Recorder in Go 1.25

Carlos Amedee and Michael Knyszek
26 September 2025

In 2024 we introduced the world to more powerful Go execution traces. In that blog post we gave a sneak peek into some of the new functionality we could unlock with our new execution tracer, including flight recording. We’re happy to announce that flight recording is now available in Go 1.25, and it’s a powerful new tool in the Go diagnostics toolbox.

Execution traces

First, a quick recap on Go execution traces.

The Go runtime can be made to write a log recording many of the events that happen during the execution of a Go application. That log is called a runtime execution trace. Go execution traces contain a plethora of information about how goroutines interact with each other and the underlying system. This makes them very handy for debugging latency issues, since they tell you both when your goroutines are executing, and crucially, when they are not.

The runtime/trace package provides an API for collecting an execution trace over a given time window by calling runtime/trace.Start and runtime/trace.Stop. This works well if the code you’re tracing is just a test, microbenchmark, or command line tool. You can collect a trace of the complete end-to-end execution, or just the parts you care about.

However, in long-running web services, the kinds of applications Go is known for, that’s not good enough. Web servers might be up for days or even weeks, and collecting a trace of the entire execution would produce far too much data to sift through. Often just one part of the program’s execution goes wrong, like a request timing out or a failed health check. By the time it happens it’s already too late to call Start!

One way to approach this problem is to randomly sample execution traces from across the fleet. While this approach is powerful, and can help find issues before they become outages, it requires a lot of infrastructure to get going. Large quantities of execution trace data would need to be stored, triaged, and processed, much of which won’t contain anything interesting at all. And when you’re trying to get to the bottom of a specific issue, it’s a non-starter.

Flight recording

This brings us to the flight recorder.

A program often knows when something has gone wrong, but the root cause may have happened long ago. The flight recorder lets you collect a trace of the last few seconds of execution leading up to the moment a program detects there’s been a problem.

The flight recorder collects the execution trace as normal, but instead of writing it out to a socket or a file, it buffers the last few seconds of the trace in memory. At any point, the program can request the contents of the buffer and snapshot exactly the problematic window of time. The flight recorder is like a scalpel cutting directly to the problem area.

Example

Let’s learn how to use the flight recorder with an example. Specifically, let’s use it to diagnose a performance problem with an HTTP server that implements a “guess the number” game. It exposes a /guess-number endpoint that accepts an integer and responds to the caller informing them if they guessed the right number. There is also a goroutine that, once per minute, sends a report of all the guessed numbers to another service via an HTTP request.

// bucket is a simple mutex-protected counter.
type bucket struct {
    mu      sync.Mutex
    guesses int
}

func main() {
    // Make one bucket for each valid number a client could guess.
    // The HTTP handler will look up the guessed number in buckets by
    // using the number as an index into the slice.
    buckets := make([]bucket, 100)

    // Every minute, we send a report of how many times each number was guessed.
    go func() {
        for range time.Tick(1 * time.Minute) {
            sendReport(buckets)
        }
    }()

    // Choose the number to be guessed.
    answer := rand.Intn(len(buckets))

    http.HandleFunc("/guess-number", func(w http.ResponseWriter, r *http.Request) {
        start := time.Now()

        // Fetch the number from the URL query variable "guess" and convert it
        // to an integer. Then, validate it.
        guess, err := strconv.Atoi(r.URL.Query().Get("guess"))
        if err != nil || !(0 <= guess && guess < len(buckets)) {
            http.Error(w, "invalid 'guess' value", http.StatusBadRequest)
            return
        }

        // Select the appropriate bucket and safely increment its value.
        b := &buckets[guess]
        b.mu.Lock()
        b.guesses++
        b.mu.Unlock()

        // Respond to the client with the guess and whether it was correct.
        fmt.Fprintf(w, "guess: %d, correct: %t", guess, guess == answer)

        log.Printf("HTTP request: endpoint=/guess-number guess=%d duration=%s", guess, time.Since(start))
    })
    log.Fatal(http.ListenAndServe(":8090", nil))
}

// sendReport posts the current state of buckets to a remote service.
func sendReport(buckets []bucket) {
    counts := make([]int, len(buckets))

    for index := range buckets {
        b := &buckets[index]
        b.mu.Lock()
        defer b.mu.Unlock()

        counts[index] = b.guesses
    }

    // Marshal the report data into a JSON payload.
    b, err := json.Marshal(counts)
    if err != nil {
        log.Printf("failed to marshal report data: error=%s", err)
        return
    }
    url := "http://localhost:8091/guess-number-report"
    if _, err := http.Post(url, "application/json", bytes.NewReader(b)); err != nil {
        log.Printf("failed to send report: %s", err)
    }
}

Here is the full code for the server: https://go.dev/play/p/rX1eyKtVglF, and for a simple client: https://go.dev/play/p/2PjQ-1ORPiw. To avoid a third process, the “client” also implements the report server, though in a real system this would be separate.

Let’s suppose that after deploying the application in production, we received complaints from users that some /guess-number calls were taking longer than expected. When we look at our logs, we see that sometimes response times exceed 100 milliseconds, while the majority of calls are on the order of microseconds.

2025/09/19 16:52:02 HTTP request: endpoint=/guess-number guess=69 duration=625ns
2025/09/19 16:52:02 HTTP request: endpoint=/guess-number guess=62 duration=458ns
2025/09/19 16:52:02 HTTP request: endpoint=/guess-number guess=42 duration=1.417µs
2025/09/19 16:52:02 HTTP request: endpoint=/guess-number guess=86 duration=115.186167ms
2025/09/19 16:52:02 HTTP request: endpoint=/guess-number guess=0 duration=127.993375ms

Before we continue, take a minute and see if you can spot what’s wrong!

Regardless of whether you found the problem or not, let’s dive deeper and see how we can find the problem from first principles. In particular, it would be great if we could see what the application was doing in the time leading up to the slow response. This is exactly what the flight recorder was built for! We’ll use it to capture an execution trace once we see the first response exceeding 100 milliseconds.

First, in main, we’ll configure and start the flight recorder:

// Set up the flight recorder
fr := trace.NewFlightRecorder(trace.FlightRecorderConfig{
    MinAge:   200 * time.Millisecond,
    MaxBytes: 1 << 20, // 1 MiB
})
fr.Start()

MinAge configures the duration for which trace data is reliably retained, and we suggest setting it to around 2x the time window of the event. For example, if you are debugging a 5-second timeout, set it to 10 seconds. MaxBytes configures the size of the buffered trace so you don’t blow up your memory usage. On average, you can expect a few MB of trace data to be produced per second of execution, or 10 MB/s for a busy service.

Next, we’ll add a helper function to capture the snapshot and write it to a file:

var once sync.Once

// captureSnapshot captures a flight recorder snapshot.
func captureSnapshot(fr *trace.FlightRecorder) {
    // once.Do ensures that the provided function is executed only once.
    once.Do(func() {
        f, err := os.Create("snapshot.trace")
        if err != nil {
            log.Printf("opening snapshot file %s failed: %s", f.Name(), err)
            return
        }
        defer f.Close() // ignore error

        // WriteTo writes the flight recorder data to the provided io.Writer.
        _, err = fr.WriteTo(f)
        if err != nil {
            log.Printf("writing snapshot to file %s failed: %s", f.Name(), err)
            return
        }

        // Stop the flight recorder after the snapshot has been taken.
        fr.Stop()
        log.Printf("captured a flight recorder snapshot to %s", f.Name())
    })
}

And finally, just before logging a completed request, we’ll trigger the snapshot if the request took more than 100 milliseconds:

// Capture a snapshot if the response takes more than 100ms.
// Only the first call has any effect.
if fr.Enabled() && time.Since(start) > 100*time.Millisecond {
    go captureSnapshot(fr)
}

Here’s the full code for the server, now instrumented with the flight recorder: https://go.dev/play/p/3V33gfIpmjG

Now, we run the server again and send requests until we get a slow request that triggers a snapshot.

Once we’ve gotten a trace, we’ll need a tool that will help us examine it. The Go toolchain provides a built-in execution trace analysis tool via the go tool trace command. Run go tool trace snapshot.trace to launch the tool, which starts a local web server, then open the displayed URL in your browser (if the tool doesn’t open your browser automatically).

This tool gives us a few ways to look at the trace, but let’s focus on visualizing the trace to get a sense of what’s going on. Click “View trace by proc” to do so.

In this view, the trace is presented as a timeline of events. At the top of the page, in the “STATS” section, we can see a summary of the application’s state, including the number of threads, the heap size, and the goroutine count.

Below that, in the “PROCS” section, we can see how the execution of goroutines is mapped onto GOMAXPROCS (the number of operating system threads created by the Go application). We can see when and how each goroutine starts, runs, and finally stops executing.

For now, let’s turn our attention to this massive gap in execution on the right side of the viewer. For a period of time, around 100ms, nothing is happening!

By selecting the zoom tool (or pressing 3), we can inspect the section of the trace right after the gap with more detail.

In addition to the activity of each individual goroutine, we can see how goroutines interact via “flow events.” An incoming flow event indicates what happened to make a goroutine start running. An outgoing flow edge indicates what effect one goroutine had on another. Enabling the visualization of all flow events often provides clues that hint at the source of a problem.

In this case, we can see that many of the goroutines have a direct connection to a single goroutine right after the pause in activity.

Clicking on the single goroutine shows an event table filled with outgoing flow events, which matches what we saw when the flow view was enabled.

What happened when this goroutine ran? Part of the information stored in the trace is a view of the stack trace at different points in time. When we look at the goroutine we can see that the start stack trace shows that it was waiting for the HTTP request to complete when the goroutine was scheduled to run. And the end stack trace shows that the sendReport function had already returned and it was waiting for the ticker for the next scheduled time to send the report.

Between the start and the end of this goroutine running, we see a huge number of “outgoing flows,” where it interacts with other goroutines. Clicking on one of the Outgoing flow entries takes us to a view of the interaction.

This flow implicates the Unlock in sendReport:

for index := range buckets {
    b := &buckets[index]
    b.mu.Lock()
    defer b.mu.Unlock()

    counts[index] = b.guesses
}

In sendReport, we intended to acquire a lock on each bucket and release the lock after copying the value.

But here’s the problem: we don’t actually release the lock immediately after copying the value contained in bucket.guesses. Because we used a defer statement to release the lock, that release doesn’t happen until the function returns. We hold the lock not just past the end of the loop, but until after the HTTP request completes. That’s a subtle error that may be difficult to track down in a large production system.

Fortunately, execution tracing helped us pinpoint the problem. However, if we tried to use the execution tracer in a long-running server without the new flight-recording mode, it would likely amass a huge amount of execution trace data, which an operator would have to store, transmit, and sift through. The flight recorder gives us the power of hindsight. It lets us capture just what went wrong, after it’s already happened, and quickly zero in on the cause.

The flight recorder is just the latest addition to the Go developer’s toolbox for diagnosing the inner workings of running applications. We’ve steadily been improving tracing over the past couple of releases. Go 1.21 greatly reduced the run-time overhead of tracing. The trace format became more robust and also splittable in the Go 1.22 release, leading to features like the flight recorder. Open-source tools like gotraceui, and the forthcoming ability to programmatically parse execution traces are more ways to leverage the power of execution traces. The Diagnostics page lists many additional tools at your disposal. We hope you make use of them as you write and refine your Go applications.

Thanks

We’d like to take a moment to thank those community members who have been active in the diagnostics meetings, contributed to the designs, and provided feedback over the years: Felix Geisendörfer (@felixge.de), Nick Ripley (@nsrip-dd), Rhys Hiltner (@rhysh), Dominik Honnef (@dominikh), Bryan Boreham (@bboreham), and PJ Malloy (@thepudds).

The discussions, feedback, and work you’ve all put in have been instrumental in pushing us to a better diagnostics future. Thank you!

Next article: The Green Tea Garbage Collector
Previous article: It's survey time! How has Go has been working out for you?
Blog Index

It's survey time! How has Go has been working out for you?

2025-09-16T00:00:00+00:00

The Go Blog

It's survey time! How has Go has been working out for you?

Todd Kulesza, on behalf of the Go team
16 September 2025

Hi Gophers! Today we’re excited to announce our 2025 Go Developer Survey. The Go Team uses the results of this annual survey to better understand the needs and concerns of Go developers across the world. Your feedback helps us brainstorm, plan, and prioritize work on Go.

You can take the survey here. It will be open through September 30th. The survey should take 10 – 20 minutes to complete, and every question is optional.

We’ll share aggregated survey results on this blog in early November. This year we’ll also share the raw dataset of survey responses, so that the entire Go community can benefit from this knowledge and conduct your own analyses on the data. Similar to our approach with Go Telemetry, we’re using an opt-in model: the survey will ask for your permission to include your responses in the dataset. If you don’t give us permission, your survey responses will not be shared.

Please help us reach as many Go developers as possible! We love it when you share the survey with your colleagues, friends, and online communities. The more voices we hear, the better we can understand the diverse needs of Go developers everywhere.

We’re looking forward to hearing your feedback!

Next article: Flight Recorder in Go 1.25
Previous article: A new experimental Go API for JSON
Blog Index

The Go Blog

Type Construction and Cycle Detection

Type Construction and Cycle Detection

Type construction

Recursive types

Recursive types and values

Cycle detection

Where to do it

Conclusion

//go:fix inline and the source-level inliner

//go:fix inline and the source-level inliner

Source-level inlining

Example: renaming ioutil.ReadFile

Example: fixing API design flaws

Under the hood of the inliner

1. Parameter elimination

2. Side effects

3. “Fallible” constant expressions

4. Shadowing

5. Unused variables

6. Defer

An optimizing compiler for “tidiness”

Try it out!

Allocating on the Stack

Allocating on the Stack

Stack allocation of constant-sized slices

Stack allocation of variable-sized slices

Stack allocation of append-allocated slices

Stack allocation of append-allocated escaping slices

Wrapping up

Footnotes

Using go fix to modernize Go code

Using go fix to modernize Go code

Running go fix

Modernizers

Example: a modernizer for Go 1.26’s new(expr)

Synergistic fixes

Merging fixes and conflicts

The Go analysis framework

Improving analysis infrastructure

The “self-service” paradigm

Go 1.26 is released

Go 1.26 is released

Language changes

Performance improvements

Tool improvements

More improvements and changes

Results from the 2025 Go Developer Survey

Results from the 2025 Go Developer Survey

Sections

Who did we hear from?

How do people feel about Go?

What are people building with Go?

What are the biggest challenges facing Go developers?

What does their development environment look like?

Operating systems and architectures

Code editors

Cloud environments

Developing with AI

Closing

Survey methodology

Go’s Sweet 16

Go’s Sweet 16

Core language and library improvements

Secure software development

Under-the-hood improvements

Furthering the software development stack

Looking ahead

The Green Tea Garbage Collector

The Green Tea Garbage Collector

Tracing garbage collection

Objects and pointers

The mark-sweep algorithm

That’s it?

Graph flood example

The problem

Garbage collection costs

“A microarchitectural disaster”

Green Tea

Green Tea example

Example: renaming `ioutil.ReadFile`