Every week cron: what @weekly means and where the macro is not supported

What the macro expands to

Vixie cron introduced a handful of named schedules that replace the five fields: @yearly, @monthly, @weekly, @daily, @hourly and @reboot. @weekly is defined as 0 0 * * 0: minute 0, hour 0, any day of month, any month, day of week 0, which is Sunday. Writing the five fields out gives exactly the same schedule.

This page's parser expands the macro before describing it, which is why its reading is: At 00:00, on Sunday. The next run times in the panel above are computed in your browser, in your own timezone, so they are not printed in this text.

Where @weekly works and where it does not

Cronie and Vixie cron (the cron on most Linux distributions) and Kubernetes CronJobs accept the macro. GitHub Actions does not: its documentation lists the @ shorthands as unsupported, so a workflow needs cron: '0 0 * * 0'. Some minimal crons in embedded systems and small container images do not understand macros either. The five-field form is the portable one; the macro is easier to read.

systemd timers have their own shorthand OnCalendar=weekly, and it is not the same schedule: systemd defines it as Mon *-*-* 00:00:00, Monday at midnight. Porting a crontab line to a timer by name silently moves the job by a day; write OnCalendar=Sun *-*-* 00:00:00 to keep cron's meaning.

Example and pitfalls

@weekly /usr/sbin/fstrim -av is a classic weekly housekeeping line. Midnight on Sunday is when a lot of other weekly jobs also run, and in the server's zone, which on a cloud host is often UTC rather than the team's local time. Long weekly jobs should take a lock (flock -n /run/lock/fstrim.lock) and report their exit status, because a weekly failure can go unseen for a long time.

Plain cron does not catch up: if the host is off at midnight on Sunday, that week's run is lost. anacron, or a systemd timer with Persistent=true, runs it at the next boot instead.

Related schedules

If the job should run in working hours, every Sunday at 09:00 or every Monday at 09:00 are the common alternatives. @monthly and @yearly are the next macros up; @daily (also spelled @midnight) is the one below.