Next Release Notes Draft

DRAFT RELEASE NOTES — Introduction to Go 1.N

Go 1.25 is not yet released. These are work-in-progress release notes. Go 1.25 is expected to be released in August 2025.

Tools

Go command

The go build -asan option now defaults to doing leak detection at program exit. This will report an error if memory allocated by C is not freed and is not referenced by any other memory allocated by either C or Go. These new error reports may be disabled by setting ASAN_OPTIONS=detect_leaks=0 in the environment when running the program.

The new work package pattern matches all packages in the work (formerly called main) modules: either the single work module in module mode or the set of workspace modules in workspace mode.

When the go command updates the go line in a go.mod or go.work file, it no longer adds a toolchain line specifying the command’s current version.

Vet

The go vet command includes new analyzers:

Runtime

The message printed when a program exits due to an unhandled panic that was recovered and repanicked no longer repeats the text of the panic value.

Previously, a program which panicked with panic("PANIC"), recovered the panic, and then repanicked with the original value would print:

panic: PANIC [recovered]
  panic: PANIC

This program will now print:

panic: PANIC [recovered, repanicked]

The default behavior of the GOMAXPROCS has changed. In prior versions of Go, GOMAXPROCS defaults to the number of logical CPUs available at startup (runtime.NumCPU). Go 1.25 introduces two changes:

  1. On Linux, the runtime considers the CPU bandwidth limit of the cgroup containing the process, if any. If the CPU bandwidth limit is lower than the number of logical CPUs available, GOMAXPROCS will default to the lower limit. In container runtime systems like Kubernetes, cgroup CPU bandwidth limits generally correspond to the “CPU limit” option. The Go runtime does not consider the “CPU requests” option.

  2. On all OSes, the runtime periodically updates GOMAXPROCS if the number of logical CPUs available or the cgroup CPU bandwidth limit change.

Both of these behaviors are automatically disabled if GOMAXPROCS is set manually via the GOMAXPROCS environment variable or a call to runtime.GOMAXPROCS. They can also be disabled explicitly with the GODEBUG settings containermaxprocs=0 and updatemaxprocs=0, respectively.

In order to support reading updated cgroup limits, the runtime will keep cached file descriptors for the cgroup files for the duration of the process lifetime.

On Linux systems with kernel support for anonymous VMA names (CONFIG_ANON_VMA_NAME), the Go runtime will annotate anonymous memory mappings with context about their purpose. e.g., [anon: Go: heap] for heap memory. This can be disabled with the GODEBUG setting decoratemappings=0.

A new experimental garbage collector is now available as an experiment. The new design aims to improve the efficiency of garbage collection through better locality and CPU scalability in the mark algorithm. Benchmark result vary, but we expect somewhere between a 10—40% reduction in garbage collection overhead in real-world programs that heavily use the garbage collector.

The new garbage collector may be enabled by setting GOEXPERIMENT=greenteagc at build time. See the GitHub issue for more details on the design and instructions on how to report feedback.

Compiler

The compiler and linker in Go 1.25 now generate debug information using DWARF version 5; the newer DWARF version reduces the space required for debugging information in Go binaries. DWARF 5 generation is gated by the “dwarf5” GOEXPERIMENT; this functionality can be disabled (for now) using GOEXPERIMENT=nodwarf5.

The compiler has been fixed to ensure that nil pointer checks are performed promptly. Programs like the following, which used to execute successfully, will now panic with a nil-pointer exception:

package main

import "os"

func main() {
    f, err := os.Open("nonExistentFile")
    name := f.Name()
    if err != nil {
        return
    }
    println(name)
}

This program is incorrect in that it uses the result of os.Open before checking the error. The main result of os.Open can be a nil pointer if the error result is non-nil. But because of a compiler bug, this program ran successfully under Go versions 1.21 through 1.24 (in violation of the Go spec). It will no longer run successfully in Go 1.25. If this change is affecting your code, the solution is to put the non-nil error check earlier in your code, preferably immediately after the error-generating statement.

The compiler can now allocate the backing store for slices on the stack in more situations, which improves performance. This change has the potential to amplify the effects of incorrect unsafe.Pointer usage, see for example issue 73199. In order to track down these problems, the bisect tool can be used to find the allocation causing trouble using the -compile=variablemake flag. All such new stack allocations can also be turned off using -gcflags=all=-d=variablemakehash=n.

Standard library

New testing/synctest package

The new testing/synctest package provides support for testing concurrent code.

The synctest.Test function runs a test function in an isolated “bubble”. Within the bubble, time package functions operate on a fake clock.

The synctest.Wait function waits for all goroutines in the current bubble to block.

Minor changes to the library

archive/tar

The *Writer.AddFS implementation now supports symbolic links for filesystems that implement io/fs.ReadLinkFS.

crypto

MessageSigner is a new signing interface that can be implemented by signers that wish to hash the message to be signed themselves. A new function is also introduced, SignMessage which attempts to update a Signer interface to MessageSigner, using the MessageSigner.SignMessage method if successful, and Signer.Sign if not. This can be used when code wishes to support both Signer and MessageSigner.

crypto/ecdsa

The new ParseRawPrivateKey, ParseUncompressedPublicKey, PrivateKey.Bytes, and PublicKey.Bytes functions and methods implement low-level encodings, replacing the need to use crypto/elliptic or math/big functions and methods.

crypto/elliptic

The hidden and undocumented Inverse and CombinedMult methods on some Curve implementations have been removed.

crypto/sha3

The new SHA3.Clone method implements hash.Cloner.

crypto/tls

The new ConnectionState.CurveID field exposes the key exchange mechanism used to establish the connection.

The new Config.GetEncryptedClientHelloKeys callback can be used to set the [EncryptedClientHelloKey]s for a server to use when a client sends an Encrypted Client Hello extension.

SHA-1 signature algorithms are now disallowed in TLS 1.2 handshakes, per RFC 9155. They can be re-enabled with the tlssha1=1 GODEBUG option.

When FIPS 140-3 mode is enabled, Extended Master Secret is now required in TLS 1.2, and Ed25519 and X25519MLKEM768 are now allowed.

TLS servers now prefer the highest supported protocol version, even if it isn’t the client’s most preferred protocol version.

crypto/x509

CreateCertificate, CreateCertificateRequest, and CreateRevocationList can now accept a crypto.MessageSigner signing interface as well as crypto.Signer. This allows these functions to use signers which implement “one-shot” signing interfaces, where hashing is done as part of the signing operation, instead of by the caller.

CreateCertificate now uses truncated SHA-256 to populate the SubjectKeyId if it is missing. The GODEBUG setting x509sha256skid=0 reverts to SHA-1.

debug/elf

The debug/elf package adds two new constants:

go/ast

The new PreorderStack function, like Inspect, traverses a syntax tree and provides control over descent into subtrees, but as a convenience it also provides the stack of enclosing nodes at each point.

go/parser

The ParseDir function is deprecated.

go/token

The new FileSet.AddExistingFiles method enables existing Files to be added to a FileSet, or a FileSet to be constructed for an arbitrary set of Files, alleviating the problems associated with a single global FileSet in long-lived applications.

go/types

Var now has a Var.Kind method that classifies the variable as one of: package-level, receiver, parameter, result, or local variable, or a struct field.

The new LookupSelection function looks up the field or method of a given name and receiver type, like the existing LookupFieldOrMethod function, but returns the result in the form of a Selection.

hash

The new XOF interface can be implemented by “extendable output functions”, which are hash functions with arbitrary or unlimited output length such as SHAKE.

Hashes implementing the new Cloner interface can return a copy of their state. All standard library Hash implementations now implement Cloner.

hash/maphash

The new Hash.Clone method implements hash.Cloner.

io/fs

A new ReadLinkFS interface provides the ability to read symbolic links in a filesystem.

log/slog

GroupAttrs creates a group Attr from a slice of Attr values.

Record now has a Source() method, returning its source location or nil if unavailable.

mime/multipart

The new helper function FieldContentDisposition builds multipart Content-Disposition header fields.

net

On Windows, the TCPConn.File, UDPConn.File, UnixConn.File, IPConn.File, TCPListener.File, and UnixListener.File methods are now supported.

LookupMX and *Resolver.LookupMX now return DNS names that look like valid IP address, as well as valid domain names. Previously if a name server returned an IP address as a DNS name, LookupMX would discard it, as required by the RFCs. However, name servers in practice do sometimes return IP addresses.

On Windows, the ListenMulticastUDP now supports IPv6 addresses.

On Windows, the FileConn, FilePacketConn, FileListener functions are now supported.

net/http

The new CrossOriginProtection implements protections against Cross-Site Request Forgery (CSRF) by rejecting non-safe cross-origin browser requests. It uses modern browser Fetch metadata, doesn’t require tokens or cookies, and supports origin-based and pattern-based bypasses.

os

On Windows, NewFile now supports handles opened for asynchronous I/O (that is, syscall.FILE_FLAG_OVERLAPPED is specified in the syscall.CreateFile call). These handles are associated with the Go runtime’s I/O completion port, which provides the following benefits for the resulting File:

This enhancement is especially beneficial for applications that communicate via named pipes on Windows.

Note that a handle can only be associated with one completion port at a time. If the handle provided to NewFile is already associated with a completion port, the returned File is downgraded to synchronous I/O mode. In this case, I/O methods will block an OS thread, and the deadline methods have no effect.

The filesystem returned by DirFS implements the new io/fs.ReadLinkFS interface. CopyFS supports symlinks when copying filesystems that implement io/fs.ReadLinkFS.

The os.Root type supports the following additional methods:

reflect

The new TypeAssert function permits converting a Value directly to a Go value of the given type. This is like using a type assertion on the result of Value.Interface, but avoids unnecessary memory allocations.

regexp/syntax

The \p{name} and \P{name} character class syntaxes now accept the names Any, ASCII, Assigned, Cn, and LC, as well as Unicode category aliases like \p{Letter} for \pL. Following Unicode TR18, they also now use case-insensitive name lookups, ignoring spaces, underscores, and hyphens.

runtime

Cleanup functions scheduled by AddCleanup are now executed concurrently and in parallel, making cleanups more viable for heavy use like the unique package. Note that individual cleanups should still shunt their work to a new goroutine if they must execute or block for a long time to avoid blocking the cleanup queue.

When GODEBUG=checkfinalizers=1 is set, the runtime will run diagnostics on each garbage collection cycle to find common issues with how the program might use finalizers and cleanups, such as those described in the GC guide. In this mode, the runtime will also regularly report the finalizer and cleanup queue lengths to stderr to help identify issues with long-running finalizers and/or cleanups.

The new SetDefaultGOMAXPROCS function sets GOMAXPROCS to the runtime default value, as if the GOMAXPROCS environment variable is not set. This is useful for enabling the new GOMAXPROCS default if it has been disabled by the GOMAXPROCS environment variable or a prior call to GOMAXPROCS.

runtime/pprof

The mutex profile for contention on runtime-internal locks now correctly points to the end of the critical section that caused the delay. This matches the profile’s behavior for contention on sync.Mutex values. The runtimecontentionstacks setting for GODEBUG, which allowed opting in to the unusual behavior of Go 1.22 through 1.24 for this part of the profile, is now gone.

runtime/trace

TODO The flight recorder has been added to the runtime/trace package.

sync

WaitGroup has added a new method WaitGroup.Go, that makes the common pattern of creating and counting goroutines more convenient.

testing

The new methods T.Attr, B.Attr, and F.Attr emit an attribute to the test log. An attribute is an arbitrary key and value associated with a test.

For example, in a test named TestAttr, t.Attr("key", "value") emits:

=== ATTR  TestAttr key value

The new Output method of testing.T, testing.B and testing.F provides a Writer that writes to the same test output stream as TB.Log, but omits the file and line number.

testing/fstest

MapFS implements the new io/fs.ReadLinkFS interface. TestFS will verify the functionality of the io/fs.ReadLinkFS interface if implemented. TestFS will no longer follow symlinks to avoid unbounded recursion.

testing/synctest

unicode

The new CategoryAliases map provides access to category alias names, such as “Letter” for “L”. The new categories Cn and LC define unassigned codepoints and cased letters, respectively. These have always been defined by Unicode but were inadvertently omitted in earlier versions of Go. The C category now includes Cn, meaning it has added all unassigned code points.

unique

The unique package now reclaims interned values more eagerly, more efficiently, and in parallel. As a consequence, applications using Make are now less likely to experience memory blow-up when lots of truly unique values are interned.

Values passed to Make containing [Handle]s previously required multiple garbage collection cycles to collect, proportional to the depth of the chain of Handle values. Now, they are collected promptly in a single cycle, once unused.

Ports

Darwin

As announced in the Go 1.24 release notes, Go 1.25 requires macOS 12 Monterey or later; support for previous versions has been discontinued.

Windows

Go 1.25 is the last release that contains the broken 32-bit windows/arm port (GOOS=windows GOARCH=arm). It will be removed in Go 1.26.

all: implement plugin build mode for riscv64

cmd/link/internal/ld: introduce -funcalign=N option
This patch adds linker option -funcalign=N that allows to set alignment for function entries.
For #72130.

cmd/fix: automate migrations for simple deprecations

cmd/go: allow serving module under the subdirectory of git repository
cmd/go: add subdirectory support to go-import meta tag
This CL adds ability to specify a subdirectory in the go-import meta tag. A go-import meta tag now will support: <meta name=“go-import” content=“root-path vcs repo-url subdir”>
Fixes: #34055

cmd/go: add global ignore mechanism for Go tooling ecosystem

cmd/cover: extend coverage testing to include applications

all: add GOARM64=v8.1 and so on
runtime: check LSE support on ARM64 at runtime init
Check presence of LSE support on ARM64 chip if we targeted it at compile time.
Related to #69124
Updates #60905
Fixes #71411

all: add GORISCV64 environment variable
cmd/go: add rva23u64 as a valid value for GORISCV64
The RVA23 profile was ratified on the 21st of October 2024. https://riscv.org/announcements/2024/10/risc-v-announces-ratification-of-the-rva23-profile-standard/ Now that it’s ratified we can add rva23u64 as a valid value for the GORISCV64 environment variable. This will allow the compiler and assembler to generate instructions made mandatory by the new profile without a runtime check. Examples of such instructions include those introduced by the Vector and Zicond extensions. Setting GORISCV64=rva23u64 defines the riscv64.rva20u64, riscv64.rva22u64 and riscv64.rva23u64 build tags, sets the internal variable buildcfg.GORISCV64 to 23 and defines the macros GORISCV64_rva23u64, hasV, hasZba, hasZbb, hasZbs, hasZfa, and hasZicond for use in assembly language code.
Updates #61476

math/rand/v2: revised API for math/rand
rand: deprecate in favor of math/rand/v2
For golang/go#61716
Fixes golang/go#71373

cmd/go: enable GOCACHEPROG by default
cmd/go/internal/cacheprog: drop Request.ObjectID
ObjectID was a misnaming of OutputID from cacheprog’s initial implementation. It was maintained for compatibility with existing cacheprog users in 1.24 but can be removed in 1.25.

cmd/go: doc -http should start a pkgsite instance and open a browser

cmd/go: -json flag for go version -m
cmd/go: support -json flag in go version
It supports features described in the issue:

crypto: mechanism to enable FIPS mode

spec: remove notion of core types

cmd/go: add fips140 module selection mechanism
lib/fips140: set inprocess.txt to v1.0.0

testing: panic in AllocsPerRun during parallel test
testing: panic in AllocsPerRun if parallel tests are running
If other tests are running, AllocsPerRun’s result will be inherently flaky. Saw this with CL 630136 and #70327.
Proposed in #70464.
Fixes #70464.

encoding/json/v2: add new JSON API behind a GOEXPERIMENT=jsonv2 guard

cmd/go, cmd/distpack: build and run tools that are not necessary for builds as needed and don’t include in binary distribution

go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.