You can schedule a macOS launchd job for a deprecation date, but StartCalendarInterval is not a built-in “run once” timer. It is a calendar-matching rule. To make the action effectively one-time, define every date field that matters, make the action idempotent, record successful completion, and remove both the plist file and the loaded service in the correct launchd domain.
The design below also accounts for the two timing cases that are often confused: a Mac asleep at the scheduled time normally runs the missed calendar event after wake, while a Mac that is powered off misses that occurrence. Apple documents these behaviors in its archived Scheduling Timed Jobs guide, so do not promise execution at an exact wall-clock instant in every state.
As an Amazon Associate I earn from qualifying purchases.
What “one time” means in launchd
A launchd calendar trigger describes when a date matches a pattern. Apple’s examples use a dictionary containing fields such as Month, Day, Weekday, Hour, and Minute. Any field you omit is a wildcard. A rule containing only day, hour, and minute can therefore match every month; a rule containing month, day, and time can match again in later years unless your program prevents a second effect.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
That makes a reliable deprecation job a small state machine rather than a single plist setting:
- The calendar rule wakes the process when the date pattern matches.
- The process checks whether the deprecation work has already completed.
- If it has not, the process performs the work and writes a durable completion marker only after success.
- The process requests removal of its registered service and removes its plist file when it has the permissions and domain required to do so.
The reviewed Apple material establishes the calendar matching and service-management concepts, but it does not provide a universal, copy-and-paste recipe for a process booting itself out on every current macOS release. Verify the installed man launchctl and man launchd.plist on the target system before relying on a particular self-removal sequence.
Build a calendar rule that cannot accidentally recur
Understand each calendar key
| Key | Meaning | Risk when omitted |
|---|---|---|
Month |
Numeric month for the match | The rule can match in every month. |
Day |
Day of the month | The rule can match on that day number in future months. |
Weekday |
Day of the week | Adding it can broaden the pattern to recurring weekdays; use it only when intended. |
Hour |
Hour of day | Without it, every matching date can trigger at other times. |
Minute |
Minute of the hour | Without it, the rule is less specific and may run at more times than expected. |
For a single known date, specify the month, day, hour, and minute. Do not add Weekday merely for readability: it is another matching condition and can change the schedule if the date and weekday do not agree. If the deprecation is defined by a weekday rather than a date, document that recurring intent and rely on the completion marker to make later matches harmless.
Illustrative plist
This example shows the shape of a user agent. The date and executable are examples; replace them with the values for your event and test the file on the macOS release where it will run.
Free tools Windows power users keep installed
One-click scans. No signup required.
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE plist PUBLIC '-//Apple//DTD PLIST 1.0//EN' 'http://www.apple.com/DTDs/PropertyList-1.0.dtd'>
<plist version='1.0'>
<dict>
<key>Label</key>
<string>com.example.deprecation-action</string>
<key>ProgramArguments</key>
<array>
<string>/usr/local/bin/deprecation-action</string>
</array>
<key>StartCalendarInterval</key>
<dict>
<key>Month</key>
<integer>10</integer>
<key>Day</key>
<integer>31</integer>
<key>Hour</key>
<integer>09</integer>
<key>Minute</key>
<integer>00</integer>
</dict>
</dict>
</plist>Leaving out RunAtLoad keeps its documented default of false. If you set it to true, launchd starts the job as soon as the job is loaded, which can execute the action during installation or troubleshooting rather than on the deprecation date. Apple describes this behavior in the launchd.plist(5) man page.
Make the action safe if launchd matches it again
A calendar pattern can match more than once because of an omitted field, a later year, a reload, or a manual launch. The action itself must therefore be idempotent. A practical sequence is:
- Choose a marker that survives process exits and reboots, such as a file in the user’s application-data directory or another state store appropriate to the job’s privilege level.
- At startup, read the marker. If it says the deprecation completed successfully, exit without repeating the change.
- Perform the deprecation operation in a way that can be safely retried. Do not write the success marker before the operation has actually succeeded.
- Write the marker atomically after success, so a crash cannot leave a partial “completed” state.
- Only then begin cleanup. If cleanup fails, a later match should still see the marker and avoid repeating the deprecation.
Do not use the existence of the plist as your completion record. launchd can have a service loaded while the file is changed or removed, and a failed action could otherwise be mistaken for a completed one.
Sleep, power-off, and exact timing
Apple states that when a calendar-triggered job is missed because the Mac is asleep, the job runs when the computer wakes. A powered-off Mac is different: the scheduled occurrence is missed and launchd waits for the next designated match.
| Mac state at scheduled time | Documented result | Design implication |
|---|---|---|
| Asleep | The missed calendar event runs after wake. | The action may occur later than the nominal time; keep it safe to run after the deadline. |
| Powered off | The occurrence is missed; there is no documented catch-up for that powered-off interval. | Provide a separate recovery path, such as checking the deprecation date at login or on the next launch, if missing the event is unacceptable. |
These statements come from Apple’s archived documentation and should not be read as a guarantee of exact timing on every current macOS release. If the deprecation depends on local wall-clock time, test the target release for time-zone changes and daylight-saving transitions; the cited material does not settle those edge cases.
Clean up the registered service and the plist separately
Removing a plist from disk is a filesystem operation. It does not, by itself, prove that launchd has unloaded the service it already registered. The documented launchctl operation for removing a service from its launchd domain is bootout; see Apple’s launchctl(1) man page.
A self-cleaning job therefore has two distinct cleanup goals:
- Service removal: boot the registered label out of the correct launchd domain.
- File removal: delete the plist from the location where it was installed, if the process has permission.
The exact command line depends on whether the job is a per-user agent or a system daemon, how that domain is addressed on the target release, and which account owns the files. Confirm the syntax and permissions locally instead of copying a command that assumes a different domain.
Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minutePC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Agents and daemons are not interchangeable
Apple distinguishes per-user agents from system daemons in its Creating Launch Daemons and Agents guide. Their plist locations and launchd domains differ. A user agent normally runs with that user’s rights; a system daemon runs in a system context and may require administrative ownership and permissions.
Do not treat sudo as a universal repair. It can change which domain you address, create root-owned files that the original process cannot remove, or encourage edits to Apple-owned system directories. Install your own plist in the supported user or administrator-managed location for the intended context, and make the cleanup account match that context.
Four documented pitfalls to watch for
The following are source-supported hazards, not verified evidence that a particular author personally experienced four incidents.
1. Wildcard recurrence
Every omitted calendar field is a wildcard. A day/hour/minute dictionary can match that time every month, and a month/day/time dictionary can match again in future years. Include all fields needed to identify the intended date, then keep the action idempotent anyway.
Recommended Free Tools
Rank #4
2. Assuming the calendar key means “once”
StartCalendarInterval expresses a match pattern, not a permanent one-shot guarantee. Reloading the job, waking from sleep, or reaching a later matching date can invoke it again. The completion marker and a retry-safe operation are what make repeated invocations harmless.
3. Deleting the plist and assuming launchd forgot the job
Disk state and service state are separate. A loaded service can remain registered after its file is deleted, while a file can exist without being loaded. Use the appropriate bootout operation for the service’s domain, then remove the file if that is part of your cleanup policy. Verify both states rather than inferring one from the other.
4. Ignoring load timing or daemonizing the process
RunAtLoad causes execution when the job loads. Separately, Apple requires a launchd-managed process not to daemonize: do not fork and background the real work so the original process exits while children continue elsewhere. A foreground process lets launchd observe its lifetime and makes success, failure, and cleanup behavior easier to reason about. Apple documents this process constraint in its launchd guidance.
Install, validate, and observe the job
- Choose the agent or daemon context before writing the plist. Confirm the installation directory, owner, and permissions for that context.
- Set a complete calendar pattern for the intended date and leave
RunAtLoadunset unless an immediate run is explicitly part of the design. - Validate the plist syntax with the property-list validation tools available on the target macOS release.
- Load the job using the launchctl command appropriate to its domain, then inspect the registered service and its recent output using the commands provided by that release.
- Test the action independently of the calendar trigger. Confirm that a second invocation sees the completion marker and performs no destructive work.
- Test the cleanup path with a harmless label and temporary plist before the real deprecation event. Confirm service removal and file removal separately.
- Record the target macOS version, account, domain, date, time zone, and expected wake behavior in the runbook. Those details are part of the schedule, not incidental documentation.
Do not use a plist’s Disabled value as proof that a job is currently unloaded. The launchd man-page documentation cautions that this key is not a reliable indication of runtime load state; inspect the service through launchctl instead.
Recovery when the date was missed or the job misfired
If the Mac was off
Run the deprecation tool manually or provide a login-time reconciliation check that compares the current date with the intended deadline. Before acting, consult the same completion marker used by the scheduled run.
If the action ran too early
Check whether RunAtLoad was enabled, whether the plist was reloaded, and whether a calendar field was omitted. Restore from the marker or backup appropriate to the operation, correct the rule, and reload it only after testing.
If cleanup did not finish
Inspect the registered service in the correct domain, then perform the documented bootout operation and remove the plist with the account that owns it. If permissions or domain ownership are unclear, stop rather than applying broad administrative privileges.
Time-zone and daylight-saving qualification
The cited Apple pages do not establish how this exact one-time design behaves across every time-zone or daylight-saving transition on current macOS versions. If the deprecation deadline is expressed in local wall-clock time, test a staging job on the target release around the transition, document the chosen time zone, and provide a manual fallback. For a globally coordinated deadline, consider converting the business rule to a single agreed zone and having the process verify the actual deadline before making the change.
Practical design checklist
- All required calendar fields are present, and any intentional wildcard is documented.
- The action checks a durable completion marker before doing work.
- The marker is written only after successful completion.
- The process remains in the foreground and does not daemonize.
RunAtLoadis omitted or deliberately enabled with its consequences understood.- Sleep and power-off behavior are part of the operating plan.
- The launchd domain, plist location, owner, and permissions are known.
- Service bootout and plist deletion are treated as separate cleanup steps.
- The installed macOS version’s man pages are used to verify launchctl syntax.
- Time-zone and daylight-saving assumptions are tested or explicitly accepted as a risk.
The Bottom Line
A launchd calendar job can perform a deprecation action and clean itself up, but “once” comes from complete date matching, idempotent application logic, and explicit service removal—not from StartCalendarInterval alone. Design for sleep wake-ups, missed powered-off events, domain-specific permissions, and the distinction between deleting a plist and booting out its registered service.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
