Schedule Auto-Updates

Create a macOS launchd agent to run Homebrew updates on a recurring schedule.

📄 setup-auto-update.sh 🛡 Scheduling 💻 macOS 12.0+
Download Script View on GitHub

What This Script Does

The setup-auto-update.sh script automates the process of creating a macOS LaunchAgent that runs the basic auto-update script on a schedule you define. Instead of remembering to run Homebrew updates manually, this script sets up the system so updates happen automatically in the background at a time that works for you. It is the recommended way to ensure your Homebrew packages stay current without any ongoing effort on your part.

macOS uses a system called launchd for managing background tasks, scheduled jobs, and system services. Launchd is similar to cron on Linux, but it is more tightly integrated with macOS and supports features like running missed jobs when the system wakes from sleep. The setup script generates a properly formatted launchd plist (property list) file and installs it as a user-level LaunchAgent, which means it runs under your user account and does not require root privileges.

When you run this script, it prompts you to choose your preferred update schedule. You can select from several common options, including daily, weekly, or on a specific day of the week. You also choose the time of day for the update to run. Most users find that scheduling updates for early morning or late evening works well, since Homebrew operations can temporarily increase CPU usage and you want the update to finish before you need your Mac for intensive work.

The script generates a plist XML file that contains your schedule preferences, the path to the auto-update script, and metadata that launchd uses to manage the job. It writes this file to the standard LaunchAgents directory at ~/Library/LaunchAgents/, using a reverse-domain naming convention that makes the agent easy to identify. After writing the file, the script loads it into launchd using the launchctl command, which activates the schedule immediately.

One of the advantages of launchd over simple cron jobs is its handling of missed executions. If your Mac is asleep or powered off when a scheduled update is supposed to run, launchd remembers the missed execution and runs the job the next time your Mac wakes up or starts. This ensures that your packages do not go weeks without updates just because your Mac happened to be off at the scheduled time. The plist file includes configuration to enable this catch-up behavior.

If you have previously set up a scheduled update and want to change the schedule, simply run this script again. It detects the existing plist file, unloads the current schedule from launchd, generates a new plist with your updated preferences, and loads the new schedule. This makes it easy to adjust your update frequency as your needs change over time, without needing to manually edit XML files or run launchctl commands yourself.

After setup is complete, the script shows you a confirmation message with the details of the schedule it created. It also tells you how to verify that the agent is loaded, how to manually trigger it for testing, and how to unload it if you ever want to stop automatic updates. All of these commands are standard launchctl operations that any macOS user can run from Terminal.

Usage

Run this script once to set up the scheduled task. You do not need to run it again unless you want to change the schedule.

# Set up the scheduled auto-update agent
./setup-auto-update.sh

After the agent is installed, you can verify it is running and manage it with these commands:

# Verify the agent is loaded
launchctl list | grep brewscripts

# Manually trigger an update right now (for testing)
launchctl start com.brewscripts.autoupdate

# Unload the agent (stop scheduled updates)
launchctl unload ~/Library/LaunchAgents/com.brewscripts.autoupdate.plist

# Reload the agent (resume scheduled updates)
launchctl load ~/Library/LaunchAgents/com.brewscripts.autoupdate.plist

What Gets Changed

  • LaunchAgent plist — A new file is created at ~/Library/LaunchAgents/com.brewscripts.autoupdate.plist. This XML file contains the schedule configuration and the path to the auto-update script that launchd will execute.
  • launchd registration — The newly created plist is loaded into launchd via launchctl load, which activates the schedule immediately. The agent persists across restarts and login sessions.

This script does not modify any Homebrew packages, system files, or application configurations. It only creates and registers the scheduled task. The actual update work is performed by auto-update-brew.sh when launchd triggers it at the scheduled time.

Related Scripts

  • Schedule Hybrid Updates — The equivalent scheduling script for the hybrid (email + text) auto-update script. Choose this if you want both email reports and text message alerts.
  • Auto-Update (Basic) — The auto-update script that this scheduling agent triggers. Read its documentation to understand exactly what happens during each scheduled update run.