The caffeinate command on Mac: every flag, with examples
How to keep a Mac awake from Terminal with caffeinate: what -d, -i, -m, -s, -u, -t and -w do, examples to copy, and why your Mac may still fall asleep.
What caffeinate does
caffeinate is a command that ships with every Mac. It creates what macOS calls
power assertions: requests that tell the system not to sleep for now. Open Terminal, type
it, and the Mac stays awake for as long as the command keeps running.
caffeinate With no flags it prevents idle sleep, and it keeps doing so until you stop it: press Control-C in that Terminal window, or close the window. Nothing is changed in your settings, so there is nothing to undo afterwards. The moment caffeinate exits, the Mac goes back to its normal sleep rules.
The flags, one by one
Each flag chooses which kind of sleep to hold off. You can combine them.
-
-dkeeps the display from sleeping. Use it for a presentation or anything you need to keep looking at. -
-iprevents idle sleep of the system. The display can still turn off, but downloads, renders and scripts keep going. This is the default when you pass no flag. -mkeeps the disk from idle sleeping.-
-sprevents system sleep entirely, but only while the Mac is on AC power. On battery it does nothing, which surprises people on laptops. -
-udeclares that the user is active: it wakes the display if it is off and keeps it from idling. Without-tit lasts only 5 seconds, so it is meant for scripts more than for everyday use. -
-tsets a timeout in seconds. When it runs out, caffeinate lets go on its own. -
-wwaits for a process ID to exit and then releases the assertion.
Examples you can copy
Keep the Mac awake for one hour (3,600 seconds), then let it sleep normally:
caffeinate -i -t 3600 Keep the display on too, for two hours:
caffeinate -d -i -t 7200
Stay awake while a command runs. Put the command after caffeinate and the assertion lasts
exactly as long as it does. Here it is make, but it can be a backup script, an
rsync or a long test suite:
caffeinate -i make
Stay awake until an app or process that is already running finishes. Find its process ID
(in Activity Monitor, or with pgrep) and hand it to -w:
pgrep -x ffmpeg
caffeinate -i -w 48213
Two details from the manual: when you run a command after caffeinate, -t is not
used, and -w is ignored. The command itself decides how long it lasts.
Why your Mac still went to sleep
A few situations where caffeinate is running and the Mac sleeps anyway, or seems to:
- You closed the lid. Closing a MacBook puts it to sleep, and caffeinate does not stop that. The exception is closed-display mode: with an external display connected, the Mac plugged in, and an external keyboard and mouse, macOS keeps running with the lid closed (Apple describes the setup here). That is macOS behavior, not something caffeinate turns on.
- You used
-son battery. It only applies on AC power. - You used
-iand the screen went dark. That is expected:-ikeeps the system awake, not the display. Add-d. - The Terminal window is gone. Closing it ends caffeinate.
To see what is holding your Mac awake right now (or what is not), ask the power manager:
pmset -g assertions It prints a summary of every active assertion and which process owns it. With caffeinate running you will see it listed, next to whatever else is keeping the Mac up: a video call, a download, an app that forgot to let go. It is also the quickest way to find out why a Mac will not sleep.
When a menu bar toggle is the better tool
caffeinate is great inside scripts, and caffeinate -i make is hard to beat when
the thing you are waiting for is a command. For the everyday case (a long download, a backup,
a call, a slide deck) the friction is everything around it: a Terminal window you cannot close,
seconds to work out, and no way to glance at whether it is still on.
That is why we built Keep Awake, a widget inside
Webstarted Toolbox, our free menu bar app. Full disclosure: it is ours.
On the Mac it is not a different mechanism. It runs the same caffeinate, with the
flags from this page already chosen:
-
-ialways, and-dso the screen stays on too, unless you ask it to turn the screens off when you are away. -
-tfrom the length you pick: shortcuts in minutes and in hours, a custom amount, or until turned off. It shows the time left and turns itself off at the end. -
-wpointed at Toolbox itself, so if the app quits or crashes, caffeinate exits with it and your Mac never stays awake by accident.
It also runs on Windows, where there is no caffeinate, using the system’s own power call instead. If you live in Terminal and only need it in scripts, keep using caffeinate; it is the right tool there. If you just want the Mac to stay up for the next two hours, one click is nicer than a command.
More menu bar tools that work this way are in our list of free menu bar apps. If you are weighing the menu bar apps that keep a Mac awake, we compared them in Amphetamine alternatives, and if you want the screen off while the Mac keeps working, see how to turn off the screen without sleep.
Sources
- caffeinate man page and pmset man page (SS64).
- If your external display is dark or low resolution (Apple Support), for closed-lid use.