os.process_cpu_count ajuda programas Python a descobrir quantas CPUs estão realmente disponíveis para o processo atual. Isso é especialmente útil em contêineres, servidores compartilhados, ambientes com afinidade de CPU e plataformas nas quais os.cpu_count() pode informar a capacidade física ou lógica do sistema inteiro, e não o limite efetivo imposto ao processo.
Neste guia, você aprenderá quando usar essa função, como dimensionar pools de workers, quais cuidados tomar e como criar fallbacks seguros.
O problema que a função resolve
Em aplicações paralelas, é comum escolher o número de workers com base na quantidade de núcleos. Entretanto, um servidor pode ter 32 CPUs e entregar apenas 4 para um contêiner. Usar 32 workers nesse cenário aumenta troca de contexto, memória, contenção e latência. os.process_cpu_count() busca representar a quantidade utilizável pelo processo, oferecendo uma base mais realista para decisões de concorrência.
import os
cpus = os.process_cpu_count()
print(cpus)
O retorno pode ser um inteiro positivo ou None quando a informação não estiver disponível. Portanto, nunca assuma que o valor existe sem validar.
Fallback seguro
import os
def cpus_disponiveis():
return os.process_cpu_count() or os.cpu_count() or 1
Esse padrão prioriza o limite do processo, depois consulta a contagem geral e, por fim, usa 1. O fallback evita criar pools com tamanho inválido e mantém o programa funcional em plataformas menos comuns.
Dimensionando ProcessPoolExecutor
from concurrent.futures import ProcessPoolExecutor
import os
workers = os.process_cpu_count() or 1
with ProcessPoolExecutor(max_workers=workers) as executor:
resultados = list(executor.map(abs, range(-100, 100)))
Para tarefas intensivas em CPU, um worker por CPU disponível costuma ser um ponto inicial razoável. Ainda assim, o melhor número depende do custo de serialização, uso de memória, duração das tarefas e presença de outras cargas no mesmo ambiente.
Não confunda CPU com I/O
Para chamadas HTTP, banco de dados e arquivos, o gargalo frequentemente é espera, não processamento. Nesses casos, uma quantidade de threads maior que a contagem de CPUs pode ser adequada. Veja também nosso conteúdo sobre asyncio.Runner, queue.SimpleQueue, TopologicalSorter e sys.monitoring.
Uso em contêineres
Contêineres podem receber cotas ou conjuntos específicos de CPUs. A função é valiosa porque evita calcular paralelismo apenas com base no host. Isso melhora previsibilidade em Kubernetes, Docker e serviços gerenciados. Mesmo assim, monitore throttling, consumo de memória e tempo de fila, pois a quantidade de CPUs não descreve toda a capacidade do ambiente.
Afinidade e limites dinâmicos
Administradores podem alterar afinidade ou políticas do processo. Por isso, capture o valor perto do momento em que o pool é criado, em vez de armazená-lo permanentemente em um módulo. Em serviços longos, recriar pools após mudanças relevantes pode ser necessário.
Escolha conservadora
import os
def tamanho_pool(reserva=1, limite=8):
total = os.process_cpu_count() or os.cpu_count() or 1
utilizavel = max(1, total - reserva)
return min(utilizavel, limite)
Reservar uma CPU pode manter o sistema responsivo. Um teto também impede explosões de memória quando cada worker carrega modelos, dataframes ou bibliotecas pesadas.
Testes
Não escreva testes dependentes da quantidade real de CPUs da máquina. Encapsule a consulta em uma função e use mock. Assim, você valida cenários com None, uma CPU e muitas CPUs sem depender do ambiente de CI.
from unittest.mock import patch
@patch("os.process_cpu_count", return_value=2)
def test_workers(_):
assert cpus_disponiveis() == 2
Observabilidade
Registre a contagem detectada, o tamanho escolhido para o pool, a duração das tarefas e o uso de CPU. Métricas ajudam a perceber quando o número teoricamente correto gera contenção. Combine esse dado com filas, percentis de latência e consumo de memória.
Erros comuns
Os erros mais frequentes são ignorar None, criar um worker por CPU para tarefas de I/O, usar o valor do host em contêineres, não limitar memória e presumir que mais workers sempre significam mais desempenho. Paralelismo excessivo pode tornar a aplicação mais lenta.
Compatibilidade
Consulte a documentação oficial do módulo os e as novidades do Python 3.13 para confirmar a versão mínima do seu ambiente. Em bibliotecas distribuídas para várias versões, use detecção de atributo.
import os
contador = getattr(os, "process_cpu_count", os.cpu_count)
cpus = contador() or 1
Quando usar
Use a função para pools de processos, processamento de imagens, compressão, cálculos científicos, ETL local e tarefas CPU-bound executadas em ambientes com restrições. Ela oferece um padrão melhor do que assumir a capacidade total da máquina.
Conclusão
os.process_cpu_count() torna o dimensionamento de paralelismo mais consciente do ambiente real. O valor deve ser tratado como ponto de partida, não como garantia de desempenho. A melhor estratégia combina fallback, limite conservador, testes, métricas e benchmarks com carga representativa.
