cgroup v2 CPU Quota: What Actually Happens When the Throttle Bites, Measured
A 50% quota makes the same work take 1.92 times as long. A 25% quota makes it 3.95 times as long. The CPU time the job consumes barely moves, and nearly every 100 millisecond period is throttled. The quota is the clock, and cpu.stat proves it.
Written November 9, 2026 · Tested with systemd 255 · 11 min read
- The table: the quota is the clock
- cpu.stat proves it
- cpu.pressure tracks the throttle, roughly
What this guide is
One fixed job, run under three quotas, three times each, on two nights. The job is a C program that runs exactly 2,000,000,000 iterations of the same loop and prints its wall time and a checksum. The checksum reads 527708174320810678 in all 18 runs across both nights. Each run happens in a fresh scope made with systemd-run --user --scope, with CPUQuota=50% or CPUQuota=25% for the capped cells and no quota for the baseline. After the job exits, a wrapper inside the scope reads cpu.max, cpu.stat, and cpu.pressure from the scope's own cgroup directory, before systemd tears the scope down. Reading from outside after the fact does not work: the cgroup is gone.
The question is the one people ask when a service runs slower than expected under a CPU limit: is the quota a speed limit, or a clock? The answer is the clock. The same work takes almost exactly twice as long at half quota and almost exactly four times as long at quarter quota, while the CPU time the work consumes barely changes. The extra wall time is time spent throttled, and the counters say so directly.
The table: the quota is the clock
Wall seconds, medians of three runs, fresh tonight.
- Baseline, no quota: fresh median 3.019, reps 3.003, 3.019, 3.025. Night before: 2.975, reps 2.973, 2.975, 3.000.
- CPUQuota=50%, cpu.max reads
50000 100000: fresh median 5.801, reps 5.771, 5.801, 5.862. Night before: 5.776, reps 5.773, 5.776, 5.803. Fresh ratio against the fresh baseline: 1.92 times. Night before: 1.94 times. Ideal is 2.00 times. - CPUQuota=25%, cpu.max reads
25000 100000: fresh median 11.918, reps 11.902, 11.918, 12.062. Night before: 11.652, reps 11.652, 11.652, 11.692. Fresh ratio against the fresh baseline: 3.95 times. Night before: 3.92 times. Ideal is 4.00 times.
Wall time scales almost linearly with the quota: 1.92 to 1.94 times at 50% against an ideal of 2.00, and 3.92 to 3.95 times at 25% against an ideal of 4.00. The shortfall is small and in the same direction both nights. The ranges inside each cell are tight, under 2% from the fastest to the slowest rep, so the medians are not hiding spread.
cpu.stat proves it
The wall time doubles and quadruples, but the CPU time the job consumes does not. That is the check that separates a quota from a slower machine: a slower machine would take more CPU time to do the same work, or the same wall time with less work. Here the work is identical, the CPU time is nearly flat, and the missing wall time shows up as throttled time.
- CPU time consumed, usage_usec medians: baseline 2,903,008 fresh and 2,870,043 the night before; 50% quota 2,943,227 fresh and 2,917,441 the night before; 25% quota 3,002,146 fresh and 2,949,924 the night before. Throttling adds 1.4% fresh and 1.7% the night before at 50%, and 3.4% fresh and 2.8% the night before at 25%. The quota costs wall time, not CPU time.
- Nearly every period is throttled. Fresh: at 50%, 58 of 59, 58 of 59, and 58 of 58 periods throttled; at 25%, 119 of 119, 119 of 120, and 121 of 121. Night before: at 50%, 58 of 58, 57 of 58, and 58 of 59; at 25%, 117 of 117, 118 of 118, and 118 of 118. A CPU-bound job under a quota hits the ceiling in essentially every 100 millisecond period.
- The period length confirms the 100 millisecond default. Wall time divided by nr_periods is 97.8 to 100.0 milliseconds across all 12 throttled runs on both nights. The systemd manual states the default quota period is 100 milliseconds, and the counters agree.
- The identity check: usage_usec plus throttled_usec is 96.2% to 96.8% of wall time fresh, and 96.3% to 97.0% the night before, in every throttled run. The remaining 3 to 4% is period-boundary and scheduling overhead. This is the check a reader can use to confirm their own numbers hang together: if usage plus throttled is far from wall time, something else is eating the time.
- Throttled time, throttled_usec medians: 2,655,802 fresh and 2,651,271 the night before at 50%; 8,459,643 fresh and 8,354,888 the night before at 25%.
- No bursting happened: nr_bursts is 0 and burst_usec is 0 in all 12 throttled runs. The burst allowance defaults to zero, and nothing in this probe banked quota from quiet periods.
cpu.pressure tracks the throttle, roughly
The pressure file is the one people watch on a dashboard, so it is worth checking against the counters. It tracks the throttled time, but roughly, not precisely. Do not use it as an accounting of throttled time.
- Pressure totals, some and full identical in every run: baseline 450 to 563 microseconds fresh, about half a millisecond, effectively zero. At 50%: 1,728,660 to 2,591,696 microseconds fresh, median 2,331,602, against throttled_usec of 2,642,323 to 2,674,444. At 25%: 7,862,391 to 8,557,657 fresh, median 8,434,413, against throttled_usec of 8,459,375 to 8,553,035.
- The gap matters in one run: the second 50% run fresh shows a pressure total of 1.73 seconds against 2.67 seconds throttled, a 35% miss. The other five throttled runs fresh land within 0.1 to 0.6 seconds of throttled time. The night before, pressure totals were 2.30 to 2.69 seconds at 50% against 2.64 to 2.69 seconds throttled, and 8.22 to 8.27 seconds at 25% against 8.27 to 8.39 seconds throttled. Pressure stall information is a usable rough proxy for throttling time here, not a precise one. If the pressure total and throttled_usec disagree by a third, the counters win.
- The ten-second averages: at 50%, some avg10 is 8.20 to 15.37 fresh and 12.25 to 15.48 the night before; at 25%, 42.69 to 46.26 fresh and 44.86 to 45.68 the night before. The averages move with the quota, but they are windowed averages, not totals, and the same caveat applies.
- Some and full are equal in every run here because the workload is a single thread: when the one thread stalls, the whole cgroup is fully stalled. That is a property of a single-threaded workload, not a general property of cgroup pressure.
The file that is not there
In the three baseline scopes fresh tonight, and in four baseline scopes the night before, /sys/fs/cgroup/.../cpu.max does not exist. The cat fails with "No such file or directory", while cpu.stat and cpu.pressure read fine from the same directory. The baseline cpu.stat contains only usage_usec, user_usec, system_usec, and nice_usec: the nr_periods, nr_throttled, throttled_usec, nr_bursts, and burst_usec fields appear only once a quota is set.
That is worth stating plainly because the kernel documentation says the opposite in its letter: it describes cpu.max as a file that exists on non-root cgroups with a default of "max 100000". On this stack, systemd 255 user scopes, the file is absent until a quota is set. The nearest published guide shows a system.slice service reading "max 100000" before a quota is set, so the two observations are about different paths: a service unit has the file with the default, a transient user scope does not. Do not tell a reader to cat cpu.max on an unlimited scope and expect "max 100000": on this stack they will get "No such file or directory". If the guide shows an unlimited baseline, say the file does not exist there.
What the manuals already tell you
The systemd resource-control manual says the same in unit terms: CPUQuota= takes a percentage relative to the total CPU time available on one CPU, so 50% is half of one CPU, not half of the machine, and CPUQuotaPeriodSec= defaults to 100 milliseconds. The probe adds the numbers the manuals do not give: the same work takes 1.92 times as long at 50% and 3.95 times at 25%, the CPU time stays nearly flat, nearly every period is throttled, and usage plus throttled accounts for about 96 to 97% of wall time.
A quota is a hard cap, not a weight. The kernel documentation has a separate interface, cpu.weight, for relative shares under contention: a weight only matters when CPUs are busy, and a weighted group can still use idle capacity. A quota throttles even when the machine is idle. That is the distinction that decides which knob to reach for, and it is the same distinction the memory controller draws between a throttle and a hard limit. The sibling guide on this site measures the memory side: a MemoryMax cap kills the process, a MemoryHigh throttle stalls it.
What this guide does not cover
The scope is one workload shape: a single-threaded integer loop with no syscalls, no memory traffic, and no I/O. A multi-threaded group shares one quota across its threads, so the same limit can bite much faster when several threads burn the budget in parallel; that case is not measured here, and this guide does not claim the single-threaded numbers apply to it. The scope is one quota period, the 100 millisecond default: shorter or longer periods were not tested. The burst allowance was left at its zero default, so banking quota from quiet periods is not measured. And the guide measures what happens after the limit is set, not how to size the limit: sizing from observed usage is the use the counters support, and the usage-flat finding is the number to size against.
Checklist
- Before trusting a slow service under a CPU limit, check cpu.stat: if usage_usec is flat across quotas and nr_throttled is nearly every period, the quota is the clock, not a slower machine.
- Before reading throttled time off a dashboard, check cpu.stat: pressure totals tracked throttled time within 0.1 to 1.0 seconds here, but one run missed by 35%, so the counters win when they disagree.
- Before telling someone to
cat cpu.maxon an unlimited unit, check the path: on a systemd user scope the file does not exist until a quota is set, and the read fails. - Before treating a quota as a weight, stop: a quota throttles on an idle machine, a weight only matters under contention, and the two knobs answer different questions.
- Before quoting a wall time from one night, run the probe again: the baseline moved from 2.975 to 3.019 seconds between nights, and the ratios moved from 1.94 to 1.92 and 3.92 to 3.95, while every direction held.
Related guides on this site
- cgroup v2 MemoryMax: What Actually Happens When a Process Hits the Limit, Measured
- systemd Timers vs Cron: What Actually Happens When a Run Is Missed
- nginx Reload vs Restart: What Actually Happens to In-Flight Requests
- epoll vs poll vs select, Measured: Where the Crossover Actually Is
Sources
- Linux kernel, Control Group v2 — the mechanism primary, read fresh 2026-11-09: cpu.max is "$MAX $PERIOD", the group may consume up to $MAX in each $PERIOD, "max" for $MAX means no limit, default "max 100000"; cpu.max.burst defaults to 0; cpu.pressure shows pressure stall information; cpu.weight is the relative-share interface, distinct from the quota.
- systemd.resource-control(5) — the unit-settings primary, read on the box 2026-11-09, systemd 255: CPUQuota= takes a percentage relative to the total CPU time available on one CPU; CPUQuotaPeriodSec= defaults to 100 milliseconds, clamped to 1 millisecond to 1000 milliseconds.
- golinuxcloud, Linux cgroup CPU limit: v2 cpu.max, v1 cfs quota, systemd CPUQuota — the nearest existing guide, read in full 2026-11-09: a full how-to with one illustrative cpu.stat snapshot from a stress run at 25% (usage_usec 875626, nr_periods 35, nr_throttled 33, throttled_usec 4063716); no fixed-work wall-clock timing, no medians, no 50% against 25% scaling, no checksum or usage-constancy check, no pressure numbers; a system.slice service reading "max 100000" before a quota is set, against this probe's user scopes where the file does not exist.
- Veldica, cgroup v2 MemoryMax: What Actually Happens When the Process Hits the Limit, Measured — the sibling guide: the memory controller measured with the same tool on the same box; a MemoryMax kill in about 25 milliseconds against a MemoryHigh stall at about 0.16 MiB per second.
Keep Exploring
Paste a [Service] section and get a plain-language verdict on every sandboxing setting it finds.
Paste sshd -G output and get a hardening verdict on the values your server actually runs.
Paste a server block and get WebSocket, TLS, HSTS, and proxy-header verdicts.
Paste a systemd timer expression and get the specific reason it fails, the normalized form, and the past-date traps the built-in check hides.
The full sysadmin hub \u2014 systemd, cgroups, file tools, and measured Linux comparisons.