engine: note that --cpus does not change the reported CPU count

[manunicholasjacob]

Description

The CPU section of the resource constraints page explains --cpus as a share of host CPU time, but it doesn't say that the operating system inside the container still reports every host CPU. Programs that size a thread pool from that count start more busy threads than the quota can run, and the container gets throttled for most of each period.

This adds a short paragraph after the --cpu-period/--cpu-quota example: a getconf example for --cpus, a note that nproc behaves differently depending on the image, and an nproc example for --cpuset-cpus.

Checked on Docker Engine 29.1.3 (WSL2 kernel 6.18, cgroup v2, 20 logical CPUs), three runs each, all identical:

--cpus=2         ubuntu:24.04  getconf _NPROCESSORS_ONLN -> 20   nproc -> 20 (GNU coreutils 9.4)
--cpus=2         ubuntu:26.04  getconf _NPROCESSORS_ONLN -> 20   nproc -> 2  (uutils coreutils 0.10.0)
--cpus=2         python:3.12-slim  os.cpu_count() -> 20
--cpus=2         cat /sys/fs/cgroup/cpu.max -> 200000 100000
--cpuset-cpus=0,1  ubuntu:24.04 and ubuntu:26.04  nproc -> 2   getconf _NPROCESSORS_ONLN -> 20

Because nproc depends on the image (ubuntu resolves to 26.04, whose nproc reads the quota), the --cpus example uses getconf _NPROCESSORS_ONLN, which reported 20 in every image I tried. The --cpuset-cpus example keeps nproc, since it reads the CPU affinity; the text limits that advice to programs that read their affinity, because getconf and Python's os.cpu_count() still report 20 under --cpuset-cpus=0,1.

As a measured example of the effect: in llama.cpp's llama-bench under --cpus=2, the default thread count (10) was throttled in 98.6% of CFS periods and decoded at 17.06 tok/s, against 52.83 tok/s with -t 2 (ggml-org/llama.cpp#30070).

Lint on the changed file with the versions the repo pins: Vale 3.17.0 reports 0 errors, 0 warnings and 0 suggestions, and rumdl 0.2.49 reports no issues.

Related issues or tickets

None found. Older issues about the cpus flags (#5106, #6979, #5622) are closed and don't cover the reported CPU count.

Reviews

• Technical review
• Editorial review

This change and description were drafted with help from an AI assistant (Claude). The outputs above come from runs on my own machine.

[netlify]

✅ Deploy Preview for docsdocker ready!

Name	Link
🔨 Latest commit	a30998e
🔍 Latest deploy log	https://app.netlify.com/projects/docsdocker/deploys/6acf103299390ef93f4d9c27
😎 Deploy Preview	https://deploy-preview-26348--docsdocker.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[collinfunk]

Hi, I just wanted to note that we changed the behavior in GNU coreutils 9.8 to follow cgroup v2 CPU quotas. See the following commit: coreutils/coreutils@c4df55b

Of course, many images will use older versions, so I don't think it necessarily invalidates your patch. However, I figured you may find that information useful.