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.

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
- Por que o script roda no SSH e quebra no cron
- Qual Python a sua conta tem e onde ele fica
- Criar o ambiente virtual e instalar as dependências
- Prove o interpretador com sys.executable antes de agendar
- A linha do cron: interpretador absoluto, script absoluto e log
- Os erros literais do cron e o que cada um significa
- 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:
- a primeira linha devolve a versão do Python do venv;
- a segunda devolve o caminho completo terminando em
venvs/app1/bin/python, provando que o interpretador carregado é o do ambiente; - a terceira devolve a versão do pacote. Se ela falhar com
ModuleNotFoundError, o pacote foi instalado em outro lugar. Reative o venv e repita opip install.
Só depois que as três respondem é que vale agendar.
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:
>>acumula no arquivo. Com>o log é sobrescrito a cada execução.2>&1manda o erro para o mesmo arquivo. Sem isso, o traceback some e você fica com um log vazio achando que deu certo.- Se o script lê arquivos com caminho relativo, prefixe com
cd /home/usuario/scripts &&, porque o diretório de trabalho do cron não é a pasta do script.
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 |
Checklist antes de fechar a tarefa
~/venvs/app1/bin/python -c "import sys; print(sys.executable)"devolve o caminho do venv.- O import de cada dependência responde sem erro usando esse mesmo caminho absoluto.
- A linha do cron tem interpretador absoluto, script absoluto e
>> log 2>&1. - A pasta de log existe.
- Você agendou primeiro para daqui a poucos minutos, conferiu o log, e só depois ajustou para o horário real.
- 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
- Documentação oficial (cpanel) — How to Use Python on AlmaLinux, Rocky Linux, Ubuntu and CloudLinux 9+. Consultado em 2026-10-04.