cc @indygreg

Please read the issue of why this flag is needed and see also actual use-case from #109595 (comment)

Even if the container system is important these days, there is no way to limit CPU resources for the container environment from Python program side.
JDK provides -XX:ActiveProcessorCount=<n> from JDK 21 instead of supporting cgroup, this patch will provide identical feature to Python user and super useful :)

The majority wants PYTHON_CPU_COUNT env name: https://discuss.python.org/t/change-environment-variable-style/35180

@gpshead I will merge this PR by tomorrow. Please let me know if there needs more change. :)
cc @vstinner

Congrats.

🎉 thanks everybody!

Thanks @vstinner and @gpshead for all your efforts to consider every use case!!

Follow-up: issue #110649 to add -X cpu_count=process.

Hello,

Just a ping to say that the function doesn't work and the doc is wrong.
https://docs.python.org/3/library/os.html#os.cpu_count

Changed in version 3.13: If -X cpu_count is given or PYTHON_CPU_COUNT is set, cpu_count() returns the overridden value n.

expected: PYTHON_CPU_COUNT should change the return value of os.cpu_count on python 3.13+ as explained by the doc.
what happens: PYTHON_CPU_COUNT has no effect.

It seems the value is only read once at interpreter startup.

FYI: This is a problem because python cannot detect the number cores correctly. It's not aware of the number of cpu exposed to containers/VM and try to use all CPU from the host machine, it's not aware of the number of CPU it should use in compute clusters that expect 1 core per job.
This requires developers/users to implement their own code to detect cpu, and patch the python code in the sitecustomize/interpreter code to fix applications they can't modify directly.

I was looking forward to setting PYTHON_CPU_COUNT on interpreter startup to finally fix the issue in a simple consistent way, but it doesn't work ^^

expected: PYTHON_CPU_COUNT should change the return value of os.cpu_count on python 3.13+ as explained by the doc.
what happens: PYTHON_CPU_COUNT has no effect.
It seems the value is only read once at interpreter startup.

You're correct: the PYTHON_CPU_COUNT environment variable is only read once at startup, not during execution.

If you really have to change os.cpu_count() return value at runtime, you can mock the function:

But it's better to set the environment variable before Python startup.

But it's better to set the environment variable before Python startup.

I agree but it's not possible in practice.

• In spark/slurm compute clusters, I could configure the clusters to add an environment variable with the number of CPU to be used by the job
• In kubernetes, there is no way to automatically configure kubernetes to add an environment variable matching the number of cpu limit on the pod. (this would need some logic anyway because cpu limit can be fractional)
• plenty of other environments where it's not possible to set an environment variable before the process starts

So the fix for me is to fix the CPU detection in the sitecustomize.py and configure environment variables for all the known frameworks: OMP_NUM_THREADS, OPENBLAS_NUM_THREADS, POLARS_MAX_THREADS, PYTHON_CPU_COUNT etc...
I was hoping to not have to patch os.cpu_count() anymore, but I guess no choice :D

For reference, this is a pretty critical issue with the last generation of server CPUs released in 2024 which have way more cores (up to 192c/384t per socket). It only take a few misbehaved apps/libraries each trying to create N subthreads/subprocesses to accidentally kill the server and other jobs.

64x64 on an older server is merely 4096 threads/processes. 512x512 on a recent server is 262144 threads/processes.

This closed issue is not the right place to ask questions on how to use Python. I suggest you finding another place to ask your question such as the Python Help category of discuss.python.org.

This thread is the right place to discuss cpu detection in the interpreter, as it was modified by this ticket and needs further improvements.

1. do you mind if I send a patch to the doc, to mention that the variable is only read once at startup?

2. do you mind if we correct the code to actually respect the variable at runtime?
   https://github.com/python/cpython/blob/3.14/Lib/os.py#L1180

3. do you mind if we correct these functions to return the correct number of CPU, taking into account cgroup limits.
   there was another thread asking about that few years ago, which was closed by you.
   since your last comment, the problem has been standardized with cgroup v2, it's just one file to read with some numbers. happy to discuss with this thread or the other.
   os.cpu_count() should return a count assigned to a container or that the process is restricted to #80235

do you mind if I send a patch to the doc, to mention that the variable is only read once at startup?

You can propose a PR, I don't know if it would be accepted. @corona10 added this feature.

do you mind if we correct the code to actually respect the variable at runtime?

I don't think that it's a good idea. It's common in Python to only read an environment variable once at startup.

do you mind if we correct these functions to return the correct number of CPU, taking into account cgroup limits.

So far, the consensus is to not read cgroup limits since there is not reliable way to get a number of CPUs. Again, this closed issue is not the right place to discuss it.

You can propose a PR for doc. But rest of things does not look like good idea.

morotti please open a thread on discuss.python.org ideally which could ultimately spawn new issues. closed PRs are not a meaningful place for discussions.