GOMAXPROCS Under CPU Quotas

## What the setting actually is The Go runtime multiplexes goroutines onto OS threads through an intermediate resource the runtime calls a **P** — a scheduling context that owns a run queue and the per-CPU caches a thread needs in order to run Go code. A thread must hold a P to execute Go code, and `GOMAXPROCS` is simply how many Ps exist. So the honest one-line definition is: **GOMAXPROCS is the maximum number of goroutines that can be executing Go code simultaneously.** Three things it is *not*: - **Not a limit on goroutines.** You can create a million goroutines with `GOMAXPROCS=1`; they just take turns. - **Not a limit on OS threads.** A goroutine that blocks in a system call or in cgo hands its P to another thread, so the process can hold many more threads than Ps. - **Not a limit the kernel enforces.** The container's CPU quota is enforced by the kernel; GOMAXPROCS is only the runtime's own idea of how much parallelism to attempt. ## Where the default comes from For most of Go's history the default was `runtime.NumCPU()`. That function reports the number of logical CPUs **usable by the process**, which means it respects a CPU affinity mask (a `taskset`-style pinning) — but it has never respected a cgroup CPU *bandwidth* limit, because a bandwidth quota does not remove CPUs from view. A process in a container that is allowed 0.5 CPU on a 64-core node still sees 64 CPUs. That mismatch is the classic container problem. The runtime starts 64 Ps, happily runs 64 goroutines in parallel, burns the cgroup's slice of the quota period in a fraction of the period, and then the whole cgroup is frozen by the kernel until the next period begins. The program is not slow because a function is slow; it is slow because it asked for far more parallelism than it was allowed to consume. **Go 1.25 changed the default on Linux.** The runtime now derives GOMAXPROCS from the smaller of the logical CPUs it can use and the cgroup CPU bandwidth limit, rounding a fractional limit up to a whole number, and it does not reduce the value below 2 on account of the limit. On a node with 64 CPUs and a 0.5-CPU quota, a Go 1.25 program therefore starts small instead of starting at 64. ## Seeing it from inside the container The two numbers you want are `runtime.NumCPU()` (what the process can see) and `runtime.GOMAXPROCS(0)` (what the runtime chose — passing 0 queries without setting). Logging both at start-up, next to the CPU limit the deployment asked for, turns an argument into a fact. If the CPU count is large, GOMAXPROCS equals it, and the CPU limit is a fraction of a core, you have found a real problem. ## Overriding it The value is still yours to set: - the `GOMAXPROCS` environment variable, read once at start-up; - `runtime.GOMAXPROCS(n)` with `n >= 1`, which sets the value and returns the previous one. Either of those pins the number. Prefer leaving it alone on a modern toolchain: the runtime's own default tracks the limit the platform actually gave you, and a hard-coded number goes stale the moment somebody edits the deployment. ## The everyday intuition For CPU-bound work, throughput rises with GOMAXPROCS only up to the CPU time you are actually allowed to consume. Beyond that you are not adding capacity — you are adding contention, extra parallel garbage-collector workers (the collector targets roughly a quarter of GOMAXPROCS in dedicated mark workers), and more per-P memory, all paid for out of the same quota. Matching the runtime to the limit is nearly always faster than exceeding it.