Crontab Guide

A cron expression is only half of a cron job. The other half is the crontab — the file that pairs each schedule with a command, and that carries its own syntax, its own environment, and a handful of rules that will happily eat your job without telling you. This guide covers editing and listing crontabs, the difference between user and system crontabs, the environment variables that matter, and the escaping rules that catch everyone at least once.

Anatomy of a crontab line

A user crontab line is a cron expression followed by the command to run. Everything after the fifth field is the command, spaces included — cron does not need quoting around it.

# ┌───────────── minute (0-59)
# │ ┌─────────── hour (0-23)
# │ │ ┌───────── day of month (1-31)
# │ │ │ ┌─────── month (1-12)
# │ │ │ │ ┌───── day of week (0-6, Sunday = 0)
# │ │ │ │ │
  30 2 * * *  /usr/local/bin/backup.sh --full

Blank lines are ignored and lines starting with # are comments. Comments must be on their own line: cron does not strip a trailing # from a command line, so 0 3 * * * /bin/job.sh # nightly passes # nightly to the shell rather than discarding it. Harmless in that example, less harmless when the comment contains a character the shell acts on.

Use the builder to compose the schedule and the explainer to verify a line you inherited; this guide covers everything to the right of the fifth field.

Editing and listing your crontab

Never edit the spool file directly. The crontab command validates syntax and signals the daemon to reload; hand-editing /var/spool/cron/ does neither.

Choosing the editor

crontab -e uses $VISUAL, then $EDITOR, then a system default that is often vi. Set it explicitly if that surprises you:

EDITOR=nano crontab -e

User crontabs vs system crontabs

There are two formats, and the difference is one extra field. Mixing them up is a frequent cause of "my job never runs".

A system crontab line looks like this — note the root before the command:

30 2 * * * root /usr/local/bin/backup.sh --full

Put that same line in a user crontab and cron tries to execute a program called root. Put a user crontab line in /etc/cron.d/ and cron treats the first word of your command as the username, fails to resolve it, and logs an error you will only find if you go looking.

The environment: PATH, SHELL and MAILTO

This is the single biggest source of "it works in my terminal but not in cron". Cron does not read .bashrc, .bash_profile, .profile or any other login file. Your aliases, your exported variables, your version manager shims and your PATH additions are all absent.

A typical cron environment is roughly:

SHELL=/bin/sh
PATH=/usr/bin:/bin
HOME=/home/youruser
LOGNAME=youruser

Two consequences follow. First, /usr/local/bin is usually not on the path, so anything you installed yourself will not be found by name. Second, the shell is /bin/sh, not bash, so bashisms such as [[ ]], &> and arrays may fail depending on what sh points at.

You can set variables at the top of a crontab. Assignments apply to every line below them:

SHELL=/bin/bash
PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
MAILTO=ops@example.com

0 3 * * * /usr/local/bin/nightly.sh

Note that variable assignment in a crontab is literal, not shell syntax. PATH=$PATH:/opt/bin does not expand — cron stores the string $PATH:/opt/bin verbatim. Write the full path out, or set it inside the script instead.

Escaping: the percent sign rule

Inside a crontab, an unescaped % is special. The first one and everything after it is removed from the command and fed to the command on standard input, with each subsequent % becoming a newline. This is a feature for supplying input to a program, and a trap for anyone using date.

# Wrong — everything from %Y onward becomes stdin
0 1 * * * /bin/tar czf /backup/$(date +%Y%m%d).tgz /srv

# Right — escape each percent
0 1 * * * /bin/tar czf /backup/$(date +\%Y\%m\%d).tgz /srv

Because this rule applies only to crontabs and not to scripts, the same command that fails as a crontab line works unchanged inside a shell script — another argument for keeping the crontab line trivial.

The missing final newline

Historically, a crontab file whose last line had no trailing newline would have that last job silently ignored. Modern crontab -e fixes this for you, but a crontab installed from a file (crontab jobs.txt) or written into /etc/cron.d/ by a deploy script can still hit it. If your last job is the only one not running, check for the newline first.

Capturing output and exit codes

By default, anything a cron job writes to stdout or stderr is mailed to the job's owner. On a machine with no mail transport configured — which is most machines now — that output goes nowhere. A job can fail every night for months without producing a single visible signal.

Redirect explicitly:

# Append both streams to a log
0 3 * * * /usr/local/bin/nightly.sh >> /var/log/nightly.log 2>&1

# Log errors only; discard normal output
0 3 * * * /usr/local/bin/nightly.sh > /dev/null

# Timestamp each line
0 3 * * * /usr/local/bin/nightly.sh 2>&1 | /usr/bin/ts >> /var/log/nightly.log

The common anti-pattern is > /dev/null 2>&1, which discards errors as well as output and guarantees that a broken job stays broken quietly. If you want silence on success and noise on failure, let the script exit non-zero and write to stderr only when something goes wrong — cron will then mail you (if mail works) or your monitoring will notice the non-zero exit. Better still, use a dead-man's-switch check-in as described in the best practices guide.

Permissions and cron.allow

Whether a user may install a crontab at all is controlled by two files:

• /etc/cron.allow — if it exists, only users listed in it may use crontab.
• /etc/cron.deny — consulted only when cron.allow does not exist; users listed here are refused.
• If neither file exists, behaviour depends on the distribution: some allow everyone, some allow only root.

A user who is refused sees You (name) are not allowed to use this program from crontab -e. Note that these files govern installing crontabs, not running jobs — a job already installed keeps running even if the user is later added to cron.deny.

Beyond that, ordinary Unix permissions apply. The script must be executable (chmod +x), readable by the user cron runs it as, and every directory in its path must be traversable by that user. A job that runs as www-data cannot read a script in a home directory set to mode 700.

A checklist before you save

1. Does the schedule mean what you think? Paste it into the Explainer and read the next five run times, not the syntax.
2. Are both day-of-month and day-of-week restricted? If so, cron applies OR logic and the job runs more often than you expect.
3. Is every path absolute — the interpreter, the script, the data files, the log?
4. Is every % escaped as \%?
5. Is output redirected somewhere you will actually look?
6. Does the script run correctly under a minimal environment? Test with env -i /bin/sh -c '/usr/local/bin/yourjob.sh'.
7. Is the file version-controlled and deployed with crontab jobs.txt, rather than typed into an editor on a production box?
8. Can the job overlap with itself if it runs long? If so, wrap it in flock.

If a job still does not fire after all of that, work through the troubleshooting guide, which starts at the daemon and the logs rather than the crontab.