# Enter launchd: The macOS Native Alternative to Cron

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.

* * *

## Enter `launchd`: The macOS Native Alternative to Cron

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

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

> \[!TIP\] **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:

```bash
# 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
```

* * *

## 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:
    
    ```bash
    cat ~/Library/Logs/dailyscript.err
    ```
    
4.  **Verify the job is registered**:
    
    ```bash
    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:
    
    ```bash
    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, it is 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.