How to Limit Docker Container CPU Usage with --cpus, --cpu-quota, and --cpuset

Limit Number of CPUs

On Docker 1.13+ you can easily restrict the number of host CPUs a container may use by specifying the --cpus flag, which accepts fractional values such as 1.5. The demo runs on a low‑load host with four CPUs.

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

Inside the container we start four busy processes with the stress command: # stress -c 4 Running docker stats shows a container CPU load of 200%, meaning the container is using the equivalent of two full CPUs.

The host top command reveals that two CPUs are at 100% while the other two are idle, confirming the container’s total consumption of two CPUs.

Docker’s documentation describes --cpus as "Specify how much of the available CPU resources a container can use," emphasizing that the value is a proportion rather than a count.

For Docker versions prior to 1.13, the same effect can be achieved with --cpu-period and --cpu-quota:

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

These values are expressed in microseconds; a period of 100 000 µs (100 ms) and a quota of 200 000 µs allow the container to use two CPUs during each period.

Specify Fixed CPUs

While --cpus cannot pin a container to specific cores, the --cpuset-cpus option can. Pinning reduces cache misses on multi‑core systems.

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

After launching the stress test, only CPU 1 reaches 100% load:

Multiple CPUs can be specified, e.g., --cpuset-cpus="1,3", which results in both CPU 1 and CPU 3 hitting 100% load and the container showing a 200% CPU usage.

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

Set CPU Weight

When CPU resources are contested, --cpu-shares determines each container’s relative weight. The default is 1024; a lower value (e.g., 512) gives the container less CPU time.

$ 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

Running stress -c 4 in both containers shows the host CPU 0 at 100% load, while the containers split the load in a 1:2 ratio according to their shares.

Summary

Limiting CPU resources in Docker is more straightforward than limiting memory, but the simplification hides details such as the evolution from --cpu-period / --cpu-quota to --cpus. Understanding these options helps reduce the learning curve and enables precise control over container CPU usage.