Master Docker CPU Limits: --cpus, --cpuset-cpus, and --cpu-shares Explained

By default Docker containers can consume unlimited host CPU resources, which may exhaust the host if a container misbehaves. The article explains how to limit CPU usage safely.

Limiting the number of CPUs with --cpus

Docker 1.13+ allows specifying the amount of CPU a container may use via the --cpus option, accepting integer or fractional values. On a four‑CPU host, the demo runs a container with --cpus=2, meaning the container can use up to two CPUs.

$ docker run -it --rm --cpus=2 u-stress:latest /bin/bash

Inside the container, the stress -c 4 command creates four busy processes. docker stats shows a CPU usage of 200%, which represents two full CPUs. The host’s top command confirms that two CPUs are at 100% while the other two remain idle.

Legacy method: --cpu-period and --cpu-quota

Before --cpus, the same effect required both --cpu-period (default 100 000 µs) and --cpu-quota. Setting --cpu-period=100000 and --cpu-quota=200000 yields the same 2‑CPU limit.

$ docker run -it --rm --cpu-period=100000 --cpu-quota=200000 u-stress:latest /bin/bash

The values are expressed in microseconds: 100 000 µs = 100 ms, 200 000 µs = 200 ms, meaning the container may use CPU for 200 ms in each 100 ms window, effectively two CPUs.

Pinning a container to specific CPUs with --cpuset-cpus

To keep a container on fixed cores, use --cpuset-cpus. The example pins the container to CPU 1:

$ docker run -it --rm --cpuset-cpus="1" u-stress:latest /bin/bash

Running stress -c 4 now shows only CPU 1 at 100% load, while the other CPUs stay idle.

The option also accepts multiple CPUs, e.g., --cpuset-cpus="1,3", which results in both CPU 1 and CPU 3 reaching 100% load and the container showing 200% CPU usage.

$ docker run -it --rm --cpuset-cpus="1,3" u-stress:latest /bin/bash

Adjusting CPU weight with --cpu-shares

When multiple containers compete for CPU, --cpu-shares sets relative weight (default 1024). In the demo two containers share CPU 0, one with --cpu-shares=512 and the other with --cpu-shares=1024. The host shows 100% load on CPU 0, and the containers receive CPU proportionally (1:2 ratio).

$ docker run -it --rm --cpuset-cpus="0" --cpu-shares=512 u-stress:latest /bin/bash
$ docker run -it --rm --cpuset-cpus="0" --cpu-shares=1024 u-stress:latest /bin/bash

Setting equal shares makes the containers split the CPU evenly.

Conclusion

Limiting CPU resources in Docker is more straightforward than memory limits, especially with the --cpus flag introduced in Docker 1.13. Understanding the underlying --cpu-period and --cpu-quota mechanics helps grasp why percentages are used, while --cpuset-cpus and --cpu-shares provide finer control over core affinity and weight.

Reference: https://www.cnblogs.com/sparkdev/p/8052522.html