The latest Go release, version 1.21, arrives six months after Go 1.20. Most of its changes are in the implementation of the toolchain, runtime, and libraries. As always, the release maintains the Go 1 promise of compatibility; in fact, Go 1.21 improves upon that promise. We expect almost all Go programs to continue to compile and run as before.
Go 1.21 introduces a small change to the numbering of releases. In the past, we used Go 1.N to refer to both the overall Go language version and release family as well as the first release in that family. Starting in Go 1.21, the first release is now Go 1.N.0. Today we are releasing both the Go 1.21 language and its initial implementation, the Go 1.21.0 release. These notes refer to “Go 1.21”; tools like
version will report “
go1.21.0” (until you upgrade to Go 1.21.1). See “Go versions” in the “Go Toolchains” documentation for details about the new version numbering.
Go 1.21 adds three new built-ins to the language.
max compute the smallest (or largest, for
max) value of a fixed number of given arguments. See the language spec for details.
clear deletes all elements from a map or zeroes all elements of a slice. See the language spec for details.
Package initialization order is now specified more precisely. The new algorithm is:
This may change the behavior of some programs that rely on a specific initialization ordering that was not expressed by explicit imports. The behavior of such programs was not well defined by the spec in past releases. The new rule provides an unambiguous definition.
Multiple improvements that increase the power and precision of type inference have been made.
More generally, the description of type inference in the language spec has been clarified. Together, all these changes make type inference more powerful and inference failures less surprising.
Go 1.21 includes a preview of a language change we are considering for a future version of Go: making for loop variables per-iteration instead of per-loop, to avoid accidental sharing bugs. For details about how to try that language change, see the LoopvarExperiment wiki page.
Go 1.21 now defines that if a goroutine is panicking and recover was called directly by a deferred function, the return value of recover is guaranteed not to be nil. To ensure this, calling panic with a nil interface value (or an untyped nil) causes a run-time panic of type
To support programs written for older versions of Go, nil panics can be re-enabled by setting
GODEBUG=panicnil=1. This setting is enabled automatically when compiling a program whose main package is in a module that declares
1.20 or earlier.
Go 1.21 adds improved support for backwards compatibility and forwards compatibility in the Go toolchain.
To improve backwards compatibility, Go 1.21 formalizes Go‘s use of the GODEBUG environment variable to control the default behavior for changes that are non-breaking according to the compatibility policy but nonetheless may cause existing programs to break. (For example, programs that depend on buggy behavior may break when a bug is fixed, but bug fixes are not considered breaking changes.) When Go must make this kind of behavior change, it now chooses between the old and new behavior based on the
go line in the workspace’s
go.work file or else the main module's
go.mod file. Upgrading to a new Go toolchain but leaving the
go line set to its original (older) Go version preserves the behavior of the older toolchain. With this compatibility support, the latest Go toolchain should always be the best, most secure, implementation of an older version of Go. See “Go, Backwards Compatibility, and GODEBUG” for details.
To improve forwards compatibility, Go 1.21 now reads the
go line in a
go.mod file as a strict minimum requirement:
1.21.0 means that the workspace or module cannot be used with Go 1.20 or with Go 1.21rc1. This allows projects that depend on fixes made in later versions of Go to ensure that they are not used with earlier versions. It also gives better error reporting for projects that make use of new Go features: when the problem is that a newer Go version is needed, that problem is reported clearly, instead of attempting to build the code and printing errors about unresolved imports or syntax errors.
To make these new stricter version requirements easier to manage, the
go command can now invoke not just the toolchain bundled in its own release but also other Go toolchain versions found in the PATH or downloaded on demand. If a
go line declares a minimum requirement on a newer version of Go, the
go command will find and run that version automatically. The new
toolchain directive sets a suggested minimum toolchain to use, which may be newer than the strict
go minimum. See “Go Toolchains” for details.
-pgo build flag now defaults to
-pgo=auto, and the restriction of specifying a single main package on the command line is now removed. If a file named
default.pgo is present in the main package's directory, the
go command will use it to enable profile-guided optimization for building the corresponding program.
dir flag must now be the first flag on the command-line when used.
-fullpath prints full path names in test log messages, rather than just base names.
-c flag now supports writing test binaries for multiple packages, each to
pkg is the package name. It is an error if more than one test package being compiled has a given package name.
-o flag now accepts a directory argument, in which case test binaries are written to that directory instead of the current directory.
In files that
import "C", the Go toolchain now correctly reports errors for attempts to declare Go methods on C types.
When printing very deep stacks, the runtime now prints the first 50 (innermost) frames followed by the bottom 50 (outermost) frames, rather than just printing the first 100 frames. This makes it easier to see how deeply recursive stacks started, and is especially valuable for debugging stack overflows.
On Linux platforms that support transparent huge pages, the Go runtime now manages which parts of the heap may be backed by huge pages more explicitly. This leads to better utilization of memory: small heaps should see less memory used (up to 50% in pathological cases) while large heaps should see fewer broken huge pages for dense parts of the heap, improving CPU usage and latency by up to 1%.
As a result of runtime-internal garbage collection tuning, applications may see up to a 40% reduction in application tail latency and a small decrease in memory use. Some applications may also observe a small loss in throughput. The memory use decrease should be proportional to the loss in throughput, such that the previous release's throughput/memory tradeoff may be recovered (with little change to latency) by increasing
Calls from C to Go on threads created in C require some setup to prepare for Go execution. On Unix platforms, this setup is now preserved across multiple calls from the same thread. This significantly reduces the overhead of subsequent C to Go calls from ~1-3 microseconds per call to ~100-200 nanoseconds per call.
Profile-guide optimization (PGO), added as a preview in Go 1.20, is now ready for general use. PGO enables additional optimizations on code identified as hot by profiles of production workloads. As mentioned in the Go command section, PGO is enabled by default for binaries that contain a
default.pgo profile in the main package directory. Performance improvements vary depending on application behavior, with most programs from a representative set of Go programs seeing between 2 and 7% improvement from enabling PGO. See the PGO user guide for detailed documentation.
PGO builds can now devirtualize some interface method calls, adding a concrete call to the most common callee. This enables further optimization, such as inlining the callee.
Go 1.21 improves build speed by up to 6%, largely thanks to building the compiler itself with PGO.
On amd64, frameless nosplit assembly functions are no longer automatically marked as
NOFRAME. Instead, the
NOFRAME attribute must be explicitly specified if desired, which is already the behavior on other architectures supporting frame pointers. With this, the runtime now maintains the frame pointers for stack transitions.
The verifier that checks for incorrect uses of
R15 when dynamic linking on amd64 has been improved.
On windows/amd64, the linker (with help from the compiler) now emits SEH unwinding data by default, which improves the integration of Go applications with Windows debuggers and other tools.
In Go 1.21 the linker (with help from the compiler) is now capable of deleting dead (unreferenced) global map variables, if the number of entries in the variable initializer is sufficiently large, and if the initializer expressions are side-effect free.
The new log/slog package provides structured logging with levels. Structured logging emits key-value pairs to enable fast, accurate processing of large amounts of log data. The package supports integration with popular log analysis tools and services.
The new slices package provides many common operations on slices, using generic functions that work with slices of any element type.
The new maps package provides several common operations on maps, using generic functions that work with maps of any key or element type.
As always, there are various minor changes and updates to the library, made with the Go 1 promise of compatibility in mind. There are also various performance improvements, not enumerated here.
The implementation of the
io/fs.DirEntry interface returned by the
io/fs.ReadDirFile.ReadDir method of the
io/fs.File returned by
Reader.Open now implements a
String method that calls
WithoutCancel function returns a copy of a context that is not canceled when the original context is canceled.
AfterFunc function registers a function to run after a context has been cancelled.
An optimization means that the results of calling
TODO and converting them to a shared type can be considered equal. In previous releases they were always different. Comparing
Context values for equality has never been well-defined, so this is not considered to be an incompatible change.
All of the
Curve methods have been deprecated, along with
Unmarshal. For ECDH operations, the new
crypto/ecdh package should be used instead. For lower-level operations, use third-party modules such as filippo.io/nistec.
crypto/rand package now uses the
getrandom system call on NetBSD 10.0 and later.
The performance of private RSA operations (decryption and signing) is now better than Go 1.19 for
GOARCH=arm64. It had regressed in Go 1.20.
Due to the addition of private fields to
PrivateKey.Precompute must be called for optimal performance even if deserializing (for example from JSON) a previously-precomputed private key.
GenerateMultiPrimeKey function and the
PrecomputedValues.CRTValues field have been deprecated.
PrecomputedValues.CRTValues will still be populated when
PrivateKey.Precompute is called, but the values will not be used during decryption operations.
SHA-224 and SHA-256 operations now use native instructions when available when
GOARCH=amd64, providing a performance improvement on the order of 3-4x.
Servers now skip verifying client certificates (including not running
Config.VerifyPeerCertificate) for resumed connections, besides checking the expiration time. This makes session tickets larger when client certificates are in use. Clients were already skipping verification on resumption, but now check the expiration time even if
Config.InsecureSkipVerify is set.
Applications can now control the content of session tickets.
SessionState type describes a resumable session.
SessionState.Bytes method and
ParseSessionState function serialize and deserialize a
Config.UnwrapSession hooks convert a
SessionState to and from a ticket on the server side.
Config.DecryptTicket methods provide a default implementation of
ClientSessionState.ResumptionState method and
NewResumptionState function may be used by a
ClientSessionCache implementation to store and resume sessions on the client side.
To reduce the potential for session tickets to be used as a tracking mechanism across connections, the server now issues new tickets on every resumption (if they are supported and not disabled) and tickets don't bear an identifier for the key that encrypted them anymore. If passing a large number of keys to
Conn.SetSessionTicketKeys, this might lead to a noticeable performance cost.
Both clients and servers now implement the Extended Master Secret extension (RFC 7627). The deprecation of
ConnectionState.TLSUnique has been reverted, and is now set for resumed connections that support Extended Master Secret.
QUICConn type provides support for QUIC implementations, including 0-RTT support. Note that this is not itself a QUIC implementation, and 0-RTT is still not supported in TLS.
VersionName function returns the name for a TLS version number.
The TLS alert codes sent from the server for client authentication failures have been improved. Previously, these failures always resulted in a “bad certificate” alert. Now, certain failures will result in more appropriate alert codes, as defined by RFC 5246 and RFC 8446:
RevocationList.RevokedCertificates has been deprecated and replaced with the new
RevokedCertificateEntries field, which is a slice of
RevocationListEntry contains all of the fields in
pkix.RevokedCertificate, as well as the revocation reason code.
Name constraints are now correctly enforced on non-leaf certificates, and not on the certificates where they are expressed.
File.DynValue method may be used to retrieve the numeric values listed with a given dynamic tag.
The constant flags permitted in a
DT_FLAGS_1 dynamic tag are now defined with type
DynFlag1. These tags have names starting with
The package now defines the constant
The package now defines the constant
NativeEndian variable may be used to convert between byte slices and integers using the current machine's native endianness.
ErrUnsupported error provides a standardized way to indicate that a requested operation may not be performed because it is unsupported. For example, a call to
os.Link when using a file system that does not support hard links.
A flag definition (via
IntVar, etc.) will panic if
Set has already been called on a flag with the same name. This change is intended to detect cases where changes in initialization order cause flag operations to occur in a different order than expected. In many cases the fix to this problem is to introduce a explicit package dependence to correctly order the definition before any
File.GoVersion field records the minimum Go version required by any
// +build directives.
The package now parses build directives (comments that start with
//go:) in file headers (before the
package declaration). These directives are available in the new
GoVersion function returns the minimum Go version implied by a build expression.
File.Lines method returns the file's line-number table in the same form as accepted by
Package.GoVersion method returns the Go language version used to check the package.
hash/maphash package now has a pure Go implementation, selectable with the
purego build tag.
The new error
FormatFileInfo function returns a formatted version of a
FileInfo. The new
FormatDirEntry function returns a formatted version of a
DirEntry. The implementation of
DirEntry returned by
ReadDir now implements a
String method that calls
FormatDirEntry, and the same is true for the
DirEntry value passed to
Int.Float64 method returns the nearest floating-point value to a multi-precision integer, along with an indication of any rounding that occurred.
On Linux, the net package can now use Multipath TCP when the kernel supports it. It is not used by default. To use Multipath TCP when available on a client, call the
Dialer.SetMultipathTCP method before calling the
Dialer.DialContext methods. To use Multipath TCP when available on a server, call the
ListenConfig.SetMultipathTCP method before calling the
ListenConfig.Listen method. Specify the network as
"tcp6" as usual. If Multipath TCP is not supported by the kernel or the remote host, the connection will silently fall back to TCP. To test whether a particular connection is using Multipath TCP, use the
In a future Go release we may enable Multipath TCP by default on systems that support it.
ResponseController.EnableFullDuplex method allows server handlers to concurrently read from an HTTP/1 request body while writing the response. Normally, the HTTP/1 server automatically consumes any remaining request body before starting to write the response, to avoid deadlocking clients which attempt to write a complete request before reading the response. The
EnableFullDuplex method disables this behavior.
Programs may now pass an empty
time.Time value to the
Chtimes function to leave either the access time or the modification time unchanged.
On Windows the
File.Chdir method now changes the current directory to the file, rather than always returning an error.
On Windows calling
Truncate on a non-existent file used to create an empty file. It now returns an error indicating that the file does not exist.
On Windows calling
TempDir now uses GetTempPath2W when available, instead of GetTempPathW. The new behavior is a security hardening measure that prevents temporary files created by processes running as SYSTEM to be accessed by non-SYSTEM processes.
On Windows the os package now supports working with files whose names, stored as UTF-16, can't be represented as valid UTF-8.
Lstat now resolves symbolic links for paths ending with a path separator, consistent with its behavior on POSIX platforms.
In Go 1.21,
ValueOf no longer forces its argument to be allocated on the heap, allowing a
Value's content to be allocated on the stack. Most operations on a
Value also allow the underlying value to be stack allocated.
Textual stack traces produced by Go programs, such as those produced when crashing, calling
runtime.Stack, or collecting a goroutine profile with
debug=2, now include the IDs of the goroutines that created each goroutine in the stack trace.
Crashing Go applications can now opt-in to Windows Error Reporting (WER) by setting the environment variable
GOTRACEBACK=wer or calling
debug.SetTraceback("wer") before the crash. Other than enabling WER, the runtime will behave as with
GOTRACEBACK=crash. On non-Windows systems,
GOTRACEBACK=wer is ignored.
GODEBUG=cgocheck=2, a thorough checker of cgo pointer passing rules, is no longer available as a debug option. Instead, it is available as an experiment using
GOEXPERIMENT=cgocheck2. In particular this means that this mode has to be selected at build time instead of startup time.
GODEBUG=cgocheck=1 is still available (and is still the default).
A new type
Pinner has been added to the runtime package.
Pinners may be used to “pin” Go memory such that it may be used more freely by non-Go code. For instance, passing Go values that reference pinned Go memory to C code is now allowed. Previously, passing any such nested reference was disallowed by the cgo pointer passing rules. See the docs for more details.
A few previously-internal GC metrics, such as live heap size, are now available.
GOMEMLIMIT are also now available as metrics.
Collecting traces on amd64 and arm64 now incurs a substantially smaller CPU cost: up to a 10x improvement over the previous release.
Traces now contain explicit stop-the-world events for every reason the Go runtime might stop-the-world, not just garbage collection.
On Windows the
Fchdir function now changes the current directory to its argument, rather than always returning an error.
SysProcAttr has a new field
Jail that may be used to put the newly created process in a jailed environment.
On Windows the syscall package now supports working with files whose names, stored as UTF-16, can't be represented as valid UTF-8. The
UTF16FromString functions now convert between UTF-16 data and WTF-8 strings. This is backward compatible as WTF-8 is a superset of the UTF-8 format that was used in earlier releases.
Several error values match the new
errors.ErrUnsupported, such that
errors.Is(err, errors.ErrUnsupported) returns true.
EPLAN9 (Plan 9 only)
ERROR_CALL_NOT_IMPLEMENTED (Windows only)
ERROR_NOT_SUPPORTED (Windows only)
EWINDOWS (Windows only)
-test.fullpath option will print full path names in test log messages, rather than just base names.
Testing function reports whether the program is a test created by
As announced in the Go 1.20 release notes, Go 1.21 requires macOS 10.15 Catalina or later; support for previous versions has been discontinued.
As announced in the Go 1.20 release notes, Go 1.21 requires at least Windows 10 or Windows Server 2016; support for previous versions has been discontinued.
go:wasmimport directive can now be used in Go programs to import functions from the WebAssembly host.
Go 1.21 adds an experimental port to the WebAssembly System Interface (WASI), Preview 1 (
As a result of the addition of the new
GOOS value “
wasip1”, Go files named
*_wasip1.go will now be ignored by Go tools except when that
GOOS value is being used. If you have existing filenames matching that pattern, you will need to rename them.
GOPPC64=power10 now generates PC-relative instructions, prefixed instructions, and other new Power10 instructions. On AIX,
GOPPC64=power10 generates Power10 instructions, but does not generate PC-relative instructions.
When building position-independent binaries for
GOARCH=ppc64le, users can expect reduced binary sizes in most cases, in some cases 3.5%. Position-independent binaries are built for ppc64le with the following
linux/loong64 port now supports