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:

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

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

:

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

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:

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

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:

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

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:

<code>$ 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</code>

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.