The Five Fields
A crontab line is five time fields separated by spaces, followed by the command to run:
┌───────── 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.
| Character | Meaning | Example | Reads as |
|---|---|---|---|
* | Every value | * * * * * | Every minute |
, | A list | 0 9,17 * * * | At 9:00 and 17:00 |
- | A range | 0 9 * * 1-5 | At 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.
| Schedule | Expression |
|---|---|
| Every minute | * * * * * |
| Every 5 minutes | */5 * * * * |
| Every hour, on the hour | 0 * * * * |
| Every day at midnight | 0 0 * * * |
| Every day at 2:30am | 30 2 * * * |
| Weekdays at 9am | 0 9 * * 1-5 |
| Every Monday at 9am | 0 9 * * 1 |
| First day of every month at midnight | 0 0 1 * * |
| Every Sunday at 4am | 0 4 * * 0 |
| Every quarter (Jan, Apr, Jul, Oct 1st) | 0 0 1 1,4,7,10 * |
| Once a year, January 1st at midnight | 0 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:
| Shortcut | Same as |
|---|---|
@yearly or @annually | 0 0 1 1 * |
@monthly | 0 0 1 * * |
@weekly | 0 0 * * 0 |
@daily or @midnight | 0 0 * * * |
@hourly | 0 * * * * |
@reboot | Once, 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:
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:
# 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:
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:
# /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:
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.