How to Use Launchd to Schedule Run Scripts on Mac

This guide explains how to use Launchd to schedule and run scripts on Mac. Learn to create plist files, load tasks, and automate workflows using Terminal commands.

Bertie Atkinson

Launchd is a powerful service management framework in macOS that allows you to automate tasks by scheduling scripts to run at specific intervals or events. Unlike cron, which is commonly used in Unix-based systems, Launchd offers more flexibility and integration with macOS.

Understanding Launchd and Its Components

Launchd operates using property list (plist) files, which are XML-based configuration files. These files define how and when a task should be executed. There are two types of Launchd plist files: User Agents and System Agents. User Agents run under your user account, while System Agents run under the system’s root account.

Each plist file contains key-value pairs that specify the script to run, the schedule, and other parameters. Common keys include Label, ProgramArguments, and StartInterval. Understanding these components is essential for configuring Launchd effectively.

Creating a Launchd Plist File

To create a Launchd plist file, follow these steps:

  • Open Terminal and navigate to the ~/Library/LaunchAgents directory for user-specific tasks or /Library/LaunchDaemons for system-wide tasks.
  • Create a new plist file using a text editor like nano or vim. For example, nano com.example.myscript.plist.
  • Add the necessary key-value pairs to define your task. Below is an example configuration:
<?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.myscript</string>
    <key>ProgramArguments</key>
    <array>
        <string>/path/to/your/script.sh</string>
    </array>
    <key>StartInterval</key>
    <integer>3600</integer>
</dict>
</plist>

Save the file and exit the text editor.

Loading and Managing Launchd Tasks

Once your plist file is created, you need to load it into Launchd. Use the following Terminal commands:

  • To load the task: launchctl load ~/Library/LaunchAgents/com.example.myscript.plist.
  • To unload the task: launchctl unload ~/Library/LaunchAgents/com.example.myscript.plist.
  • To check the status of your task: launchctl list | grep com.example.myscript.

If you make changes to the plist file, unload and reload the task to apply the updates.

Scheduling Tasks with StartInterval and StartCalendarInterval

Launchd provides two primary methods for scheduling tasks: StartInterval and StartCalendarInterval. StartInterval specifies the time interval in seconds between task executions. For example, setting StartInterval to 3600 runs the task every hour.

StartCalendarInterval allows you to schedule tasks based on calendar events, such as specific days or times. Below is an example configuration:

<key>StartCalendarInterval</key>
<dict>
    <key>Hour</key>
    <integer>10</integer>
    <key>Minute</key>
    <integer>30</integer>
</dict>

This configuration runs the task every day at 10:30 AM.

Debugging and Troubleshooting

If your script fails to run, check the system logs for errors. Use the following command in Terminal: log show --predicate 'process == "launchd"' --info --last 1h. This displays Launchd-related logs from the past hour.

Ensure your script has executable permissions by running chmod +x /path/to/your/script.sh. Additionally, verify that the paths in your plist file are correct.

Advanced Configuration Options

Launchd supports advanced configurations, such as running tasks only when the system is idle or when specific files are modified. Use keys like RunAtLoad, WatchPaths, and QueueDirectories to customize your tasks further.

For example, WatchPaths monitors specified files or directories and triggers the task when changes are detected. This is useful for automating backups or syncing tasks.

Share This Article