What is GOMAXPROCS, how does it affect parallelism, and what is the container pitfall?

GOMAXPROCS controls the number of OS threads (Ps) that can execute Go code simultaneously. It defaults to runtime.NumCPU() — the number of logical CPU cores on the host. Misunderstanding its default is one of the most common production performance issues for containerised Go services.

import "runtime"

// Query current GOMAXPROCS (0 = query without changing)
fmt.Println(runtime.GOMAXPROCS(0))

// Set programmatically (returns previous value)
prev := runtime.GOMAXPROCS(4)

// Or via environment variable before process starts:
// GOMAXPROCS=4 ./myapp

// CPU-bound: increasing GOMAXPROCS → more true parallelism
// I/O-bound: GOMAXPROCS matters less — blocked goroutines park and
//            release their P for other goroutines to use

// ── THE CONTAINER PITFALL ──
// Default: GOMAXPROCS = host CPU count (e.g. 64 on a 64-core machine)
// Container CPU quota: 0.5 CPU
// Result: 64 OS threads compete for 0.5 CPU time slice
// → excessive context switching, scheduler overhead, latency spikes

// FIX: uber-go/automaxprocs — reads cgroup CPU quota automatically
// import _ "go.uber.org/automaxprocs"
// Sets GOMAXPROCS = ceil(containerCPUQuota) at startup

// Or set manually in your container entrypoint:
// GOMAXPROCS=$(nproc --ignore=0) ./myapp

// Scheduler tracing:
// GODEBUG=schedtrace=1000 ./myapp  → prints stats every 1s

GOMAXPROCS=1: goroutines interleave but never truly run in parallel. Useful for reproducing certain race conditions that only appear with true parallelism, or for testing that code is correct regardless of scheduling order. Never use GOMAXPROCS=1 as a race condition fix — use -race.

Invest now in Acorns!!! 🚀
Join Acorns and get your $5 bonus!

Acorns is a micro-investing app that automatically invests your "spare change" from daily purchases into diversified, expert-built portfolios of ETFs. It is designed for beginners, allowing you to start investing with as little as $5. The service automates saving and investing. Disclosure: I may receive a referral bonus.

Invest now!!! Get Free equity stock (US, UK only)!

Use Robinhood app to invest in stocks. It is safe and secure. Use the Referral link to claim your free stock when you sign up!.

The Robinhood app makes it easy to trade stocks, crypto and more.

Webull! Receive free stock by signing up using the link: Webull signup.