How does os.process_cpu_count() differ from os.cpu_count(), and what does it honour?

### Two counts, two questions Python has offered `os.cpu_count()` for a long time, and it answers a hardware question: how many logical processors does this machine expose — cores multiplied by hardware threads. **Python 3.13** added `os.process_cpu_count()`, which answers a permission question: how many logical processors may the calling thread of this process actually be scheduled onto. Both return an `int` or `None` when the platform cannot determine the value. On a developer laptop the two agree, and that is why the distinction is easy to miss. They diverge the moment something restricts where the process may run. ### The affinity mask On Linux each thread carries a CPU affinity mask: the set of processors the scheduler is permitted to place it on. A batch scheduler, a pinning wrapper such as `taskset`, or an orchestrator that assigns exclusive cores will narrow that mask. Narrowing it genuinely removes processors from the process's reach, and `os.process_cpu_count()` reflects that — a process pinned to four of a host's sixty-four processors reports 4. `os.cpu_count()` still reports 64, because the machine still has 64. This is the case where the older function is not merely imprecise but actively wrong for sizing: the extra workers can never be scheduled anywhere useful, so they add memory and context switching for no parallelism at all. ### What neither function sees A control-group CPU quota is a different kind of restriction. It does not narrow the set of processors; it caps how much CPU *time* the group may consume per period. The group's threads still run on any processor, they are simply stopped once the allowance for the period is spent. Because no processor is removed from the process's reach, the affinity mask is untouched and `os.process_cpu_count()` reports the full host count exactly as `os.cpu_count()` does. So the useful mental model is: `os.process_cpu_count()` covers *pinning*, and nothing in the `os` module covers *quota*. The quota has to be read from the control group's own files — `cpu.max` on cgroup v2, which holds either a limit and a period or the word `max`, and the `cpu.cfs_quota_us` / `cpu.cfs_period_us` pair on v1 — and reconciled with the affinity-aware count by taking the smaller of the two. ### The override **3.13** also added a deliberate escape hatch: the `-X cpu_count` interpreter option and the equivalent `PYTHON_CPU_COUNT` environment variable. Setting either makes *both* functions return the supplied value for the life of the interpreter. This is the intended way for a deployment system to tell Python what it is really allowed to use, and it is far more robust than patching every call site, because every library that quietly sizes something from the standard functions picks up the corrected number too. The tradeoff is honesty: the override is process-wide and indiscriminate. Anything asking for the machine's size for a legitimately different reason — a diagnostic banner, a hardware inventory — also gets the faked value. In practice that is almost always the trade you want, but it should be a conscious one. ### Why the standard-library defaults moved Before **3.13**, `concurrent.futures.ProcessPoolExecutor()` with no `max_workers` sized itself from `os.cpu_count()`; from 3.13 it uses `os.process_cpu_count()`, as does `multiprocessing.Pool()` when given no process count, and `concurrent.futures.ThreadPoolExecutor()` in its `min(32, cpu + 4)` formula. That change means a pinned process on a modern interpreter gets a sane default for free, where on 3.12 it would have started a worker for every processor on the host. It does not rescue the quota case, which still needs an explicit `max_workers` or a `PYTHON_CPU_COUNT` injection. ### Choosing between them Use `os.cpu_count()` when you genuinely mean the hardware: logging what machine a job landed on, or reporting capacity. Use `os.process_cpu_count()` — with `or 1` — whenever the number is going to size concurrency, and then clamp it against the quota if one exists. A one-line helper that does that reconciliation, called once at startup and logged, saves an enormous amount of confused profiling later. One last habit worth forming: neither function is free of `None`, and both are cheap enough to call but not free, so read the value once at startup into a module-level constant rather than calling it inside a hot path or, worse, recomputing it per submitted work item. Capturing it once also gives you a single place to log it, which turns the question "how many workers did this process think it could run" from an archaeology exercise into a grep.