Esc

    ↑ ↓ to moveEnter to openEsc to close

    Guide

    Reading a Crontab

    Every cron schedule is five fields and a command, and here's how to read all of them.

    I've been writing crontab lines for 20 years, and this is all of it in one place, from what each field means to the gotchas that bite everyone eventually.

    The Five Fields

    A crontab line is five time fields separated by spaces, followed by the command to run:

    Text
    ┌───────── minute (0-59)
    │ ┌─────── hour (0-23)
    │ │ ┌───── day of month (1-31)
    │ │ │ ┌─── month (1-12, or jan-dec)
    │ │ │ │ ┌─ day of week (0-7, or sun-sat; 0 and 7 are both Sunday)
    │ │ │ │ │
    * * * * *  command to run
    

    Cron checks every minute whether the current time matches all five fields, and runs the command when it does. So 30 9 * * 1-5 /usr/local/bin/report runs at 9:30 in the morning, Monday through Friday.

    Hours use the 24-hour clock, so 2pm is 14 and midnight is 0. Times are in the server's time zone unless your cron supports setting another one, which I get into further down.

    The Special Characters

    Four characters do almost all the work.

    CharacterMeaningExampleReads as
    *Every value* * * * *Every minute
    ,A list0 9,17 * * *At 9:00 and 17:00
    -A range0 9 * * 1-5At 9:00 on weekdays
    /A step*/15 * * * *Every 15 minutes

    You can combine them. 0-30/10 * * * * runs at minutes 0, 10, 20, and 30 of every hour, and 0 8-18/2 * * 1-5 runs every 2 hours from 8am to 6pm on weekdays.

    A step always counts from the start of the range, so */7 in the minute field fires at 0, 7, 14, and so on up to 56, then again at 0. That leaves only 4 minutes between :56 and the next :00, which surprises people who expect a strict every-seven-minutes schedule.

    Common Schedules

    These are the ones I end up writing over and over.

    ScheduleExpression
    Every minute* * * * *
    Every 5 minutes*/5 * * * *
    Every hour, on the hour0 * * * *
    Every day at midnight0 0 * * *
    Every day at 2:30am30 2 * * *
    Weekdays at 9am0 9 * * 1-5
    Every Monday at 9am0 9 * * 1
    First day of every month at midnight0 0 1 * *
    Every Sunday at 4am0 4 * * 0
    Every quarter (Jan, Apr, Jul, Oct 1st)0 0 1 1,4,7,10 *
    Once a year, January 1st at midnight0 0 1 1 *

    If you'd rather not count fields in your head, paste any of these into the Cron Expression Generator. It explains the expression in plain English and lists the next run times in your time zone, which is the fastest way I know to catch a schedule that doesn't do what you meant.

    The Shortcuts

    Most cron implementations also understand a handful of named schedules in place of the five fields:

    ShortcutSame as
    @yearly or @annually0 0 1 1 *
    @monthly0 0 1 * *
    @weekly0 0 * * 0
    @daily or @midnight0 0 * * *
    @hourly0 * * * *
    @rebootOnce, when the cron daemon starts

    @reboot is handy for starting something when the server boots, though on a modern Linux box a systemd service is usually the better home for that.

    The Day-of-Month and Day-of-Week Trap

    Almost everyone runs into this one at some point.

    When you restrict both day fields, most crons run the job when either one matches. So 0 9 13 * 5 runs at 9am on the 13th of every month and also at 9am every Friday, which is probably a lot more often than you wanted.

    The catch is that cron only checks whether a day field starts with *. Something like */2 in the day of month counts as unrestricted, so 0 9 */2 * 5 goes back to needing both, and runs only on Fridays that fall on an odd-numbered day.

    If you want Friday the 13th specifically, schedule it for every Friday and have the script check the date itself:

    Bash/Shell
    0 9 * * 5  [ "$(date +\%d)" = "13" ] && /usr/local/bin/spooky-report
    

    That line also shows the next gotcha.

    Percent Signs Need Escaping

    Cron treats a bare % in the command as a newline, and everything after the first one gets sent to the command as standard input. Commands that format dates are where this usually shows up:

    Bash/Shell
    # Broken: cron cuts the command off at the first %
    0 0 * * * tar czf /backups/site-$(date +%F).tar.gz /var/www
    
    # Works: each % escaped with a backslash
    0 0 * * * tar czf /backups/site-$(date +\%F).tar.gz /var/www
    

    The other way around it is to move the command into a script and call the script from cron, which I'd do anyway once a line gets this long.

    Editing Your Crontab

    Each user has their own crontab. These are the commands you need:

    Bash/Shell
    crontab -e   # edit your crontab in your $EDITOR
    crontab -l   # print it
    crontab -r   # delete it, with no confirmation
    

    Be careful with crontab -r, because the r sits right next to the e on the keyboard and it deletes everything without asking. I keep a copy of anything important with crontab -l > ~/crontab.backup.

    There's also the system-wide crontab at /etc/crontab and the files in /etc/cron.d/. Those have a sixth field between the schedule and the command for the user to run as:

    Text
    # /etc/cron.d/backups
    30 2 * * *  www-data  /usr/local/bin/backup
    

    If you copy a line from one style into the other, add or remove that user field, or cron will try to run a command called www-data.

    Setting Variables at the Top

    You can set environment variables at the top of a crontab, and they apply to every line below:

    Bash/Shell
    MAILTO=you@example.com
    PATH=/usr/local/bin:/usr/bin:/bin
    SHELL=/bin/bash
    
    */5 * * * *  check-queue
    

    PATH matters more than people expect. Cron starts jobs with a very small environment, so a command that works in your terminal can fail in cron because it can't find the binary. Setting PATH here, or using full paths in the command, avoids most of that. MAILTO sends any output to that address, assuming the server can send mail.

    Some crons (cronie, the default on Fedora and RHEL) also read CRON_TZ to run the lines below it in another time zone. Debian and Ubuntu's cron doesn't support it, so check before you rely on it.

    When a Job Fails Quietly

    The hardest thing about cron is that it doesn't tell you when something goes wrong. A job with a typo in its path just doesn't run, and you find out 3 weeks later when you need the backup it was supposed to make.

    I wrote a whole guide on why cron jobs don't run and how to track it down. The short version is to send each job's output somewhere you'll actually look, and to use a heartbeat monitor like CronWatch for anything that matters, so you hear about a missed run the day it happens.

    Quick Reference

    Five fields (minute, hour, day of month, month, and day of week), followed by the command.
    • * is every value, , is a list, - is a range, and / is a step.
    • Both day fields restricted means either one matching is enough.
    • Escape % in commands, or move the command into a script.
    • Use full paths or set PATH, because cron's environment is tiny.
    • Check any schedule in the Cron Expression Generator before you trust it.

    Also by me

    CronWatch

    Once the syntax is right, the next thing to know is whether the job actually ran. I built CronWatch so you hear about a missed run the day it happens, without digging through logs weeks later.

    Visit cronwatch.dev