Go 1.25 Release Notes

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:

• waitgroup, which reports misplaced calls to sync.WaitGroup.Add; and

• hostport, which reports uses of fmt.Sprintf("%s:%d", host, port) to construct addresses for net.Dial, as these will not work with IPv6; instead it suggests using net.JoinHostPort.

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]

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.

Standard library

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/elliptic

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

crypto/tls

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

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

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.

debug/elf

The debug/elf package adds two new constants:

• PT_RISCV_ATTRIBUTES
• SHT_RISCV_ATTRIBUTES for RISC-V ELF parsing.

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.

io/fs

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

log/slog

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.

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:

• I/O methods (File.Read, File.Write, File.ReadAt, and File.WriteAt) do not block an OS thread.
• Deadline methods (File.SetDeadline, File.SetReadDeadline, and File.SetWriteDeadline) are supported.

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:

• os.Root.Chmod
• os.Root.Chown
• os.Root.Chtimes
• os.Root.Lchown
• os.Root.Link
• os.Root.Readlink
• os.Root.Rename
• os.Root.Symlink

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/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.

sync

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

testing

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.

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.

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.