# 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.

> 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.

João Rizzon · 2026-10-05 · Painéis

---

## 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](https://docs.cpanel.net/knowledge-base/web-services/how-to-use-python-on-almalinux-rocky-linux-ubuntu-and-cloudlinux-9-and-later/) 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 o `pip 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>&1` manda 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.

