How to Write a systemd Timer with OnCalendar Instead of Cron

What a systemd timer is and how it works

A systemd timer is a unit file ending in .timer. It contains no command at all. Its only job is to activate another unit at the right moment, and unless you say otherwise that unit is the service with the same base name: backup.timer starts backup.service.

That split is the whole idea. The service says what the work is: which binary, which user, which environment, which sandbox. The timer says when. You can run the service by hand without touching the schedule, and you can change the schedule without touching the job.

System-wide units live in /etc/systemd/system/. Per-user units live in ~/.config/systemd/user/ and are managed with systemctl --user. Both kinds accept exactly the same OnCalendar syntax.

A complete systemd timer example with both files

Here is a full systemd timer example: a nightly backup that runs at 03:00. First the service unit, which holds the command.

# /etc/systemd/system/backup.service
[Unit]
Description=Nightly backup

[Service]
Type=oneshot
ExecStart=/usr/local/bin/backup.sh

Type=oneshot tells systemd the process is expected to run once and exit, rather than stay alive like a daemon. There is no [Install] section, and that is deliberate: this unit is never enabled on its own.

Then the timer unit, which holds the schedule.

# /etc/systemd/system/backup.timer
[Unit]
Description=Run the nightly backup at 03:00

[Timer] 03:00:00
Persistent=true

[Install]
WantedBy=timers.target

Two commands switch it on. Reload so systemd sees the new files, then enable and start the timer in one step.

sudo systemctl daemon-reload
sudo systemctl enable --now backup.timer

The full list of directives that can appear in a [Timer] section is in the systemd.timer manual page.

How does systemd OnCalendar syntax work field by field

A systemd OnCalendar value is not five space-separated numbers. It is a calendar expression built from three groups:

DayOfWeek Year-Month-Day Hour:Minute:Second

Each group can be dropped. Omit the day of week and every weekday matches. Omit the date and it means every day. Omit the seconds and they default to zero, so 03:00 and *-*-* 03:00:00 are the same schedule. An asterisk in any position means any value, just as in cron.

So the shortest daily schedule is a single time, and a weekday schedule is a day name plus a time:

OnCalendar=03:00 03:00 12:30:00 04:00:00

Which operators can you use in OnCalendar?

The two dots are the first thing that trips up people coming from cron, because a hyphen is already taken as the separator inside the date group. The ~ operator has no cron equivalent at all.

Can you use shorthand names like daily and weekly?

Yes. OnCalendar accepts a set of named schedules that expand to full expressions.

Every accepted form, including the ones not listed here, is specified in the systemd.time manual page.

Does OnCalendar use UTC or local time?

Local time, as configured on the host. That means a 03:00 job shifts with daylight saving, and two servers in different regions running the same unit file will not fire together.

systemd 252 and later let you pin the expression by appending a timezone name or UTC to it:

OnCalendar=Mon..Fri 09:00 UTC

On older releases the only lever is the host timezone itself, which our Linux date command generator will write out for you along with the command that verifies it took effect. If you need to know what a given local time is on another machine, the timezone converter does that conversion for any IANA zone.

Which cron expressions map to which OnCalendar values

Most migrations are mechanical. Read the cron fields in their usual order (minute, hour, day of month, month, day of week) and rebuild them as a calendar expression.

If you are not certain what the old cron line actually did, decode it before you translate it. Paste it into our cron builder and you get a plain English description, a per-field breakdown and the next 10 run times in your browser's local time.

What can a systemd timer do that cron cannot?

Two directives are the usual reason people move a job over in the first place.

Persistent=true makes systemd remember when the timer last fired by writing a stamp file on disk. If the machine was off or suspended at the scheduled moment, the job runs shortly after the next boot instead of being silently skipped. A cron job on a laptop that is closed at 03:00 simply never happens.

RandomizedDelaySec delays each activation by a random amount between zero and the value you give. Ship the same unit to 200 machines and their backups no longer all start on the same second and saturate the network.

[Timer] 03:00:00
Persistent=true
RandomizedDelaySec=30m
FixedRandomDelay=true

FixedRandomDelay=true keeps each machine's offset stable instead of rerolling it every day, so a host that starts at 03:17 keeps starting at 03:17.

Two more things cron has no answer for:

• AccuracySec controls how much systemd is allowed to shift the activation in order to batch timers together and let the CPU stay idle longer. The default is one minute, so set AccuracySec=1s when a job really must start on the second.
• Monotonic timers schedule relative to an event rather than a clock. OnBootSec=15min runs a quarter of an hour after boot, and OnUnitActiveSec=2h runs two hours after the last run finished, which never drifts into overlapping runs the way a fixed interval can.

How to check the next run with systemctl list timers

Never trust a schedule you have not read back. The command is systemctl list-timers, and it prints one row per active timer with the next elapse, how long is left, when it last ran, how long ago that was, the timer unit and the service it activates.

systemctl list-timers
systemctl list-timers --all
systemctl list-timers backup.timer

Add --all to include timers that are loaded but not currently active, which is how you notice the unit you thought you enabled. For a user timer, add --user.

To test an expression before it ever reaches a unit file, ask systemd to parse it directly:

systemd-analyze calendar "Mon..Fri 03:00"
systemd-analyze calendar --iterations=5 "*:0/15"

The output shows the form you typed, the normalized form systemd actually uses, and the next elapse. A typo is rejected here rather than quietly never firing. The --iterations flag prints several upcoming runs, which is the fastest way to confirm that a step expression steps the way you expected. Other systemd-analyze subcommands will also validate the unit files themselves.

Finally, check the job separately from the schedule. Run the service once by hand and read its output:

sudo systemctl start backup.service
journalctl -u backup.service -n 50

When should you use a systemd timer instead of cron?

Use a timer when the job matters: when a missed run needs to be caught up, when the job must wait for the network or the database to be up, when it should run under a restricted user with a sandbox, or when the same schedule ships to a fleet. The dependency directives and resource limits you already know from services all apply.

Stick with cron for a throwaway one-liner on a box you control, or when you are working on a system without systemd. Cron is one line in one file and that is a real advantage. If the cron job you already have is the problem, our guide on why a cron job is not running walks the usual causes before you rewrite anything. The Arch Wiki page on timers is a good second read once you have the basics down.

Cron expression builder

Get the schedule right before you write the unit file

Build the five cron fields visually or paste an existing expression to decode it, then read the next 10 run times in plain English and translate the result into OnCalendar.

Open the cron builderFree, runs in your browser

Frequently asked questions