A Go container can be limited to one CPU while the runtime sees all 32 logical CPUs on its node. Before Go 1.25, the runtime could schedule work as if all 32 were available. When a burst of CPU-bound work used the container’s quota, Linux could pause the whole container until its quota renewed. Requests that were ready to run then waited, which can show up as latency spikes under load.

A one-CPU pod on a 32-CPU node

Assume the Linux node exposes 32 logical CPUs, the container has no narrower CPU-affinity setting, and Kubernetes gives the pod a one-CPU limit:

resources:
  limits:
    cpu: "1"

With Go 1.24 or earlier, the default could be GOMAXPROCS=32. If 32 CPU-bound goroutines are ready, Go can run up to 32 of them in parallel. A program can still have thousands of goroutines; GOMAXPROCS limits how many can execute Go code at once.

A one-CPU cgroup limit commonly allows 100 milliseconds of CPU time in each 100-millisecond period. Thirty-two busy threads can use that budget well before the period ends. Linux then throttles the container until its quota renews. Requests that were ready to run pause too. Under load, that can appear as p95 or p99 latency spikes. It is most likely with CPU-heavy bursts, such as image processing or compression. An I/O-heavy service, whose goroutines often wait on network or disk, may show less effect. The Go team’s explanation describes how cgroup throttling affects tail latency.

For the assumptions above, a small program that prints runtime.NumCPU() and runtime.GOMAXPROCS(0) could report:

Go 1.24:  NumCPU=32  GOMAXPROCS=32
Go 1.25:  NumCPU=32  GOMAXPROCS=2

The Go 1.25 result assumes no manual override and a module go line of 1.25.0 or later. The runtime keeps a minimum GOMAXPROCS of 2 when at least two logical CPUs are available, even with a one-CPU limit.

What Go 1.25 changes

Go 1.25 makes the default GOMAXPROCS account for Linux cgroup CPU limits. That lower parallelism can reduce how quickly a CPU-bound workload exhausts its quota. It does not remove the quota, guarantee that throttling stops, or guarantee lower latency for every workload.

The runtime chooses the minimum of the logical CPU count, CPU affinity, and, on Linux, the cgroup CPU throughput limit. A fractional quota rounds up. The result is never below 2 unless the logical CPU count or CPU affinity is itself below 2. For example, with at least two CPUs available, limits of 0.5, 1, and 1.5 CPU all produce a GOMAXPROCS value of 2.

The quota is a throughput limit, not a pin to particular cores. A value of GOMAXPROCS=2 means at most two goroutines execute Go code at once. It does not reserve two cores for the container. CPU requests are not used to choose the value.

The runtime can update GOMAXPROCS when CPU affinity or the cgroup quota changes. Updates happen at most once per second, or less often while the application is idle. On non-Linux systems, the cgroup part does not apply.

See the Go 1.25 release notes, the Go team’s explanation, and the runtime.GOMAXPROCS documentation for the full rules.

package main

import (
	"fmt"
	"runtime"
)

func main() {
	fmt.Printf("Go: %s\n", runtime.Version())
	fmt.Printf("Logical CPUs: %d\n", runtime.NumCPU())
	fmt.Printf("GOMAXPROCS: %d\n", runtime.GOMAXPROCS(0))
}

Build with Go 1.25 or later and set the module’s go line to 1.25.0 or later to use the new defaults. Then run the program inside a Linux container with a CPU limit:

docker run --rm --cpus=1.5 \
  -v "$PWD:/src" -w /src \
  golang:1.25 go run .

If the host has at least two logical CPUs available, the expected default is GOMAXPROCS=2. runtime.NumCPU() may still print a larger number because it reports logical CPUs, not the container’s fractional throughput quota.

For Kubernetes, the equivalent test is a pod with a CPU limit such as:

resources:
  limits:
    cpu: "1.5"

Run a small program built with the same Go version and module go line as the application you are diagnosing. Do not infer the setting from kubectl top; inspect it from inside the process.

When the automatic default is disabled

A positive GOMAXPROCS environment variable or a call to runtime.GOMAXPROCS sets the value manually and disables automatic updates. Go 1.25 also provides two GODEBUG switches:

GODEBUG=containermaxprocs=0  # Ignore the Linux cgroup CPU quota.
GODEBUG=updatemaxprocs=0     # Keep the initial value instead of updating it.

These can help isolate a regression, but they are not general performance fixes. runtime.SetDefaultGOMAXPROCS restores the runtime’s default behavior if application code needs to undo a manual setting.

If an application uses go.uber.org/automaxprocs or another helper, check how it sets the runtime value before removing it. Calling runtime.GOMAXPROCS manually can disable Go’s automatic updates, so duplicate configuration may change behavior.

What this does not tell you

A lower GOMAXPROCS may reduce CPU throttling and improve latency for some workloads. A workload with short bursts may behave differently, and a CPU-bound program may need measurement before any manual override. The Go change is a safer default, not a benchmark result for your service.

It also does not read Kubernetes CPU requests, change the container’s quota, or tune memory use. Measure the application under its real limits before changing those settings.