From a30998e1e7852b1ffe55f9af4bd3839f04af6840 Mon Sep 17 00:00:00 2001 From: manunicholasjacob Date: Tue, 13 Oct 2026 22:47:59 -0500 Subject: [PATCH 1/2] engine: note that --cpus does not change the reported CPU count The CPU section explains --cpus as a share of host CPU time but does not say that the operating system inside the container still reports every host CPU. Programs that size a thread pool from that count oversubscribe the quota and get throttled. Add a short paragraph with a getconf example for --cpus, a note that some nproc builds read the quota and others do not, and an nproc example for --cpuset-cpus. Verified on Docker Engine 29.1.3 (cgroup v2, 20-CPU host) with ubuntu:24.04 and ubuntu:26.04. Co-Authored-By: Claude Opus 5.5 --- .../engine/containers/resource_constraints.md | 26 +++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/content/manuals/engine/containers/resource_constraints.md b/content/manuals/engine/containers/resource_constraints.md index b8cc7b9dae5e..6a0891fb421e 100644 --- a/content/manuals/engine/containers/resource_constraints.md +++ b/content/manuals/engine/containers/resource_constraints.md @@ -174,6 +174,32 @@ Which is the equivalent to manually specifying `--cpu-period` and `--cpu-quota`; $ docker run -it --cpu-period=100000 --cpu-quota=50000 ubuntu /bin/bash ``` +The `--cpus`, `--cpu-period`, and `--cpu-quota` flags limit how much CPU time +the container gets. They don't change the number of CPUs that the operating +system reports inside the container. On a host with 20 CPUs, a container +started with `--cpus=2` still reports 20 online CPUs: + +```console +$ docker run --rm --cpus=2 ubuntu getconf _NPROCESSORS_ONLN +20 +``` + +Programs that size a thread pool from this count, for example with Python's +`os.cpu_count()`, start more busy threads than the quota can run at the same +time, and the kernel throttles the container for most of each period. Some +tools also read the quota: the `nproc` command in the `ubuntu:26.04` image +reports 2 in the same container, while the one in `ubuntu:24.04` reports 20. + +To keep the thread count in line with the limit, set the program's thread +count explicitly, for example with `OMP_NUM_THREADS` or a command-line option. +For programs that read their CPU affinity, such as `nproc`, you can instead +restrict the container to specific CPUs with `--cpuset-cpus`: + +```console +$ docker run --rm --cpuset-cpus=0,1 ubuntu nproc +2 +``` + ### Configure the real-time scheduler You can configure your container to use the real-time scheduler, for tasks which From 04aa4bc892e320633d07ab1df415bd08affb0b15 Mon Sep 17 00:00:00 2001 From: manunicholasjacob Date: Thu, 15 Oct 2026 17:04:33 -0500 Subject: [PATCH 2/2] engine: name GNU coreutils 9.8 as the nproc version that reads the quota GNU coreutils 9.8 made nproc follow a cgroup v2 CPU quota (coreutils commit c4df55be). Say so, so the image-dependent nproc result is explained rather than only shown for two images. Co-Authored-By: Claude Opus 5.5 --- content/manuals/engine/containers/resource_constraints.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/content/manuals/engine/containers/resource_constraints.md b/content/manuals/engine/containers/resource_constraints.md index 6a0891fb421e..4511a36d1ea4 100644 --- a/content/manuals/engine/containers/resource_constraints.md +++ b/content/manuals/engine/containers/resource_constraints.md @@ -187,8 +187,10 @@ $ docker run --rm --cpus=2 ubuntu getconf _NPROCESSORS_ONLN Programs that size a thread pool from this count, for example with Python's `os.cpu_count()`, start more busy threads than the quota can run at the same time, and the kernel throttles the container for most of each period. Some -tools also read the quota: the `nproc` command in the `ubuntu:26.04` image -reports 2 in the same container, while the one in `ubuntu:24.04` reports 20. +tools also read the quota, so their output depends on the image. GNU coreutils +9.8 and later make `nproc` follow a cgroup v2 CPU quota, and the `nproc` in +the `ubuntu:26.04` image reports 2 in the same container. The `nproc` in +`ubuntu:24.04` (GNU coreutils 9.4) reports 20. To keep the thread count in line with the limit, set the program's thread count explicitly, for example with `OMP_NUM_THREADS` or a command-line option.