How to Limit CPU Usage for Docker Containers: A Practical Guide

Introduction

By default a Docker container can use unlimited host CPU resources, which can exhaust the host if a process misbehaves. This article shows how to restrict the CPU resources a container may use, using the u‑stress image for demonstration.

Limiting the number of CPUs

Docker 1.13+ allows you to limit the number of CPUs with the --cpus flag, which accepts fractional values. On a four‑CPU host the demo runs:

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

Inside the container stress -c 4 creates four busy processes. The

shows the docker stats output where the container reports a 200 % CPU load (equivalent to two full CPUs).

Running top on the host reveals that two CPUs are at 100 % while the other two are idle, confirming that the container is consuming the equivalent of two CPUs.

Older Docker versions

Before --cpus, the same effect required --cpu-period and --cpu-quota:

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

The period is 100 ms and the quota 200 ms, meaning the container may use CPU time up to 200 ms every 100 ms – effectively two CPUs.

Pinning containers to specific CPUs

The --cpuset-cpus flag binds a container to particular CPU cores. Example binding to CPU 1:

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

After starting stress -c 4, the host’s

shows only CPU 1 at 100 % and the container’s CPU load is also 100 %.

Multiple CPUs can be specified, e.g. --cpuset-cpus="1,3", which results in both CPU 1 and CPU 3 reaching 100 % while the container reports 200 % load:

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

Adjusting CPU weight

The --cpu-shares option sets relative CPU weight (default 1024). Two containers bound to CPU 0 are started with shares 512 and 1024 respectively:

$ 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 shows the host CPU 0 at 100 % (

) and the containers’ loads split roughly 1:2, reflecting the share ratio (

).

Conclusion

CPU limiting is more concise than memory limiting, but the simplicity hides details such as the transition from --cpu-period / --cpu-quota to --cpus. Nevertheless, the higher‑level flag reduces the learning curve for most users.