What a Cron Expression Actually Means (With Examples)

Cron is a well-known Unix job scheduler, and its schedule syntax has become widely used in various systems such as CI pipelines, cloud schedulers, and job queues. The syntax is succinct, but it can be easily misinterpreted. Here's how to read and write it with confidence.

A standard cron expression consists of five space-separated fields, read from left to right, specifying when a job should run: minute, hour, day of month, month, and day of week. Each field ranges from 0 to 59, 0 to 23, 1 to 31, 1 to 12, and 0 to 6, respectively (Sunday = 0).

For example, a job runs when the current time matches all five fields. The asterisk (*) signifies every possible value for that field. Commas (,) separate a list, such as 1,15 representing the 1st and 15th. Hyphens (-) define a range, like 1-5 denoting 1 through 5 (Monday to Friday in the day-of-week field). Forward slashes (/) signify a step, meaning */15 equals every 15 units, and 10-40/10 stands for 10, 20, 30, and 40.

Common schedules include:

- */5 * * * * for running every 5 minutes.

- 0 * * * * for running at the top of every hour.

- 0 9 * * 1-5 for running at 09:00 on weekdays.

- 30 2 * * 0 for running at 02:30 every Sunday.

- 0 0 1 * * for running at midnight on the first of every month.

- 0 0 1 1 * for executing once a year, at midnight on 1 January.

- 15 14 1 * * for running at 14:15 on the 1st of each month.

There are several pitfalls that could lead to missed jobs. Time zones are a common issue, as Cron runs in the time zone of the machine or service, which is often UTC. A job set to "9 AM" may fire at 9 AM UTC instead of in your local time. Cloud schedulers typically allow you to set a time zone explicitly, so it is essential to check before assuming.

In classic Vixie cron, if both the day-of-month and the day-of-week fields are restricted, the job runs when either one matches, not both. For instance, 0 0 13 * 5 fires on every 13th and on every Friday, not only on Friday the 13th.

Some systems, such as Quartz, Spring, and AWS EventBridge, add a seconds or year field, resulting in six or seven fields. Some dialects support names like MON or JAN and shortcuts like @daily or @hourly, while others do not. Daylight saving time can also cause issues in local time zones that observe it, as jobs scheduled during the skipped hour may not run, and those in the repeated hour may execute twice. Scheduling in UTC eliminates this problem.

Before deploying your cron expression, it's a good practice to paste it into a parser and read the plain-English translation. If it doesn't match your intended schedule, make the necessary adjustments before it inadvertently runs at the wrong time in production.