Go 1.27 is out, and here is what matters most

Go 1.27 arrived in August 2026, six months after Go 1.26, on the language’s usual cadence. Most of its changes are in the toolchain, runtime, and libraries rather than the language, and the release still holds to the Go 1 promise of compatibility. The Go team expects almost all Go programs to continue to compile and run as before.

If you only read three lines, these are the three:

  • The language now supports generic methods. A method declaration may declare its own type parameters, lifting a restriction that had been in place since generics landed in Go 1.18.
  • encoding/json changed engines without changing its API. The encoding/json/v2 and encoding/json/jsontext packages are now real standard library packages, and v1 is backed by the v2 implementation.
  • Post-quantum cryptography is in the standard library, through the new crypto/mldsa package with support carried into crypto/x509 and crypto/tls.

The rest of this article covers each of those in detail, along with what to check before moving a running system to this version.

Three language changes, and generic methods is the big one

Since generics landed in Go 1.18 one restriction has stayed put: a method could not declare its own type parameters. Any function needing a free type parameter had to move out to package scope, so its name ended up carrying context that belonged to the type, and the API split in two — a set of methods plus a parallel set of loose functions.

Go 1.27 lifts that restriction, and the standard library uses it immediately. math/rand/v2 previously had only the package-scope function N; it now also declares a method that brings its own type parameter:

// The method declares Int itself: func (r *Rand) N[Int intType](n Int) Int
r := rand.New(rand.NewPCG(seed1, seed2))

backoff := r.N(30 * time.Second) // Int is inferred as time.Duration
shard := r.N(int32(16))          // Int is inferred as int32
attempts := r.N(5)               // Int is inferred as int

The math/rand/v2 documentation states that the type parameter Int can be any integer type. The payoff is visible right there: one method covers every integer type without conversions in and out, and without a parallel package-scope function.

The limits that come with it both sit on the interface side:

type Reducer interface {
	// Invalid: interface methods may not declare type parameters
	Reduce[R any](f func(int) R) R
}

Interface methods also cannot be implemented by generic methods. In practice that means the capability belongs to concrete types, not to interface contracts. If you are designing an abstraction around an interface, do not plan to move all your helpers into methods yet — what an interface can express has not changed.

The other two language changes relax existing restrictions:

  • A key in a struct literal may now be any valid field selector for the struct type, not just a top-level field name.
  • Function type inference has been generalized to apply in all contexts where a generic function is assigned to a variable of, or converted to, a matching function type. Cases that used to need explicit type arguments in several places get shorter.

All three add capability rather than removing it, so existing code is not affected by this section.

encoding/json/v2 is the change most likely to touch existing code

Go 1.27 adds two packages at once and changes what sits underneath the package nearly every Go program already uses.

encoding/json after Go 1.27: same surface, new engine

Three packages, ordered from the API your existing code already calls down to the layer that reads and writes JSON syntax directly.

Your existing code calls here

  1. encoding/jsonExisting API
    The v1 API layer most programs already use

    Still the same API and still supported, so no migration is required — but it is now backed by the v2 implementation. Marshaling and unmarshaling behavior is preserved; the exact text of error messages may differ.

  2. encoding/json/v2New in 1.27
    The layer that converts between Go values and JSON

    Provides Marshal, MarshalWrite, MarshalEncode, Unmarshal, UnmarshalRead, and UnmarshalDecode, all accepting variadic Options. Its defaults are stricter than v1: it rejects invalid UTF-8 in JSON strings and rejects duplicate names within an object.

  3. encoding/json/jsontextNew in 1.27
    The purely syntactic JSON layer

    Encoder and Decoder operate on JSON as a sequence of Token and Value, with a state machine ensuring the sequence produced or consumed is always valid JSON. Use it for streaming work that should not be tied to a struct.

v1 calls down into v2 · v2 calls down into jsontext

Escape hatch

If you hit a compatibility problem, set GOEXPERIMENT=nojsonv2 at build time to restore the original v1 implementation. The Go team expects to remove this opt-out in a future release, so treat it as time bought, not a permanent setting.

The first thing to know is purely practical: encoding/json/v2 uses the package name json, exactly like v1. If one file needs both, one of them has to be aliased.

import (
	jsonv1 "encoding/json"   // the v1 API; aliased because the names collide
	"encoding/json/v2"       // the package name here is json
	"encoding/json/jsontext" // the syntactic layer
)

v2 provides Marshal, MarshalWrite, MarshalEncode, Unmarshal, UnmarshalRead, and UnmarshalDecode, all accepting variadic Options. That is the most important design difference from v1: behavior used to be driven mainly by struct tags, and can now be set per call.

type Config struct {
	Name    string `json:"name"`
	Workers int    `json:"workers"`
}

// Deterministic fixes map key ordering — useful when diffing or checksumming output
b, err := json.Marshal(cfg, json.Deterministic(true))
if err != nil {
	return err
}

// Strictness is a per-call decision now, not a property of the type
var got Config
if err := json.Unmarshal(b, &got, json.RejectUnknownMembers(true)); err != nil {
	return err
}

// And you can read straight from an io.Reader with no intermediate []byte
if err := json.UnmarshalRead(resp.Body, &got); err != nil {
	return err
}

Its defaults are stricter and more interoperable than v1 in two main ways: it rejects invalid UTF-8 in JSON strings, and it rejects duplicate names within a single JSON object. The second is the one to watch, because a payload with duplicate keys used to pass through v1 silently, taking the last value.

encoding/json/jsontext sits a layer lower and handles JSON purely as syntax. Its Encoder and Decoder operate on JSON as a sequence of Token and Value, with a state machine ensuring the sequence produced or consumed is always valid JSON text. That suits streaming work which should not be tied to a struct — scanning a large document for one field without decoding the whole thing, for instance:

dec := jsontext.NewDecoder(resp.Body)
for {
	tok, err := dec.ReadToken()
	if errors.Is(err, io.EOF) {
		break
	}
	if err != nil {
		return err
	}
	if tok.Kind() == jsontext.KindString {
		// handle only string tokens
	}
}

Kind is a byte type whose value is the first character of that kind’s symbol in the JSON grammar, so there are named constants — KindString, KindNumber, KindBeginObject, KindEndArray — to compare against instead of raw characters.

The part that touches everyone is that encoding/json is now backed by the v2 implementation. The Go team states that marshaling and unmarshaling behavior is preserved, but the exact text of error messages may differ. The v1 package also gains a number of new Options that configure v2 to operate with v1 semantics, so a full migration to the new API is not required. The Go team is explicit that the v1 API will continue to be supported and that users are not required to migrate.

On performance, the Go team reports that marshal is broadly at parity with the previous implementation, while unmarshal is significantly faster.

Several things were removed or renamed while v2 was still a GOEXPERIMENT, and they are worth knowing before writing new code against v2:

  • The format and unknown tag options were removed.
  • The DiscardUnknownMembers marshal option and the SkipFunc sentinel error were removed.
  • The inline tag option was renamed to embed.
  • Behavior was updated for the string tag option and the MatchCaseInsensitiveNames option.
  • In jsontext, the numeric Token accessors were changed to also return errors.

If the upgrade surfaces a compatibility problem, set GOEXPERIMENT=nojsonv2 at build time to restore the original v1 implementation. The Go team expects to remove this opt-out in a future release, so treat it as time bought to fix the problem rather than a permanent setting.

Runtime: faster allocation, and goroutine leaks you can actually find

The compiler now generates calls to size-specialized memory allocation routines, reducing the cost of some small allocations under 80 bytes by up to 30%. The Go team notes that improvements vary by workload and that the overall improvement is expected to be around 1% in real allocation-heavy programs. The cost is a binary about 60 KB larger, independent of workload. It can be disabled with GOEXPERIMENT=nosizespecializedmalloc at build time, and the Go team expects to remove that option in Go 1.28.

The 30% figure is a reduction in the cost of the allocation itself, not of the whole program. The number to actually expect is the ~1%, and only for allocation-heavy programs.

The second change is worth more to teams operating long-running systems: the goroutine leak profile is now generally available after being an experiment in Go 1.26. The profile type is named goroutineleak and is fetched through runtime/pprof like any other profile:

f, err := os.Create("goroutineleak.pprof")
if err != nil {
	return err
}
defer f.Close()

if p := pprof.Lookup("goroutineleak"); p != nil {
	if err := p.WriteTo(f, 0); err != nil {
		return err
	}
}

If the program already imports net/http/pprof, there is an endpoint to pull it from directly:

go tool pprof http://localhost:6060/debug/pprof/goroutineleak

The definition the runtime uses is precise, and narrower than many people assume. A leaked goroutine is one blocked on a concurrency primitive — a channel, a sync.Mutex, a sync.Cond, and so on — that cannot possibly become unblocked. The runtime detects this using the garbage collector: if a goroutine G is blocked on primitive P, and P is unreachable from any runnable goroutine or any goroutine those could unblock, then P cannot be unblocked and G can never wake up.

The limitation follows directly from that technique. Because it builds on reachability, the runtime may fail to identify leaks caused by blocking on primitives that are still reachable through global variables or through the local variables of runnable goroutines. An empty profile is therefore not proof that nothing is leaking. Unlike the existing goroutine profile, which tells you how many goroutines are parked but not which ones can never wake, this one answers the second question. The Go team credits Vlad Saioc at Uber for contributing this work.

Two more runtime changes affect behavior directly:

  • Tracebacks now carry goroutine labels. For modules with a go 1.27 or later directive, runtime/pprof goroutine labels appear in the traceback header line. This can be disabled with the tracebacklabels=0 GODEBUG setting, which the Go team says it expects to keep indefinitely in case labels acquire sensitive information that should not appear in tracebacks.
  • The asynctimerchan GODEBUG setting has been removed permanently. Channels created by the time package are now always unbuffered and synchronous, regardless of GODEBUG settings.

Cryptography: post-quantum lands in the standard library

The new crypto/mldsa package implements the post-quantum ML-DSA signature scheme specified in FIPS 204. The API follows the same shape as the other crypto packages in the standard library:

sk, err := mldsa.GenerateKey(mldsa.MLDSA65())
if err != nil {
	return err
}

// Context separates signatures made for different purposes; max 255 bytes
opts := &mldsa.Options{Context: "release-manifest"}

sig, err := sk.Sign(nil, manifest, opts)
if err != nil {
	return err
}

if err := mldsa.Verify(sk.PublicKey(), manifest, sig, opts); err != nil {
	return err
}

The easy mistake is Context: the same value must be used when signing and when verifying, or verification fails. The package offers both Sign, which uses randomness, and SignDeterministic for cases that need the same output every time.

Support carries all the way up the stack:

  • crypto/x509 now supports ML-DSA private keys, public keys, and signatures.
  • crypto/tls now supports ML-DSA signatures in TLS 1.3, through three new SignatureScheme values: MLDSA44, MLDSA65, and MLDSA87.
  • crypto adds the MLDSAMu Hash value as a signaling mechanism for External μ ML-DSA signing.

On key exchange, crypto/tls now supports MLKEM1024, which is enabled by adding it to Config.CurvePreferences. Go 1.27 also resolves an earlier confusion: post-quantum hybrid key exchanges can be explicitly enabled in Config.CurvePreferences even when the tlsmlkem=0 or tlssecpmlkem=0 GODEBUG options are set, because those options were only ever meant to apply to the default set used when Config.CurvePreferences is nil.

Other crypto/tls and crypto/x509 changes worth knowing:

  • Config.Rand is now deprecated. For deterministic testing, use testing/cryptotest.SetGlobalRandom instead.
  • The new ConnectionState.LocalCertificate field holds the certificate chain presented to the peer during the handshake.
  • Five GODEBUG settings were removed permanently: tlsunsafeekm, tlsrsakex, tls3des, tls10server, and x509keypairleaf. Systems still depending on those old values have no way back.
  • SystemCertPool now respects the SSL_CERT_FILE and SSL_CERT_DIR environment variables on Windows and Darwin, using the native Go verifier when they are set. This can be disabled with GODEBUG=x509sslcertoverrideplatform=0.

That last item matters for containers and CI environments that already set those two variables without expecting them to affect Go programs. Confirm certificate verification still behaves the same way after upgrading. For systems that span several services and need their trust boundaries defined deliberately, see how to connect AI to ERP, CRM, and internal systems safely.

net/http: changes that affect servers already running

This section changes the behavior of code already in production, not just the available API. Start with the two fields you can set today:

srv := &http.Server{
	Addr:    ":8080",
	Handler: mux,

	// Cap how many header values to accept. Unset falls back to
	// http.DefaultMaxHeaderValueCount, which is 500.
	MaxHeaderValueCount: 1000,

	// Set true to go back to round-robin stream serving,
	// ignoring client priority signals.
	DisableClientPriority: false,
}
  • HTTP/1 Response.Body now drains unread content when closed, up to a conservative limit, to allow better connection reuse. The Go team notes that for most programs this is a no-op or an improvement, but that programs which do not benefit from connection reuse and had been improperly allowing excessive idle connections to linger — usually by setting Transport.MaxIdleConns to 0, or using different Client values per request and so bypassing that limit — might see performance degrade. Setting Transport.DisableKeepAlives to true disables connection reuse, though the Go team observes that this symptom usually indicates Transport or Client was misconfigured in the first place.
  • The HTTP/2 server now accepts client priority signals as defined in RFC 9218, and prioritizes serving higher-priority streams accordingly.
  • Transport and Server support TLS ALPN protocol negotiation on user-provided net.Conn connections which implement a ConnectionState() tls.ConnectionState method.

On the testing side, two additions work well together. net/http/httptest adds NewTestServer, which creates a Server on an in-memory fake network suitable for testing/synctest, and testing/synctest adds a Sleep helper combining time.Sleep and synctest.Wait. Together they make tests involving both time and HTTP genuinely deterministic, without waiting in real time:

func TestRetryBackoff(t *testing.T) {
	synctest.Test(t, func(t *testing.T) {
		srv := httptest.NewTestServer(t, http.HandlerFunc(
			func(w http.ResponseWriter, r *http.Request) {
				w.WriteHeader(http.StatusServiceUnavailable)
			},
		))

		go pollForever(srv.Client(), srv.URL)

		// Advance the fake clock five seconds, then wait for goroutines to settle
		synctest.Sleep(5 * time.Second)

		// Now assert how many times the poller actually fired
	})
}

NewTestServer takes a testing.TB as its first argument, so it closes the server when the test ends — no defer srv.Close() needed.

Tooling: go test, go doc, go fix, and go mod tidy

go test now invokes the stdversion vet check by default. It reports use of standard library symbols that are too new for the Go version in force in the referring file, as determined by the go directive in go.mod and build tags on the file. Code that accidentally reaches for a new API while declaring support for an older version is caught at test time rather than on a user’s machine.

go test -json now annotates "Action":"output" lines with an optional "OutputType" field specifying the type of output. The possible values currently include "error", "error-continue", and "frame". The structure below is illustrative — it shows where the new field sits, and is not captured output from a real run:

{
  "Action": "output",
  "Package": "example.com/app",
  "Test": "TestUpgrade",
  "Output": "    main_test.go:42: unexpected status 500\n",
  "OutputType": "error"
}

Teams that parse test output in CI gain the most here, because error lines can be separated from ordinary output without guessing from the message format.

Other commands that changed:

go doc example.com/pkg@v1.2.3
go doc -ex bytes.Buffer
go fix ./...
go mod tidy
  • go doc now supports package@version syntax and accepts the -ex option to list executable examples of a given package or symbol. Passing an example name prints the example source code along with its comments.
  • go fix gains four modernizers: atomictypes, embedlit, slicesbackward, and unsafefuncs. The fmtappendf analyzer was removed due to stylistic concerns, and the waitgroup analyzer was renamed to waitgroupgo to avoid ambiguity.
  • go mod tidy now merges duplicate require blocks automatically for modules specifying go 1.27 or later, leaving at most two require blocks — one direct and one indirect — while preserving comment blocks attached to dependencies. It fixes go.mod files that accumulated disjoint require blocks from manual edits, unresolved merge conflicts, or legacy upgrades.
  • go tool trace now restricts the listen address to localhost when -http is passed only a port, such as -http=:6060, matching go tool pprof. To listen on all addresses, specify one explicitly, such as -http=0.0.0.0:6060.
  • The go command no longer supports the bzr version control system. Modules hosted on bzr servers can no longer be fetched directly.

Separately, the compile, link, asm, cgo, cover, and pack tools now support @file response file parsing. The format is compatible with GCC’s response files so existing build systems interoperate.

Small things you can use immediately

strings.CutLast and bytes.CutLast are the clearest win. Both cut around the last separator and have exactly the same signature as the existing Cut:

// Before: LastIndex, two slice expressions, and your own bounds check
host, port := addr, ""
if i := strings.LastIndex(addr, ":"); i >= 0 {
	host, port = addr[:i], addr[i+1:]
}

// Go 1.27: func CutLast(s, sep string) (before, after string, found bool)
host, port, ok := strings.CutLast(addr, ":")
if !ok {
	// no separator: host is all of addr, port is empty
}

The rest change nobody’s architecture, but they do remove real annoyances:

  • net/url adds URL.Clone and Values.Clone for deep copies.
  • math/big adds Int.Divide, computing quotient and remainder in one call. The signature is func (z *Int) Divide(x, y, r *Int, mode RoundingMode) (*Int, *Int), and this release adds the four rounding constants Trunc, Floor, Round, and Ceil.
  • database/sql adds ConvertAssign, giving drivers access to the same type conversions Rows.Scan uses, and database/sql/driver adds the RowsColumnScanner interface, with NextRow and ScanColumn methods, for scanning directly into user-provided destinations.
  • The new uuid package generates and parses UUIDs, with uuid.New() for random version 4, uuid.NewV7() for time-ordered version 7, and uuid.Parse(s string) (UUID, error).
  • hash/maphash adds the Hasher interface and the ComparableHasher type, while go/types adds Hasher and HasherIgnoreTags so Type values can be used in hash tables.
  • unicode and associated support throughout the system moved from Unicode 15 to Unicode 17.
  • net changed UnixConn read methods to return io.EOF directly rather than wrapped in a net.OpError.

uuid.NewV7() is the one worth noting for database work: version 7 UUIDs lead with a timestamp, so values generated close together sort close together, unlike version 4, which is random throughout and scatters an index.

For SIMD work, Go 1.27 adds the experimental simd package, which provides vector types of unspecified size such as Int8s and Float32s and is available on all architectures. The simd/archsimd package begun in Go 1.26 adds arm64 Neon 128-bit and WebAssembly 128-bit support. Both are enabled with GOEXPERIMENT=simd at build time and their APIs are not yet stable, so production systems should not depend on them yet.

Check these five gates before moving production

The order to verify before moving production to Go 1.27

Five gates ordered from what fails loudly to what fails quietly, each with what to check and what to do when it does not pass.

  1. Build and vet
    • go test now runs the stdversion vet check by default, reporting standard library symbols too new for the version set by the go directive.
    • The go command now fails when go.mod or a //go:debug comment pins a removed GODEBUG setting to its old value.
    • Modules hosted on bzr servers can no longer be fetched.
    • Build and run hosts on macOS must be macOS 13 Ventura or later.

    If it does not passCorrect the go directive to match reality, and set any removed GODEBUG to the final default value it had before removal — the go command still accepts that.

  2. Byte-for-byte output
    • compress/flate is faster, but the exact bytes its Writer produces may differ from Go 1.26.
    • DEFLATE is the compression underneath archive/zip, compress/gzip, compress/zlib, and image/png, so output from all four may change too.
    • Golden files, checksums, and signatures computed over compressed bytes are what break first.

    If it does not passThere is no switch for this one. Compare data after decompression rather than comparing the compressed bytes.

  3. Runtime behavior
    • The asynctimerchan GODEBUG is permanently removed; channels created by the time package are now always unbuffered.
    • HTTP/1 Response.Body now drains unread content when closed, up to a conservative limit, to allow better connection reuse.
    • The HTTP/2 server now accepts RFC 9218 client priority signals.
    • The compiler gives function literals shorter, inlining-independent names. Tests asserting symbol names may need updating, and code that compares function code pointers for equality is more exposed.

    If it does not passSet Server.DisableClientPriority to true to restore round-robin serving, and Transport.DisableKeepAlives to true to disable connection reuse.

  4. JSON
    • encoding/json keeps the same API but is now backed by the v2 implementation.
    • Marshaling and unmarshaling behavior is preserved, but the exact text of error messages may differ.
    • Tests or log parsers matching on literal error strings are what break.

    If it does not passSet GOEXPERIMENT=nojsonv2 at build time to restore the v1 implementation. The Go team expects to remove this opt-out in a future release.

  5. Measure after the upgrade
    • The compiler now calls size-specialized allocation routines, cutting the cost of some allocations under 80 bytes by up to 30%, with roughly 1% overall expected in allocation-heavy programs.
    • Binaries grow by about 60 KB, independent of workload.
    • The goroutineleak profile is now generally available in runtime/pprof and at the /debug/pprof/goroutineleak endpoint.

    If it does not passSet GOEXPERIMENT=nosizespecializedmalloc at build time to disable size-specialized allocation. The Go team expects to remove this option in Go 1.28.

What has not changed

Go 1.27 still holds to the Go 1 promise of compatibility, and the Go team expects almost all programs to compile and run as before. These five gates are a list to check, not a list expected to fail.

Two things outside your code can decide whether the upgrade is possible at all:

  • macOS must be version 13 Ventura or later, as announced in the Go 1.26 release notes; support for previous versions has been discontinued. Developer machines and CI runners still on older macOS have to move first.
  • Big-endian 64-bit PowerPC on Linux — GOOS=linux with GOARCH=ppc64 — now generates binaries using the ELFv2 system ABI, which requires Linux kernel 3.13 or later. RHEL7 backported that support into its own 3.10 kernel. The gain is that cgo, position-independent executables, and external linking are now supported, but using them requires an ELFv2-compatible runtime: libc and every linked and loaded library. For programs that do not use cgo, the toolchain still generates static binaries with internal linking by default; for programs with cgo options that need a static, pure-Go binary, set CGO_ENABLED=0 when running go build.

Once all five gates pass, the way to confirm each escape hatch still works is to build with that option and run the same test suite again:

GOEXPERIMENT=nojsonv2 go build ./...
GOEXPERIMENT=nosizespecializedmalloc go build ./...

Conclusion: upgrade, but give three places real attention

Go 1.27 adds far more than it removes and still holds to the Go 1 promise of compatibility. For most projects the upgrade will be a matter of running the test suite and moving on.

The three places worth genuine attention are the error message text from encoding/json, which may change now that v1 runs on v2; the bytes produced by compress/flate and the packages built on DEFLATE, which may differ from Go 1.26; and the net/http behavior around draining Response.Body on close together with HTTP/2 stream prioritization. Each has a documented escape hatch or a clear fix, but none of them announces itself unless you go looking.

After the upgrade, the new feature with the fastest payback is the goroutineleak profile, because it turns finding stuck goroutines from guesswork into measurement and needs no code changes to start using.

If you want help assessing an upgrade plan or designing a backend that stays maintainable, read more about our software and custom systems development service or contact Nixxel to start scoping the problem.

Sources and further reading