Writing .timer units

Mental model

A timer is an alarm clock that starts another unit. The timer never runs anything itself. When it elapses, systemd starts foo.service, exactly as if you had run systemctl --user start foo.service.

The two-file skeleton

Name the timer and the service the same apart from the suffix, and backup.timer will start backup.service without extra configuration. Use Unit= only when the names must differ. Templates also work: sync@work.timer starts sync@work.service.

Recipes

Each recipe shows only the [Timer] section, or the files that differ from the skeleton.

The timer fires once. Afterwards it stays loaded with no next elapse, because RemainAfterElapse= defaults to yes. AccuracySec=1s overrides the default one-minute window, described in the gotchas. Persistent= only catches up on runs that fell due after you enabled the timer. If you enable a timer whose date is already in the past, it never runs.

For a one-off reminder, you usually don't need files. A transient timer is simpler, though it disappears when your user manager stops:

Avoid OnCalendar=daily on a laptop. It means midnight, when the lid is usually closed. With Persistent=true it still runs, but at an unpredictable time: whenever you next log in. Pick a time you are actually at the machine. To pin the time to a timezone other than the system one, append the zone: OnCalendar=*-*-* 07:30 Europe/Paris.

"Every 6 hours" can mean two different things, and they need different directives.

Aligned to the clock: at 00:00, 06:00, 12:00 and 18:00

DeferReactivation=v257 matters when a run can take longer than the interval. Without it, the missed slot fires again as soon as the long run finishes. With it, the timer waits for the next scheduled slot. It only works with OnCalendar=.

A repetition value restarts at each larger unit, so it must divide the range evenly. *:0/7 fires at :00, :07 … :56 and then :00 again, leaving a 4-minute gap. For a 90-minute rhythm, combine two expressions: OnCalendar=*-*-* 00/3:00 and OnCalendar=*-*-* 01/3:30.

Relative to the last run: 6 hours after the previous run started

OnUnitActiveSec= needs a starter such as OnStartupSec= or OnActiveSec=. On its own it waits for a previous run that never happened. This style drifts, and it counts only awake time, as the diagram at the top shows. Persistent= has no effect on it. Use it for "not too often" jobs where the exact time doesn't matter. If a run can outlast the interval, use OnUnitInactiveSec=6h instead. It counts from the end of the previous run, so runs never follow each other back to back.

For a user timer, OnStartupSec= counts from the moment your user manager started, which is your first login. OnBootSec= counts from kernel boot. If you log in an hour after booting, a 3-minute OnBootSec= timer is already overdue and fires the moment you log in. With lingering enabled, the user manager starts at boot, and the two become nearly the same. A logout followed by a new login doesn't restart the manager while other sessions or lingering keep it alive, so this recipe fires once per manager start, not once per login.

To make the timer count from a target, have the target start the timer, then use OnActiveSec=, which counts from the timer's own start.

systemctl --user enable notes-sync.timer now links the timer into graphical-session.target.wants/ instead of timers.target.wants/. Each time the desktop session starts, the timer starts too, and it fires 10 minutes later. PartOf= stops the timer when the session ends. That resets it, so the next session gets its own 10-minute countdown. Without PartOf=, the timer would stay active with nothing left to trigger, and the next session wouldn't re-arm it.

The same shape works for any user target the manager actually reaches, such as default.target or xdg-desktop-autostart.target, or a target of your own (see below).

This builds on the previous recipe with a real schedule. The timer ticks only while the target is up. The service also refuses to run outside the target, in case something else starts it, and gets stopped if the target goes away mid-run.

Requisite= means the target must already be active, or this unit fails at once. Wants= would try to start the target, and graphical-session.target refuses manual starts anyway. Adding Persistent=true to the timer makes the next session catch up on a slot it missed.

A custom user target works as a switch: timers attached to it run only while it is on. Targets don't stop on their own, so the switch stays in whatever position you set.

This is the man page's own example. With RandomizedDelaySec=5d, the delay starts again at every boot or login. A laptop that never stays up for 4 days in a row would then never run the job. RandomizedOffsetSec= doesn't have this problem. To spread runs out, set AccuracySec=1us alongside a randomized delay, because accuracy coalescing pulls runs back together.

Your user manager is a separate instance from the system manager. User units can't use Wants= or After= with system units, so network-online.target, time-sync.target and sleep.target don't exist from a user unit's point of view. You have two options.

Wait inside the user service. The timer fires on schedule and the service waits up to a limit before giving up. This is good enough for a laptop:

Make it a system timer that runs as you. This option gets real ordering, lets the timer wake the machine with WakeSystem=, and runs whether or not you're logged in:

OnCalendar= syntax

The full form is DayOfWeek Year-Month-Day Hour:Minute:Second Timezone, and every part is optional. A missing date means every day (*-*-*), a missing time means 00:00:00, and missing seconds mean :00. Within each field, , separates a list, .. gives a range, /N repeats every N, * matches anything, and ~ counts days back from the end of the month. The full grammar is in systemd.time(7).

A bare number means seconds. Units can be combined, as in OnBootSec=1h 30min. The available units are us, ms, s, min (also m), h, d, w, M (a month, 30.44 days) and y. Be careful with case: m means minutes and M means months. Write min to avoid mistakes, and check with systemd-analyze timespan '90m'.

Targets you can hook

These are the targets inside your user manager. A timer can use WantedBy= and PartOf= with any of them. The authoritative list is in systemd.special(7).

System targets for system timers include multi-user.target, graphical.target, network-online.target, time-sync.target and sleep.target. System timers that use OnCalendar= are ordered after time-set.target and time-sync.target automatically, so a machine without a battery-backed clock doesn't fire them at a wrong 1970 time.

Gotchas

Each entry is listed by the symptom you'd notice. Open one to see the cause and the fix.

Inspect and debug

When a timer starts a service, systemd passes it environment variables, including $TRIGGER_UNIT, $TRIGGER_TIMER_REALTIME_USEC and $TRIGGER_TIMER_MONOTONIC_USEC. A script can check them to tell a scheduled run from a manual systemctl start. The details are in systemd.exec(5).