os.process_cpu_count() should take cgroups CPU limitations into account (on Linux)

[itamarst]

Feature or enhancement

Proposal:

os.process_cpu_count() currently takes CPU core scheduler affinity into account. However, there are other ways to restrict CPU usage on Linux, most significantly cgroups as used by Docker and Kubernetes.

For example, if I ask for 2 cpus for a container, process_cpu_count() does not respect that:

$ docker run -it --cpus=2 python:3.14-slim python -c "import os; print(os.process_cpu_count())"
20

This can lead to surprising behavior for users, where too many threads are started in a container given the available resources.

An existing implementation in Python

In contrast, the loky.cpu_count() function does know about these restrictions:

$ docker run -it --cpus=2 python:3.14-slim bash
root@557b43351822:/# pip install --quiet loky
root@557b43351822:/# python    
Python 3.14.2 (main, Jan 13 2026, 03:08:39) [GCC 14.2.0] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> import loky
>>> loky.cpu_count()
2

You can read the loky implementation (permanlink to version as of May 6, 2026).

Has this already been discussed elsewhere?

This is a minor feature, which does not need previous discussion elsewhere

Links to previous discussion of this feature:

There was some discussion in #77167. Given cpu_count() is now distinct from process_cpu_count(), it seems useful to make the latter accurate, and cgroups as the basis for Linux containerization has a massive scale of deployment.

[picnixz]

This looks like a nontrivial implementation. Should we really make it part of the stdlib as this may vary across platforms and we would need to maintain this? Iam tagging it as a mp issue event though it is not mp-really (but it is related to mt/mp)

[itamarst]

If the final decision is that it's not worth doing, the minimalist option is to document the limitations of process_cpu_count() and point readers at better alternatives.

As a reference point, the (fairly minimal) Rust standard library decided to add cgroups support in 1.61 to the equivalent API. The detailed changelog explained that "Since available_parallelism is often used to create a thread pool for parallel computation, which may be CPU-bound for performance, available_parallelism will return a value consistent with the ability to use that many threads continuously, if possible. For instance, in a container with 8 virtual CPUs but quotas only allowing for 50% usage, available_parallelism will return 4."

I guess if Rust ever becomes a CPython dependency that would allow for an easy fix...

[picnixz]

I am perfectly ok for a doc update for now as it is largerly non-controversial. I would be interested in having something in the stdlib though, but the question is:

• can all Tier 1 platforms be properly supported?
• can Tier 2/3 platforms be supported at minimal cost?
• how maintainable will it be?

UUID is another beast where there are lots of checks since we want to support many platforms and I would honestly want to avoid this kind of code if possible.. if every Linux distribution needs its own check it will be hard to maintain properly =/ but we can make it as an iterative approach (start with common checks). We however do not want to end up with frozen dev as for ctypes.util.find_library() (I think we soft-deprecated that function)

[itamarst]

At first glance at the Rust std implementation as a potential baseline, I think it's mostly just adding cgroups support for Linux, none of the other OSes have much custom code beyond what Python already does (https://github.com/rust-lang/rust/tree/main/library/std/src/sys/thread).