Como ler uma expressão cron, campo por campo

Uma expressão cron é uma linha curta de texto que diz a um agendador quando executar uma tarefa. A forma mais comum tem cinco campos separados por espaços: minuto, hora, dia do mês, mês e dia da semana. A linha 0 9 * * 1-5 significa 09:00, de segunda a sexta-feira. Cada campo é um número, um nome, uma lista, um intervalo ou um passo, ou * para todos os valores, e a tarefa roda em cada horário em que todos os campos coincidem.

Explicador de cronCron roda no horário erradoUse de graça

Os cinco campos

Campo	Valores permitidos	Exemplo
Minuto	0 a 59	`30` é o minuto 30 da hora
Hora	0 a 23	`9` é 09:00, no relógio de 24 horas
Dia do mês	1 a 31	`15` é o dia 15
Mês	1 a 12, ou JAN a DEC	`3` ou `MAR` é março
Dia da semana	0 a 6, ou SUN a SAT	`0` ou `SUN` é domingo, `1` é segunda-feira

Alguns sistemas também aceitam 7 para domingo, mas nem todos, então use 0 ou SUN. O cron não tem campo de segundos nesta forma, então o menor passo é de um minuto.

Listas, intervalos, passos e nomes

significa todos os valores do campo. * * * * roda a cada minuto.
Uma lista usa vírgulas. 0 9,17 * * * roda às 09:00 e às 17:00 todos os dias.
Um intervalo usa hífen. 1-5 no campo de dia da semana significa de segunda a sexta-feira.
Um passo usa barra. */15 no campo de minuto significa 0, 15, 30 e 45. 10-30/5 significa 10, 15, 20, 25 e 30.
Nomes, como MON-FRI, podem substituir números. São mais fáceis de ler, se o seu agendador aceitar.

Essas partes se combinam. 0 8-18/2 * * * roda no minuto 0 de cada duas horas, das 08:00 às 18:00.

Agendamentos comuns

Expressão	Significado
`* * * * *`	A cada minuto
`/15 * * *`	A cada 15 minutos
`0 * * * *`	No minuto 0 de cada hora
`0 2 * * *`	Todos os dias às 02:00
`0 9 * * 1-5`	09:00, de segunda a sexta-feira
`0 9,17 * * *`	09:00 e 17:00 todos os dias
`30 6 1 * *`	06:30 no dia 1 de cada mês
`0 0 * * 0`	Meia-noite de todo domingo
`0 0 1 1 *`	Meia-noite de 1º de janeiro
`/5 9-17 * 1-5`	A cada 5 minutos, das 09:00 às 17:55, de segunda a sexta-feira

Observe que 0 0 * * é meia-noite, e 0 12 * * é meio-dia. Errar a hora é um dos erros mais comuns.

Dia do mês e dia da semana

Quando os campos de dia do mês e de dia da semana são ambos restritos, a tarefa roda quando qualquer um deles coincide. Esta é a regra clássica do Vixie cron e de muitos sistemas derivados dele. Assim, 0 0 13 * 5 roda à meia-noite do dia 13 de cada mês e também toda sexta-feira. Muita gente espera apenas a sexta-feira 13 e acaba com mais execuções do que planejava.

Se um dos dois campos for *, só o outro conta. Para rodar na sexta-feira 13, agende uma tarefa para cada sexta-feira e verifique a data dentro do script. Outros agendadores, incluindo alguns serviços em nuvem, podem usar regras diferentes, então leia a documentação deles.

Fuso horário e horário de verão

O cron roda pelo relógio da máquina ou do serviço em que está, que normalmente é o fuso horário local dessa máquina. Uma tarefa marcada para 02:30 roda às 02:30 nesse relógio. Verifique o fuso primeiro (no Linux, date mostra). Se você quer que as tarefas sigam um só relógio em todo lugar, muitas equipes usam servidores em UTC, e alguns agendadores permitem definir um fuso para cada tarefa.

O horário de verão muda o relógio duas vezes por ano. Na primavera, muitos lugares pulam de 02:00 direto para 03:00, então uma tarefa às 02:30 não tem horário para rodar. No outono, a hora entre 01:00 e 01:59 acontece duas vezes. Os agendadores tratam esses casos de formas diferentes. Alguns pulam a tarefa, outros a rodam uma vez, e outros a rodam duas vezes. Mantenha as tarefas fora da janela de mudança da madrugada, ou use UTC, se a diferença importar para você.

Seis campos e Quartz

Alguns agendadores acrescentam um campo de segundos no início, então /10 * * * * roda a cada 10 segundos. O agendador Quartz para Java usa segundos, minutos, horas, dia do mês, mês, dia da semana e um ano opcional, e acrescenta quatro caracteres especiais:

? significa “nenhum valor específico”. O Quartz exige que ele esteja no campo de dia do mês ou no de dia da semana, naquele que você não definir.
L significa último. L no campo de dia do mês é o último dia do mês, e 6L no campo de dia da semana é a última sexta-feira.
W significa o dia útil mais próximo. 15W é o dia útil mais próximo do dia 15, e não pula para outro mês.
# significa a enésima ocorrência de um dia da semana. 6#3 é a terceira sexta-feira.

O Quartz numera os dias de forma diferente da forma de cinco campos. O 1 dele é domingo e o 7 é sábado, então de segunda a sexta-feira é 2-6, não 1-5. Sempre confira qual formato o seu agendador usa antes de copiar uma linha.

Erros comuns

*/7 no campo de minuto. Os valores são 0, 7, 14 e assim por diante, até 56. O próximo seria 63, que não existe, então a execução após 56 é no minuto 0 da hora seguinte. A diferença é de apenas quatro minutos, e o espaçamento fica irregular. Use um passo que divida 60 exatamente, como 5, 10, 15 ou 30.
30 de fevereiro. Essa data não existe, então 0 0 30 2 * nunca roda. O mesmo vale para o dia 31 em um mês de 30 dias. Pela regra do OU, uma restrição de dia da semana ainda pode fazer a tarefa rodar em outros dias, então confira o resultado.
Hora 24 ou minuto 60. São valores fora do intervalo. A maioria dos agendadores os rejeita quando você salva, mas nem todos.
Esperar segundos. Uma linha de cinco campos roda apenas em minutos inteiros.
Confundir cron com expressões regulares. No cron, significa todos os valores. Em uma expressão regular, significa repetir o item anterior. Use o testador de regex para padrões, e mantenha as linhas de cron separadas.

Confira as próximas execuções

Antes de confiar em um agendamento, leia a linha em palavras simples e liste seus próximos horários de execução. O explicador de cron faz as duas coisas, e é a forma mais rápida de pegar a regra do OU ou um passo estranho.

Respostas rápidas

O primeiro campo são minutos ou segundos?

Minutos, na forma padrão de cinco campos. Só alguns agendadores de seis campos acrescentam segundos, e eles os colocam primeiro.

Por que minha tarefa roda às sextas-feiras e também no dia 13?

Os campos de dia do mês e de dia da semana estão ambos definidos, então a tarefa roda quando qualquer um deles coincide. Defina um dos campos como * se quiser apenas o outro.

O cron usa UTC?

Só se a máquina ou o serviço estiver configurado para UTC. Caso contrário, ele usa o fuso horário local desse sistema.