configurar cron job no cPanel: causa e solução completa

15 min de leitura  ·  Guia técnico

Configurar cron job no cPanel significa agendar tarefas automáticas — como envio de e-mails, geração de relatórios ou limpeza de cache — para serem executadas em intervalos definidos sem intervenção manual. Quando o cron não executa, a causa mais comum é PATH incorreto, caminho relativo no comando ou permissão ausente no script. Veja abaixo como diagnosticar e corrigir cada situação.

1. Acesse o cPanel e localize a seção Cron Jobs em "Avançado".
2. Defina o intervalo de tempo usando os campos visuais ou a expressão cron manual.
3. Escreva o comando com caminhos absolutos para o interpretador e para o script.
4. Redirecione a saída para um arquivo de log com >> ~/cron.log 2>&1.
5. Salve o job e aguarde a próxima execução para verificar o log.
6. Ajuste permissões do script com chmod +x se necessário.

Pré-requisitos para configurar cron job no cPanel

• Acesso ao cPanel com usuário e senha válidos (versão 106 ou superior recomendada).
• Plano de hospedagem que permita execução de cron jobs (a maioria dos planos compartilhados da AviraHost inclui esse recurso).
• Script PHP, Python, Bash ou outro interpretador já enviado ao servidor via FTP ou Gerenciador de Arquivos.
• Conhecimento do caminho absoluto do script — por exemplo, /home/usuario/public_html/tarefa.php.
• Opcional: acesso SSH para verificar o PATH do ambiente e testar o comando antes de agendá-lo.
• Endereço de e-mail configurado no campo MAILTO do cPanel para receber saída de erros.

Como acessar a interface de cron jobs no cPanel

A interface de agendamento de tarefas automáticas no cPanel centraliza toda a configuração sem exigir edição manual do crontab. Para chegar até ela, siga este caminho:

1. Faça login no cPanel pelo endereço https://seudominio.com.br:2083.
2. Role a página até a seção Avançado (em alguns temas aparece como "Advanced").
3. Clique no ícone Cron Jobs.
4. Na parte superior da tela, configure o e-mail que receberá a saída de cada execução no campo Email e clique em Atualizar E-mail.

A tela exibirá dois blocos: o formulário para adicionar um novo job e a lista de jobs existentes. O formulário possui menus suspensos para minuto, hora, dia do mês, mês e dia da semana — o que elimina a necessidade de memorizar a sintaxe cron para casos simples.

Formato correto da expressão de tempo no cron do cPanel

A expressão de agendamento segue cinco campos separados por espaço, cada um representando uma unidade de tempo. Entender esse formato é essencial para evitar o erro mais frequente: job que nunca dispara por expressão mal formada.

# Formato:
# minuto  hora  dia_do_mes  mes  dia_da_semana  comando
# 0-59    0-23  1-31        1-12 0-7 (0 e 7 = domingo)

# Exemplos práticos:
30 3 * * *        # Executa às 3h30 todos os dias
0 */6 * * *       # Executa a cada 6 horas
0 8 * * 1         # Executa às 8h toda segunda-feira
*/15 * * * *      # Executa a cada 15 minutos
0 0 1 * *         # Executa à meia-noite no primeiro dia de cada mês

O cPanel oferece menus suspensos com opções como "Every Minute", "Every 5 Minutes", "Every Hour" etc., que preenchem automaticamente os campos. Para intervalos personalizados, use o campo de texto livre e insira a expressão diretamente.

Configurar cron job no cPanel para scripts PHP

Automatizar tarefas PHP via cron é o caso de uso mais comum em hospedagens compartilhadas — desde envio de newsletters até sincronização de estoque. O erro mais frequente aqui é usar apenas php no comando, sem o caminho absoluto do binário.

Para descobrir o caminho correto do PHP via SSH, execute:

which php

/usr/local/bin/php

Se o servidor usa o EasyApache 4 do cPanel com múltiplas versões de PHP, o caminho varia conforme a versão:

# PHP 8.1
/opt/cpanel/ea-php81/root/usr/bin/php

# PHP 8.2
/opt/cpanel/ea-php82/root/usr/bin/php

# PHP 8.3
/opt/cpanel/ea-php83/root/usr/bin/php

Com o caminho em mãos, monte o comando completo no campo Command do cPanel:

/opt/cpanel/ea-php83/root/usr/bin/php /home/usuario/public_html/cron/tarefa.php >> /home/usuario/cron.log 2>&1

O trecho >> /home/usuario/cron.log 2>&1 redireciona tanto a saída padrão quanto os erros para o arquivo de log, permitindo diagnóstico sem acesso ao e-mail.

Atenção: nunca use caminhos relativos como ./tarefa.php ou ../scripts/ no cron. O diretório de trabalho do cron não é o mesmo do shell interativo, e o script simplesmente não será encontrado.

Configurar cron job no cPanel para scripts Bash e Python

Scripts de shell e Python seguem a mesma lógica: caminho absoluto do interpretador seguido do caminho absoluto do arquivo. Para scripts Bash, é necessário garantir permissão de execução antes de agendar.

Verifique e corrija a permissão via SSH:

chmod +x /home/usuario/scripts/limpeza.sh

Comando para o campo do cPanel (Bash):

/bin/bash /home/usuario/scripts/limpeza.sh >> /home/usuario/bash_cron.log 2>&1

Para Python 3, descubra o caminho com which python3 e use:

/usr/bin/python3 /home/usuario/scripts/relatorio.py >> /home/usuario/python_cron.log 2>&1

Output esperado no log (se o script funcionar corretamente):
[2025-01-15 03:30:01] Relatório gerado com sucesso. 142 registros processados.

Se o script depende de variáveis de ambiente como HOME, USER ou PATH, defina-as explicitamente no início do script ou no próprio comando do cron, pois o ambiente do cron é mínimo por padrão.

Como verificar se o cron job está sendo executado

Monitorar a execução de tarefas agendadas é tão importante quanto configurá-las. Existem três formas principais de verificar se o job rodou corretamente no ambiente cPanel.

Método 1 — Arquivo de log dedicado: já incluído no comando com >> ~/cron.log 2>&1. Acesse o arquivo pelo Gerenciador de Arquivos do cPanel ou via SSH:

tail -f /home/usuario/cron.log

Output esperado:
[2025-01-15 03:30:02] Tarefa iniciada
[2025-01-15 03:30:04] 58 registros atualizados
[2025-01-15 03:30:04] Tarefa concluída

Método 2 — E-mail de saída: configure o campo MAILTO no topo da tela de Cron Jobs do cPanel. Cada execução enviará um e-mail com a saída do comando. Para desativar os e-mails (útil quando o job roda com frequência), defina MAILTO="" — mas isso só é possível editando o crontab via SSH com crontab -e.

Método 3 — Log do sistema via SSH: em servidores com acesso root, o log do cron fica em:

grep CRON /var/log/syslog | tail -20

Output esperado:
Jan 15 03:30:01 servidor CRON[12345]: (usuario) CMD (/opt/cpanel/ea-php83/root/usr/bin/php /home/usuario/public_html/cron/tarefa.php)

Em hospedagens compartilhadas, o acesso ao /var/log/syslog geralmente não está disponível, tornando o arquivo de log dedicado o método mais confiável.

Para tarefas relacionadas a banco de dados agendadas via cron, consulte também o artigo Conectando remotamente ao MySQL - cPanel para garantir que as credenciais e permissões de acesso estejam corretas antes de automatizar operações no banco.

Configurar cron job sem acesso SSH pelo cPanel

Uma das vantagens do cPanel é permitir o agendamento completo de tarefas sem nenhum conhecimento de linha de comando. O processo é inteiramente visual e funciona em qualquer plano de hospedagem compartilhada.

1. Acesse o cPanel e clique em Cron Jobs na seção Avançado.
2. No bloco Add New Cron Job, use os menus suspensos para definir o intervalo. Por exemplo, para executar diariamente às 2h: selecione 0 em Minute e 2 em Hour; deixe os demais campos como *.
3. No campo Command, insira o comando completo com caminhos absolutos.
4. Clique em Add New Cron Job.
5. O cPanel exibirá uma mensagem de confirmação e o job aparecerá na lista abaixo.

Para editar um job existente, clique em Edit na linha correspondente. Para remover, clique em Delete e confirme. Não há limite fixo de jobs por conta, mas jobs muito frequentes (a cada minuto) em hospedagens compartilhadas podem ser limitados pela política do servidor.

Se você gerencia múltiplos sites e precisa de mais controle sobre agendamentos, vale considerar um plano VPS onde o crontab do sistema oferece mais flexibilidade. Veja o comparativo em Hospedagem de sites vs. VPS: qual é a melhor opção?

Problemas comuns e como resolver

Sintoma: cron job configurado mas nunca executa

Causa: a expressão de tempo está incorreta ou o campo de comando está vazio. Outra causa frequente é o uso de caracteres especiais sem escape no comando, como %, que o cron interpreta como quebra de linha.
Solução: revise a expressão de tempo campo a campo. Se o comando contém % (comum em comandos date), escape com barra invertida: \%. Teste o comando manualmente via SSH antes de agendá-lo. Exemplo: /opt/cpanel/ea-php83/root/usr/bin/php /home/usuario/public_html/cron/tarefa.php — se funcionar no terminal, funcionará no cron com os mesmos caminhos.

Sintoma: cron executa mas o script retorna erro ou não faz nada

Causa: o script depende de variáveis de ambiente (PATH, HOME, DOCUMENT_ROOT) que existem no shell interativo mas não no ambiente mínimo do cron. Scripts PHP que usam $_SERVER ou funções que dependem de contexto web também falham quando executados via CLI.
Solução: adicione no início do script PHP a definição explícita das variáveis necessárias. Para scripts Bash, inclua source /etc/profile ou defina o PATH manualmente: PATH=/usr/local/bin:/usr/bin:/bin. Redirecione stderr para o log e analise a mensagem de erro exata.

Sintoma: erro "Permission denied" ao executar o script

Causa: o arquivo do script não tem permissão de execução, ou o diretório pai não tem permissão de leitura para o usuário do cron.
Solução: via SSH, execute chmod +x /home/usuario/scripts/tarefa.sh para scripts Bash. Para scripts PHP, a permissão de execução não é necessária no arquivo — o interpretador PHP é que precisa ter acesso de leitura ao arquivo. Verifique com ls -la /home/usuario/scripts/ e garanta que o arquivo tenha pelo menos permissão 644.

Sintoma: cron executa a versão errada do PHP

Causa: o comando usa apenas php sem caminho absoluto, e o PATH do cron aponta para uma versão diferente da configurada no cPanel para o domínio.
Solução: substitua php pelo caminho absoluto da versão correta. Confirme a versão em uso pelo site no cPanel em MultiPHP Manager e use o binário correspondente. Por exemplo, se o site usa PHP 8.3: /opt/cpanel/ea-php83/root/usr/bin/php.

Sintoma: cron gera e-mails em excesso ou não envia nenhum

Causa: quando o script produz saída (mesmo que seja apenas espaços em branco), o cron envia um e-mail por execução. Em jobs que rodam a cada minuto, isso gera centenas de mensagens por dia. O oposto ocorre quando o endereço MAILTO está incorreto ou o servidor de e-mail está bloqueado.
Solução: para suprimir e-mails, redirecione toda a saída para /dev/null (apenas se o log já estiver sendo salvo em arquivo): comando >> ~/cron.log 2>&1. Para desativar completamente os e-mails, edite o crontab via SSH com crontab -e e adicione MAILTO="" na primeira linha.

Perguntas frequentes sobre cron job no cPanel

Por que meu cron job no cPanel não está executando?

As causas mais comuns são: PATH incorreto no ambiente do cron (que difere do shell interativo), permissão de execução ausente no script, caminho absoluto não especificado para o interpretador ou para o arquivo, e erros de sintaxe na expressão de tempo. Verifique o log de saída redirecionando stderr para um arquivo de log com 2>&1 no final do comando. Testar o comando manualmente via SSH antes de agendá-lo é a forma mais rápida de isolar o problema.

Como verificar se um cron job foi executado no cPanel?

Redirecione a saída do cron para um arquivo de log adicionando >> /home/usuario/cron.log 2>&1 ao final do comando. Depois, acesse o arquivo via Gerenciador de Arquivos do cPanel ou via SSH com tail -f ~/cron.log. O cPanel também envia e-mail com a saída do cron se um endereço estiver configurado em MAILTO. Essa combinação — log em arquivo e e-mail de alerta — garante visibilidade completa sobre cada execução.

Qual é o formato correto da expressão de tempo no cron do cPanel?

O formato é: minuto (0-59), hora (0-23), dia do mês (1-31), mês (1-12) e dia da semana (0-7, onde 0 e 7 são domingo). Por exemplo, 30 3 * * * executa às 3h30 todos os dias. O cPanel oferece uma interface visual para montar a expressão sem precisar memorizar a sintaxe, com menus suspensos para cada campo e opções pré-definidas como "Every Hour" e "Every Day".

Como usar o PHP correto no cron job do cPanel?

Especifique o caminho absoluto do binário PHP correspondente à versão desejada, por exemplo /usr/local/bin/php ou /opt/cpanel/ea-php83/root/usr/bin/php. Evite usar apenas php no comando, pois o PATH do cron pode apontar para uma versão diferente da usada pelo site. Confirme o caminho correto executando which php ou php -v via SSH, e verifique a versão configurada para o domínio no MultiPHP Manager do cPanel.

É possível configurar cron job no cPanel sem acesso SSH?

Sim. Acesse o cPanel, vá em "Avançado" e clique em "Cron Jobs". Preencha os campos de intervalo de tempo e o comando completo com caminhos absolutos. Para scripts PHP, use o caminho completo do binário PHP seguido do caminho absoluto do script. A interface do cPanel elimina a necessidade de editar o crontab manualmente via terminal, tornando o processo acessível mesmo para usuários sem experiência em linha de comando.

Conclusão

• Use sempre caminhos absolutos: tanto para o interpretador (PHP, Python, Bash) quanto para o script — nunca caminhos relativos no comando do cron.
• Redirecione a saída para um log: adicione >> ~/cron.log 2>&1 a todo job novo para ter visibilidade imediata sobre erros de execução sem depender de e-mail.
• Teste antes de agendar: execute o comando completo via SSH antes de cadastrá-lo no cPanel — se funcionar no terminal com os mesmos caminhos, funcionará no cron.

Leia também

• Entenda o que é Cron: automatização de tarefas no Linux
• Passo a passo para configurar backup automático com cron no VPS Linux e servidor dedicado
• Passo a passo para configurar autenticação por chave SSH no painel WHM/cPanel

Precisa de ajuda com hospedagem e cron jobs no cPanel?

Os planos de hospedagem da AviraHost incluem suporte a cron jobs, múltiplas versões de PHP via MultiPHP Manager e painel cPanel completo. Se você está enfrentando dificuldades para configurar tarefas agendadas ou precisa de um ambiente com mais controle e recursos dedicados, nossa equipe pode orientar na escolha do plano mais adequado para o seu projeto.

Conheça os planos de hospedagem com cPanel da AviraHost