Mac OS X crontab FAQ: How do I run a Unix job (or shell script) through the OS X crontab facility? I keep trying to edit my Mac crontab file, but my Mac won't save my crontab changes, or run my program.
As of this writing (updated in 2014), the Mac crontab command seems to be deprecated on Mac OS X, and the Apple documentation encourages you to use their launchd facility. Here's a blurb from Apple's
crontab man page:
Darwin note: Although cron(8) and crontab(5) are officially supported under Darwin, their functionality has been absorbed into launchd(8), which provides a more flexible way of automatically executing commands. See launchctl(1) for more information.
That being said, it looks like you can still use the Mac crontab facility, as implied by this note in the Mac OS X
cron man page:
The cron utility is launched by launchd(8) when it sees the existence of /etc/crontab or files in /usr/lib/cron/tabs. There should be no need to start it manually.
(Follow-up note: I have not been able to get crontab to work under Mac OS X 10.6.)
In this tutorial I'm going with Apple's suggestion and show you how to run your Unix shell scripts and commands with the Mac OS X launchd facility using the
For my purposes, I want to run a shell script every minute to ping my websites. If the sites don't respond, I want to be able to notify myself of the problem, perhaps by displaying a dialog from the Mac OS X Unix shell.
To get this running, I followed the steps shown here.
First, open a Mac Terminal window, then
cd to this directory:
When I dug around in the Apple documentation, I found there are three main directories you can use with
launchd, and that's how I learned about this directory. Here are your three options:
Note that when you use the first two directories shown here, you must use the
sudo command to edit your files.
To keep this simple and just see how things work initially, my advice is to use the $HOME/Library/LaunchAgents folder until you see how things work, then use the other two system folders if/when necessary.
Next, create a Mac plist file in this directory to describe the job you want to run. In my case I fired up vi to edit my file:
Following Apple's documentation (and after many errors), I ended up with these contents in my plist file:
<?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.alvin.crontabtest</string> <key>ProgramArguments</key> <array> <string>/Users/al/bin/crontab-test.sh</string> </array> <key>Nice</key> <integer>1</integer> <key>StartInterval</key> <integer>60</integer> <key>RunAtLoad</key> <true/> <key>StandardErrorPath</key> <string>/tmp/AlTest1.err</string> <key>StandardOutPath</key> <string>/tmp/AlTest1.out</string> </dict> </plist>
This plist file can be read as "Run the script /Users/al/bin/crontab-test.sh every 60 seconds, and redirect the standard output and standard error as shown".
A note about the naming convention: Apple strongly encourages you to use the naming convention I've shown here for (a) your filename and (b) your
label value. When using the commands that I'm about to show you, you'll refer to the filename and this "label", and they encourage you to follow this naming convention to avoid namespace collisions. Having programmed in Java, this is just like the Java package naming convention, and I have no problems following it.
(You'll see other Mac launchd jobs running when you use the
launchctl list command below, and I think after that, you'll agree that naming convention is a good idea.)
Next, it's important to know that your Mac OS X system won't pick up on this change immediately. You have to tell the Mac launchd daemon to load it, using the
launchctl command, like this:
launchctl load com.alvin.crontabtest.plist
In my case, I just had my /Users/al/bin/crontab-test.sh shell script write some output to a file in the /tmp directory so I could debug this process, like this:
date >> /tmp/MyLaunchdTest.out
After issuing the
launchctl load command I started getting output from my
date command. I let it run for several minutes while I checked that everything was working, and then turned it off using this
launchctl unload com.alvin.crontabtest.plist
Next, I tested how this works with Mac OS X system reboots.
In my tests, I found that just the presence of my file in the $HOME/Library/LaunchAgents directory was enough to make Mac OS X load the file and begin running my script every minute. To test this properly, I issued the Mac
launchctl unload command, like this:
launchctl unload com.alvin.crontabtest.plist
and then I rebooted my system.
After logging into my Mac after the reboot and checking my output files, I found that my plist script had begun executing every minute.
It's important to note that after a reboot you have to use a slightly different
unload command than what I showed earlier. In my previous example you didn't need to include the full path to your plist file, but now that the system has started your job for you, you need to unload it by specifically the full path to the file, like this:
launchctl unload /Users/Al/Library/LaunchAgents/com.alvin.crontabtest.plist
It's also very important to note that if you placed your Mac plist file in one of the two system directories (/Library/LaunchDaemons, /Library/LaunchAgents), your job will be running as the root user after a system reboot. This means a couple of things:
First, output files created by your script will be owned by the root user.
Second, you'll need to use
sudo before any of your
launchctl commands, as shown here:
sudo launchctl list | grep 'alvin'
If you issue that
launchctl command like this, without
launchctl list | grep 'alvin'
you'll never see that your job is running, even though it is. (Because it's owned by root, you're not allowed to see it.)
I used the following Mac OS X launchd, launchctl, and plist resources while researching this tutorial:
In summary, the Mac OS X launchd facility appears to be a replacement for the standard Unix cron/crontab facility. I believe you can enable crontab to work on Mac OS X, and I'll show how to do that in a future tutorial. In the meantime, the Mac OS X launchd/launchctl facility seems to be the future for launching startup jobs, and other jobs we have traditionally run through the cron facility. As such, if you're going to be working a lot on Mac OS X systems, it behooves you to learn about this new approach.