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.

  • -d keeps the display from sleeping. Use it for a presentation or anything you need to keep looking at.
  • -i prevents 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.
  • -m keeps the disk from idle sleeping.
  • -s prevents system sleep entirely, but only while the Mac is on AC power. On battery it does nothing, which surprises people on laptops.
  • -u declares that the user is active: it wakes the display if it is off and keeps it from idling. Without -t it lasts only 5 seconds, so it is meant for scripts more than for everyday use.
  • -t sets a timeout in seconds. When it runs out, caffeinate lets go on its own.
  • -w waits 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 -s on battery. It only applies on AC power.
  • You used -i and the screen went dark. That is expected: -i keeps 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:

  • -i always, and -d so the screen stays on too, unless you ask it to turn the screens off when you are away.
  • -t from 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.
  • -w pointed 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

Get Webstarted Toolbox

Keep Awake comes built into Toolbox: free, no account, macOS 12 and later (Intel and Apple silicon) and Windows 10 and later.

Free beta · macOS · Windows (x64) · Signed & notarized · No account required