Go 127

Go 1.27 — What Changed and What To Do About It

Released: August 2026, six months after Go 1.26. Go 1 compatibility holds; almost all programs compile and run unchanged.

Sources: go.dev/doc/go1.27 (authoritative) · victoriametrics.com/blog/go-1-27 (worked examples). Every claim below is from one of those two, or from reading $(go env GOROOT)/src on the installed 1.27.0 toolchain.

Companion skill: code-guidelines-go holds the standing style rules. This skill holds only what 1.27 changed.

0. Read this first — GOEXPERIMENT=none is set on this machine

go env on this host persists GOEXPERIMENT=none, which does not mean "no extra experiments" — it clears the 1.27 baseline, which enables JSONv2, GreenTeaGC, SizeSpecializedMalloc, Dwarf5 and RandomizedHeapBase64 (src/internal/buildcfg/exp.go:81). Verified consequences here:

$ go build ./...                      # importing encoding/json/v2
imports encoding/json/v2: build constraints exclude all Go files in .../encoding/json/v2

$ golangci-lint --version
golangci-lint has version 2.13.1 built with go1.27.0-X:nojsonv2,nogreenteagc,
norandomizedheapbase64,nosizespecializedmalloc

So on this machine encoding/json/v2 will not import, and the 1.27 allocator and GC work are switched off. Before benchmarking anything or trying a v2 snippet:

go env GOEXPERIMENT          # prints "none" -> baseline is cleared
go env -u GOEXPERIMENT       # restore the default baseline (user decision — ask first)
GOEXPERIMENT=jsonv2 go build ./...   # or scope it to one command

Do not silently change the user's go env config. Flag it, and scope the experiment to the command you are running.

1. Language changes

1.1 Generic methods — methods may declare their own type parameters

The headline change. Before 1.27 a generic operation on a type had to be a package-level function; now it can live on the type.

// ✗ Before 1.27 — generic op stranded at package scope
type Box[T any] struct{ v T }
func MapBox[T, U any](b Box[T], f func(T) U) Box[U] { return Box[U]{v: f(b.v)} }

// ✓ Go 1.27 — the method declares its own type parameter U
type Box[T any] struct{ v T }
func (b Box[T]) Map[U any](f func(T) U) Box[U] { return Box[U]{v: f(b.v)} }

b := Box[int]{v: 21}
label := b.Map(func(n int) int { return n * 2 }).
    Map(func(n int) string { return fmt.Sprintf("value=%d", n) })

Two hard restrictions, both compiler-enforced:

• Interfaces may not declare type-parameterized methods. Map[U any](...) inside an interface fails with interface method must have no type parameters.
• A generic method cannot implement an interface method. So a generic method is never part of a type's interface satisfaction set.

Prescription for pi-go: this is the right tool for transforms on a concrete generic container (a typed cache, a typed result set). It is the wrong tool anywhere the type is consumed through an interface — and pi-go's design rule is "define interfaces at the consumer" (code-guidelines-go §1). If a call site takes an interface, keep the package-level generic function.

1.2 Struct literal keys may be any valid field selector

A key in a struct literal is no longer restricted to a top-level field name, so promoted fields from an embedded struct can be set directly.

type Base struct{ ID int }
type User struct {
    Base
    Name string
}

u := User{Base: Base{ID: 7}, Name: "Mittens"}  // ✗ before 1.27, the only way
u := User{ID: 7, Name: "Mittens"}              // ✓ Go 1.27

go fix's new embedlit modernizer rewrites the old form for you (see §2.4).

1.3 Function type inference generalized

Inference now applies in every context where a generic function is assigned to or converted to a matching function type — not just plain assignment. Composite literals and conversions now infer too.

func first[T any](s []T) T { return s[0] }
func last[T any](s []T) T  { return s[len(s)-1] }

ops := []func([]int) int{first[int], last[int]}  // ✗ before 1.27: explicit instantiation
ops := []func([]int) int{first, last}            // ✓ Go 1.27: element type drives T=int

The old failure was cannot use generic function without instantiation (VM blog). If you see leftover [int] instantiations in a slice or map literal of function types, they can now be deleted.

2. Toolchain, go command, modules

2.1 go test runs stdversion by default

go test now invokes the stdversion vet check, which reports use of stdlib symbols newer than the go directive in go.mod (adjusted by build tags on the file). This is the guard that catches "works on my machine": calling strings.CutLast from a module still declaring go 1.26 is now a test failure, not a silent success.

Prescription: when you use a 1.27 stdlib symbol, bump go.mod in the same change. Do not //nolint around it.

2.2 GODEBUG settings that were removed still parse

From 1.27 the go command accepts a removed GODEBUG setting in go.mod (godebug lines) and //go:debug comments if it is set to the final default value established before removal. Set to an old value, the go command fails. So //go:debug asynctimerchan=0 still builds; asynctimerchan=1 is now a hard error.

2.3 go mod tidy enforces a two-block require layout

For modules declaring go 1.27 or later, go mod tidy merges duplicate require blocks into at most two — direct and indirect — preserving attached comment blocks. A comment block spanning a mixed set of directives is merged onto the direct block.

Expect a large go.mod diff on the first go mod tidy after the version bump. Review it, do not fight it.

2.4 go fix modernizers

Verified against go tool fix help on 1.27.0:

fmtappendf was removed (stylistic concerns). If a script or CI job names waitgroup or fmtappendf, it breaks.

2.5 go doc

• go doc example.com/pkg@v1.2.3 — documentation at a specific module version.
• go doc -ex <pkg> — list a package's runnable examples (verified: go doc -ex strings interleaves func ExampleTrimSpace() lines under each symbol).
• go doc bytes.ExampleBuffer — prints the example's source with comments.

2.6 Other tool changes

• bzr support removed from the go command; modules on Bazaar servers can no longer be fetched directly.
• go tool trace -http=:6060 now binds localhost only, matching go tool pprof. Pass -http=0.0.0.0:6060 to listen on all interfaces. Relevant to the go-pprof workflow in AGENTS.md.
• Response files (@file) are accepted by compile, link, asm, cgo, cover and pack, in GCC's format.
• Linker: -macos and -macsdk set OS/SDK versions in LC_BUILD_VERSION. Defaults: macOS 13.0.0, SDK 26.2.0.

3. Runtime, GC, performance, profiling

3.1 Faster small allocations — free, but off on this machine

The compiler emits calls to size-specialized allocation routines, cutting the cost of some allocations under 80 bytes by up to 30%, ~1% overall in allocation-heavy programs, at ~60 KB more binary size (workload-independent). Nothing to change in code.

Opt-out is GOEXPERIMENT=nosizespecializedmalloc, expected to be removed in Go 1.28. Per §0, GOEXPERIMENT=none on this host already disables it — so any allocation benchmark run here is measuring the old allocator.

3.2 goroutineleak profile is now GA

The goroutine leak profile, experimental in 1.26, is generally available. No GOEXPERIMENT needed; the goroutineleakprofile GOEXPERIMENT setting is deleted.

// scrape in-process
pprof.Lookup("goroutineleak").WriteTo(os.Stdout, 1)

Or the net/http/pprof endpoint /debug/pprof/goroutineleak — which is what pi-go should use, since it already serves pprof on :6060 under pi --pprof true.

A goroutine counts as leaked when it is blocked on a concurrency primitive (channel, sync.Mutex, sync.Cond, …) that the GC proves unreachable from any runnable goroutine or anything those could unblock — so it can never be unblocked. Known blind spot: leaks where the primitive is reachable through a global, or through the locals of a runnable goroutine, are not detected. Long-lived registries in pi-go fall exactly in that gap, so a clean profile is not proof of no leak. Keep goleak.VerifyTestMain(m) in tests.

3.3 Goroutine labels in tracebacks

For modules with go 1.27 or later, runtime/pprof goroutine labels appear in the traceback header line — in panics, SIGQUIT dumps and runtime.Stack output:

goroutine 1 [running] {request: 42}:

Anything already wrapped in pprof.Do(ctx, pprof.Labels(...), ...) now leaks that context into crash output. Check pi-go's labels for anything sensitive (session ids are fine; API keys or prompt text are not) before bumping the go directive. Opt-out is GODEBUG=tracebacklabels=0, added in 1.26 and expected to be kept indefinitely.

3.4 Compiler changes with observable effects

• Function literal (closure) names are now simpler and inlining-independent, and the compiler may share one compiled body across multiple inlined instances. Tests that assert on symbol names may need updating — better, stop asserting on them.
• Consequently, comparing function code pointers for equality is more broken than before: distinct closures with different captured data can now share a code pointer. Go never defined func comparison beyond == nil; 1.27 just exposes it more.
• Relative filenames in //line / /*line*/ directives resolve against the containing file's directory (#70478), matching go/scanner.

4. Standard library

4.1 encoding/json/v2 and encoding/json/jsontext (new)

import (
    json "encoding/json/v2"
    "encoding/json/jsontext"
)

data, err := json.Marshal(Point{X: 1, Y: 2}, opts...)   // variadic Options
err = json.MarshalWrite(w, v, opts...)                   // to an io.Writer
err = json.MarshalEncode(enc, v, opts...)                // to a *jsontext.Encoder
err = json.Unmarshal(data, &v, opts...)
err = json.UnmarshalRead(r, &v, opts...)
err = json.UnmarshalDecode(dec, &v, opts...)

jsontext is the syntactic layer: Encoder, Decoder, Token, Value, with a state machine enforcing valid JSON.

v2 chooses stricter defaults than v1: it rejects invalid UTF-8 in strings and rejects duplicate object names. It also does not sort map keys (v1 always did) — pass json.Deterministic(true) when you need stable output for golden files.

encoding/json (v1) is now backed by v2. Behavior is preserved; error message text may differ. If any pi-go test asserts on a JSON error string, that is the thing most likely to break — assert on error identity or a substring you control instead. Marshal is at parity; unmarshal is significantly faster. Escape hatch: GOEXPERIMENT=nojsonv2 (expected to be removed in a future release).

Prescription: no migration is required and v1 stays supported. Keep pi-go on v1 unless a call site actually wants v2's strictness or its options; do not do a mechanical sweep.

4.2 uuid (new, top-level stdlib package)

Implements RFC 9562, seeded from a cryptographically secure RNG. UUID is [16]byte, so it is comparable with == and usable as a map key.

id := uuid.New()      // suitable for most purposes; currently == NewV4
r  := uuid.NewV4()    // 122 bits of randomness
k  := uuid.NewV7()    // 48-bit timestamp prefix — sorts by creation time
u, err := uuid.Parse("f81d4fae-7dec-11d0-a765-00a0c91e6bf6")
m := uuid.MustParse(s)          // panics on bad input
uuid.Nil(); uuid.Max()          // functions, not vars
u.String(); u.Compare(v)        // Compare is big-endian, RFC 9562 §6.11

UUID implements encoding.TextMarshaler, TextAppender and TextUnmarshaler.

Prescription for pi-go: drop github.com/google/uuid for new code. For anything written to $HOME/.pi-go/sessions/ or used as a database/session key, prefer NewV7 — time-ordered ids sort chronologically, which is exactly what the session directory listing wants.

4.3 crypto/mldsa (new) — post-quantum signatures

FIPS 204 ML-DSA, in three parameter sets returned by functions: mldsa.MLDSA44(), MLDSA65(), MLDSA87(). Parameters exposes PublicKeySize(), SignatureSize(), String().

priv, err := mldsa.GenerateKey(mldsa.MLDSA65())
sig, err := priv.Sign(rand.Reader, msg, crypto.Hash(0))
err = mldsa.Verify(priv.PublicKey(), msg, sig, nil)

crypto/x509 handles ML-DSA keys and signatures; crypto/tls gains the MLDSA44, MLDSA65, MLDSA87 SignatureScheme values for TLS 1.3. crypto.MLDSAMu is a new Hash sentinel for external-μ signing (it panics if passed to RegisterHash).