blog
Painéis

Agendar script Python no cron do cPanel sem ModuleNotFoundError

Guia documental para criar o venv, instalar as dependências com pip e provar qual interpretador o cron vai carregar antes de agendar.

JR · · 6 min de leitura · 2 tabelas · 8 blocos de código

Resposta curta: o cron do cPanel não ativa o seu ambiente virtual, então a linha precisa chamar o caminho absoluto do Python do venv (exemplo: /home/usuario/venvs/app1/bin/python). É isso que elimina o ModuleNotFoundError e o /usr/bin/python: No such file or directory.

Neste artigo
  1. Por que o script roda no SSH e quebra no cron
  2. Qual Python a sua conta tem e onde ele fica
  3. Criar o ambiente virtual e instalar as dependências
  4. Prove o interpretador com sys.executable antes de agendar
  5. A linha do cron: interpretador absoluto, script absoluto e log
  6. Os erros literais do cron e o que cada um significa
  7. Checklist antes de fechar a tarefa

Por que o script roda no SSH e quebra no cron

Você entra por SSH, digita python app.py, o script roda. Agenda a mesma coisa no Cron Jobs do cPanel e recebe um e-mail com uma linha só:

Traceback (most recent call last):
  File "/home/usuario/scripts/app.py", line 1, in <module>
    import requests
ModuleNotFoundError: No module named 'requests'

Ou, pior, nem chega a abrir o arquivo:

/bin/sh: /usr/bin/python: No such file or directory

Os dois erros têm a mesma raiz: o cron não é a sua sessão de SSH. Ele não lê o seu .bashrc, não tem o ambiente virtual ativado e usa um PATH curto. Quando você escreve apenas python na linha do cron, está apostando que o shell vai encontrar o mesmo interpretador que você usou na mão. Em AlmaLinux, Rocky Linux e CloudLinux 9 ou superior não existe mais o atalho /usr/bin/python apontando para Python 2, e o Python que o seletor do painel cria fica em outro lugar, fora do PATH padrão do cron.

A solução é sempre a mesma: descobrir o caminho absoluto do interpretador certo, provar a versão antes de agendar e escrever esse caminho inteiro na linha do cron.

Qual Python a sua conta tem e onde ele fica

A documentação do cPanel orienta usar ambiente virtual para aplicações de usuário. A explicação é nossa: o Python que vem com o sistema operacional pertence ao sistema, é usado por ferramentas do próprio servidor, e instalar pacotes nele fora de um venv mistura as suas dependências com as da distribuição.

Na prática, você vai encontrar uma destas situações na sua hospedagem:

Onde procurar O que indica O que usar no cron
cPanel > Software > Setup Python App A hospedagem tem o seletor de versões (CloudLinux). O próprio painel cria e gerencia o virtualenv O caminho do python do virtualenv que o painel mostra
SSH: python3 -V responde Existe Python do sistema disponível para você Crie seu próprio venv e use o python dele
python -V responde "command not found" Não há alias de Python 2. Normal em EL9 Nunca escreva python sem caminho

Quando a hospedagem tem o Setup Python App

Entre em cPanel > Software > Setup Python App e clique em Create Application. Escolha a versão do Python, informe a pasta da aplicação (exemplo: scripts) e salve. Ao abrir a aplicação criada, o painel exibe no topo uma linha pronta de ativação, no formato source /home/usuario/virtualenv/scripts/3.11/bin/activate (exemplo fictício, o seu caminho muda conforme usuário, pasta e versão).

Guarde esse caminho. O interpretador do cron é o bin/python dessa mesma pasta.

Quando não existe seletor de versão do Python

Você cria o ambiente na mão, por SSH ou pelo Terminal do cPanel. Funciona igual.

Criar o ambiente virtual e instalar as dependências

Abra cPanel > Avançado > Terminal (ou conecte por SSH) e rode uma linha de cada vez.

Confirme qual python3 a conta usa como base

python3 -V
which python3

Esperado: algo como Python 3.11.2 e um caminho, por exemplo /usr/bin/python3. Se o primeiro comando falhar, pare aqui: a conta não tem Python do sistema liberado e o caminho é o seletor do painel ou abrir chamado com o provedor.

Crie o venv dentro da sua home

cd ~
python3 -m venv ~/venvs/app1

Não aparece saída quando dá certo. Isso cria a pasta ~/venvs/app1 com bin/python, bin/pip e as bibliotecas isoladas. Nada fora dessa pasta é alterado, então o risco é baixo: para desfazer, basta rm -rf ~/venvs/app1 e criar de novo.

Ative o ambiente e instale os pacotes

source ~/venvs/app1/bin/activate
pip install --upgrade pip
pip install requests

Com o ambiente ativo, o prompt ganha o prefixo (app1). O pip aqui é o do venv, então os pacotes vão para dentro de ~/venvs/app1, não para o Python do sistema. Se você já tem um requirements.txt, troque a última linha por pip install -r requirements.txt.

Para sair do ambiente, digite deactivate.

Prove o interpretador com sys.executable antes de agendar

Esta é a etapa que a maioria pula e que evita o e-mail de erro às 3 da manhã. Antes de criar o cron, execute o script exatamente como o cron vai executar: com caminho absoluto e sem ativar nada.

deactivate 2>/dev/null
~/venvs/app1/bin/python -V
~/venvs/app1/bin/python -c "import sys; print(sys.executable)"
~/venvs/app1/bin/python -c "import requests; print(requests.__version__)"

O que esperar:

Só depois que as três respondem é que vale agendar.

Do interpretador até a linha do cronAchar o python3python3 -V e which python3Criar o venvpython3 -m venv ~/venvs/app1Instalar dependênciaspip install dentro do venvProvar o interpretadorprint(sys.executable) sem ativar nadaAgendar no cronCaminhos absolutos e log
Só agende depois que o teste com caminho absoluto responder.

A linha do cron: interpretador absoluto, script absoluto e log

Vá em cPanel > Avançado > Cron Jobs. Em Common Settings, escolha a frequência (ou preencha minuto, hora, dia, mês e dia da semana). No campo Command, escreva caminho absoluto do interpretador, caminho absoluto do script e redirecionamento de saída:

/home/usuario/venvs/app1/bin/python /home/usuario/scripts/app.py >> /home/usuario/logs/cron-app1.log 2>&1

Troque usuario pelo seu nome de usuário do cPanel (ele aparece no canto direito do painel). Crie a pasta antes com mkdir -p ~/logs, senão o cron falha por não conseguir escrever o log.

Detalhes que importam:

Receber ou calar o e-mail do cron

No topo da página Cron Jobs existe o campo Cron Email. Tudo que o comando imprimir na tela vira e-mail para esse endereço. Com o redirecionamento acima, a saída vai para o log e o e-mail só chega se algo escapar. Para desligar o e-mail de vez, apague o endereço do campo ou acrescente >/dev/null 2>&1 no fim, ciente de que você perde o diagnóstico.

Para ler o log depois:

tail -n 50 ~/logs/cron-app1.log

Os erros literais do cron e o que cada um significa

Mensagem Causa provável Correção
/bin/sh: /usr/bin/python: No such file or directory A linha do cron chama um binário que não existe. Em EL9 não há /usr/bin/python Use o caminho completo do bin/python do venv
/bin/sh: python: command not found O PATH do cron não inclui o diretório do interpretador Mesmo remédio: caminho absoluto
ModuleNotFoundError: No module named 'requests' O cron chamou o Python do sistema, que não enxerga os pacotes do venv Aponte para o python do venv e revalide com sys.executable
Permission denied O arquivo não pertence ao seu usuário ou está sem permissão de leitura Confira dono e permissão com ls -l; chmod +x não é necessário quando você chama o interpretador na linha do cron
/bin/sh: /home/usuario/logs/cron-app1.log: No such file or directory A pasta de log do redirecionamento não existe mkdir -p ~/logs e rode o cron de novo
Log vazio e nenhum e-mail Saída não redirecionada ou erro engolido Acrescente >> arquivo.log 2>&1
IndentationError ou erro de sintaxe que não acontece no SSH Versão de Python diferente da que você testou Rode ~/venvs/app1/bin/python -V e compare com a versão que respondeu no teste manual
Qual erro do cron você recebeuO cron reclamou de quê?Leia a primeira linha do erroBinário não existeUse bin/python do venvModuleNotFoundErrorCron chamou o Python erradoPermission deniedConfira dono e permissão com ls -lLog vazio, sem e-mailFalta >> arquivo.log 2>&1Pasta de log ausenteRode mkdir -p ~/logs
Caminho de leitura dos erros mais comuns do cron.

Checklist antes de fechar a tarefa

  1. ~/venvs/app1/bin/python -c "import sys; print(sys.executable)" devolve o caminho do venv.
  2. O import de cada dependência responde sem erro usando esse mesmo caminho absoluto.
  3. A linha do cron tem interpretador absoluto, script absoluto e >> log 2>&1.
  4. A pasta de log existe.
  5. Você agendou primeiro para daqui a poucos minutos, conferiu o log, e só depois ajustou para o horário real.
  6. Se atualizar a versão do Python no seletor do painel, volte na linha do cron: o caminho do venv muda junto e o cron para de achar o binário.

Um detalhe final sobre manutenção: trate o venv como descartável. Mantenha o requirements.txt versionado junto do script, e recriar o ambiente vira três comandos em vez de uma arqueologia de pacotes instalados aos poucos.

Referências

  1. Documentação oficial (cpanel) — How to Use Python on AlmaLinux, Rocky Linux, Ubuntu and CloudLinux 9+. Consultado em 2026-10-04.
Leia também