DEV Community

Arjun Adhikari
Arjun Adhikari

Posted on

Cron Not Working on Mac? How to Fix the macOS Sleep Trap with launchd

#automation #productivity #systems #tutorial

If you've ever built an automated script like a Python crypto price scraper, a daily backup script, or an RSS archiver, you probably felt like a genius right up until the moment it failed to run.

You set up your crontab perfectly. You told it to run every day at 6:30 PM. You tested the script in your terminal, and it worked flawlessly. But then you check your logs a few days later, and... crickets. Nothing happened.

What gives?

If you are running your automation on a personal Mac, you've just run into the classic Sleep Mode Trap.

Why Your Mac is Ignoring Your Cron Jobs

cron is a legendary piece of software. It has been the backbone of Unix automation for decades. But cron was designed for servers that live in cold, dark rooms and literally never go to sleep.

Your Mac is different. When you close the lid or walk away for an hour, your Mac goes to sleep to save battery.

Here is how cron handles sleep: It doesn't.

If you have a job scheduled for 6:30 PM and your laptop is asleep at 6:30 PM, cron simply shrugs and skips it. It won't try again until tomorrow at 6:30 PM. If your laptop is closed tomorrow at 6:30 PM too? Skipped again. Your "automated" pipeline is now completely broken unless you babysit it and keep your screen awake.

Apple knew this was a problem, which is why they built launchd.

launchd is the modern, macOS-native replacement for cron and init. It manages everything running in the background on your Mac. Unlike cron, launchd is generally much better at handling sleep/wake scenarios — it can run missed scheduled jobs shortly after wake, depending on your exact power state and configuration.

Cron vs. launchd at a Glance

Feature cron launchd
Handles sleep well ❌ ✅
Native macOS support ❌ ✅
Simple syntax ✅ ❌
Good for servers ✅ ✅
Good for personal laptops ❌ ✅

LaunchAgents vs. LaunchDaemons: What's the Difference?

Before writing your configuration, it's crucial to know where to put it. launchd separates jobs into two categories:

  1. LaunchDaemons (/Library/LaunchDaemons/) — Run as the root system user as soon as the Mac boots, even before anyone logs in. Use this for system-level services like database servers or network listeners.
  2. LaunchAgents (~/Library/LaunchAgents/) — Run as your specific user account, only after you log in. Since personal scripts need access to your files, home directory, and user permissions, LaunchAgents are almost always what you want.

How launchd Actually Works Under the Hood

launchd is the absolute core of macOS. When you turn on your Mac, launchd is the very first process that starts — it has Process ID 1. Every other application on your Mac is technically a "child" of launchd.

When your Mac sleeps, the hardware clock keeps ticking. When you open your laptop, the Kernel updates the system time and launchd checks its internal schedule. If it missed a StartCalendarInterval job during the sleep window, it triggers the job shortly after wake to catch up.

Step-by-Step: Migrating from Cron to launchd

Instead of editing a crontab, you create a Property List (.plist) XML configuration file and drop it in ~/Library/LaunchAgents/.

Here is a complete, production-ready template for a Python script that runs Monday through Friday at 6:30 PM.

File: ~/Library/LaunchAgents/com.yourname.dailyscript.plist

<?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>

    <!-- 1. Unique identifier for this job -->
    <key>Label</key>
    <string>com.yourname.dailyscript</string>

    <!-- 2. Command to run — always use absolute paths for the interpreter AND the script -->
    <key>ProgramArguments</key>
    <array>
        <string>/usr/bin/python3</string>
        <string>/Users/yourname/projects/my_script.py</string>
    </array>

    <!-- 3. Working directory — prevents "file not found" errors inside your script -->
    <key>WorkingDirectory</key>
    <string>/Users/yourname/projects</string>

    <!-- 4. Environment variables — launchd starts with a minimal PATH, so declare it explicitly -->
    <key>EnvironmentVariables</key>
    <dict>
        <key>PATH</key>
        <string>/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin</string>
    </dict>

    <!-- 5. Schedule: Monday (1) through Friday (5) at 18:30 -->
    <key>StartCalendarInterval</key>
    <array>
        <dict>
            <key>Weekday</key><integer>1</integer>
            <key>Hour</key><integer>18</integer>
            <key>Minute</key><integer>30</integer>
        </dict>
        <dict>
            <key>Weekday</key><integer>2</integer>
            <key>Hour</key><integer>18</integer>
            <key>Minute</key><integer>30</integer>
        </dict>
        <dict>
            <key>Weekday</key><integer>3</integer>
            <key>Hour</key><integer>18</integer>
            <key>Minute</key><integer>30</integer>
        </dict>
        <dict>
            <key>Weekday</key><integer>4</integer>
            <key>Hour</key><integer>18</integer>
            <key>Minute</key><integer>30</integer>
        </dict>
        <dict>
            <key>Weekday</key><integer>5</integer>
            <key>Hour</key><integer>18</integer>
            <key>Minute</key><integer>30</integer>
        </dict>
    </array>

    <!-- 6. Persistent log files — use ~/Library/Logs, NOT /tmp (which gets wiped by macOS) -->
    <key>StandardOutPath</key>
    <string>/Users/yourname/Library/Logs/dailyscript.out</string>
    <key>StandardErrorPath</key>
    <string>/Users/yourname/Library/Logs/dailyscript.err</string>

</dict>
</plist>
Enter fullscreen mode Exit fullscreen mode

Understanding the Key Fields

Key What it does
Label Unique name used to identify and manage the job
ProgramArguments Exact command and arguments — equivalent to typing in your terminal
WorkingDirectory Sets the pwd inside your script; prevents relative path failures
EnvironmentVariables Injects env vars — critical because launchd starts with a barebones $PATH
StartCalendarInterval Defines the schedule; 0 and 7 are both Sunday
StandardOutPath Where print() and stdout output goes
StandardErrorPath Where errors and tracebacks go

Why ~/Library/Logs/ instead of /tmp/?
macOS periodically cleans /tmp/ — sometimes as frequently as on every reboot. If you put your logs there, you could lose them before you ever read them. ~/Library/Logs/ is the macOS convention for persistent, user-level logs.

Activating the Job (The Modern Way)

Historically, most tutorials teach launchctl load, but Apple considers this legacy. The modern, recommended way to register a LaunchAgent for your user session is:

# Register the job
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.yourname.dailyscript.plist

# To test it immediately without waiting for the scheduled time
launchctl start com.yourname.dailyscript

# If you edit the plist, you must unload and reload it
launchctl bootout gui/$(id -u) ~/Library/LaunchAgents/com.yourname.dailyscript.plist
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.yourname.dailyscript.plist
Enter fullscreen mode Exit fullscreen mode

Common launchd Gotchas

If your script isn't running, it is almost certainly one of these:

  1. Barebones $PATH — launchd starts with a minimal environment. If your script calls python, node, or any Homebrew tool by name without a full path, it will silently fail. Always declare your PATH explicitly in EnvironmentVariables, and on Apple Silicon Macs include /opt/homebrew/bin.

  2. Absolute paths everywhere — launchd does not expand ~. Use /Users/yourname/ literally everywhere — in ProgramArguments, WorkingDirectory, and log paths.

  3. Scripts fail silently — There is no terminal window to show you errors. Always check your log files after the first run:

    cat ~/Library/Logs/dailyscript.err

  4. Verify the job is registered:

    launchctl list | grep com.yourname.dailyscript

    The three columns are: PID (blank if not running), last exit code (0 = success), and label.

  5. Stream live system logs for deeper debugging:

    log stream --predicate 'subsystem == "com.apple.launchd"'

A Quick Note on KeepAlive

As you explore launchd further, you will encounter <key>KeepAlive</key>. Setting it to <true/> tells launchd to treat your script as a permanent background daemon — if it crashes or exits, launchd will immediately restart it. This is exactly what you want for a persistent web server, but completely wrong for a daily scraper that is supposed to run once and exit.

What About Windows?

Windows has its own built-in equivalent: Task Scheduler.

To enable the same "catch-up on wake" behavior:

  1. Open Task Scheduler and create a new task.
  2. Set your trigger (daily, weekly, etc.).
  3. Go to the Settings tab.
  4. Check "Run task as soon as possible after a scheduled start is missed".

That single checkbox gives you the same sleep-safe behavior as launchd's StartCalendarInterval. Windows also supports environment variables and working directory settings under the task's Actions configuration.

Final Thoughts

cron is a classic for a reason — simple, powerful, and universal. But it was built for servers that never sleep. If you are building personal automation on a laptop, you owe it to yourself to use the scheduler your OS was actually designed around.

Your data (and your sanity) will thank you.

Top comments (0)