6.3.4.2 Container CPU Limits

Container CPU limits constrain how much CPU time a container's processes are allowed to consume, throttling (rather than killing) the container if it attempts to exceed its configured share, preventing one container from monopolizing CPU resources shared with other containers on the same host.

Setting a CPU Limit

The --cpus flag specifies the maximum number of CPU cores (or fractional equivalent) a container can use.

docker run -d --cpus=1.5 myapp:1.0

This container can use up to the equivalent of one and a half CPU cores, regardless of how much it might otherwise attempt to consume.

How CPU Limits Differ From Memory Limits in Enforcement

Unlike a memory limit violation, which results in the offending process being killed, exceeding a CPU limit simply throttles the container's CPU usage — it continues running, just more slowly, rather than being terminated.

docker run -d --cpus=0.5 myapp:1.0

A CPU-intensive workload in this container is throttled to use no more than half a CPU core's worth of processing time, slowing it down without crashing it.

Setting Relative CPU Priority With CPU Shares

Rather than (or in addition to) an absolute CPU limit, relative CPU shares determine how CPU time is prioritized among competing containers when the host's CPU is under contention.

docker run -d --cpu-shares=512 myapp-low-priority:1.0
docker run -d --cpu-shares=1024 myapp-high-priority:1.0

Under contention, the second container receives roughly twice the CPU time of the first, reflecting their relative share values.

Observing CPU Usage Against Configured Limits

A container's actual CPU consumption relative to its configured limit can be monitored directly.

docker stats myapp

Why Container CPU Limits Matter

Appropriately configured CPU limits prevent a single CPU-intensive container from degrading the performance of other containers sharing the same host, supporting more predictable, fair resource allocation across multiple co-located workloads.