Taming Mac Sleep from the Terminal: A Practical Guide to caffeinate

By Manny Fernandez

September 21, 2026

Taming Mac Sleep from the Terminal: A Practical Guide to caffeinate

Objective: Show exactly what caffeinate does, which flag to reach for in which situation, and how to verify it is actually working, so you stop guessing and start scripting.

Target audience: macOS sysadmins, security practitioners, and anyone who has watched a long job die because the lid closed.

caffeinate is the built in macOS utility for temporarily overriding sleep behavior from the command line. No daemon to install, no System Settings toggle to remember to flip back. You run it, it holds a power assertion for as long as you need, and it releases that assertion automatically when it exits.

Prerequisites

macOS 10.8 (Mountain Lion) or later. It ships with every modern Mac.
Terminal (or SSH) access.
For the -w flag: the target process’s PID, obtained with pgrep <name> or ps aux | grep <name>.

No installation, no dependencies, no root required for the common cases.

How It Actually Works

caffeinate does not change any system setting. It creates one or more temporary power management assertions through the same IOKit power management framework that apps like Zoom and Keynote use to keep your screen awake during a call or presentation. Each assertion says “don’t do X while I’m running,” and the moment the process exits (naturally, via timeout, or via Ctrl+C), every assertion it was holding disappears with it.

That is the detail that matters operationally: the effect is scoped to the life of the process, not to your session or your machine. Kill the process, and normal sleep behavior returns immediately.

Command Reference

caffeinate [-disu] [-t timeout] [-w pid] [utility [args...]]

Flag	Assertion Created	Notes
`-d`	Prevent display sleep	Screen stays on; system can still idle sleep unless paired with `-i`
`-i`	Prevent system idle sleep	Default behavior if no flag is given
`-m`	Prevent disk idle sleep	Rarely needed on SSD Macs, still valid on external spinning disks
`-s`	Prevent system sleep	AC power only. Silently has no effect on battery
`-u`	Declare user active	Wakes the display if off; defaults to a 5 second assertion unless `-t` is set
`-t seconds`	Sets a timeout	Ignored if a utility is also specified
`-w pid`	Ties the assertion to another process	Assertion ends when that PID exits

If you give caffeinate no flags at all, it behaves as -i. If you give it no flags, no timeout, and no utility, it runs (and holds the assertion) until you Ctrl+C it, so don’t walk away from a bare caffeinate in a terminal you are about to close.

Common Workflows

1. Keep the system awake for a long running job

caffeinate -i ./run_backup.sh

caffeinate wraps the command, holds the -i assertion for exactly as long as run_backup.sh is running, and exits (releasing the assertion) the instant the script finishes. This is the pattern to default to for backups, large file transfers, batch encodes, or any unattended script you kick off and walk away from.

2. Keep the display on for a demo or screen recording

caffeinate -d

Run this in its own terminal tab before a screen share or a recorded walkthrough. Ctrl+C it when you’re done, or pair it with -t so it expires on its own:

caffeinate -d -t 1800

3. Tie the assertion to a process you didn’t start with caffeinate

Useful when the job is already running and you don’t want to kill and restart it:

caffeinate -s -w $(pgrep -x "VPN Client")

This is the flag most guides skip, and it’s the one that matters most in practice: you rarely get to wrap every long job in caffeinate from the start, but you can almost always find its PID after the fact.

4. Prevent full system sleep, not just idle sleep

caffeinate -s

-s is a stronger assertion than -i. It’s the difference between “don’t dim and idle sleep” and “don’t sleep at all, period,” which matters if you have an aggressive pmset sleep timer or Power Nap enabled. Check the AC only caveat below before relying on it for anything unattended.

5. Stack every assertion for a “leave it alone” run

caffeinate -dimsu ./long_scan.sh

Common on a Mac running an overnight vulnerability scan, packet capture, or lab build, where you don’t want the disk, display, idle timer, or system sleep interfering at all.

Verifying It’s Working

Don’t just trust that the flag did something. Confirm the assertion actually exists:

pmset -g assertions

Look for your caffeinate process by PID in the assertion list, next to the assertion type it’s holding (PreventUserIdleSystemSleep, PreventSystemSleep, PreventUserIdleDisplaySleep, and so on). If it’s not listed, the flag you used isn’t doing what you think, or the process already exited.

Activity Monitor’s Energy tab also shows caffeinate under “Preventing Sleep” while it’s active, which is a faster visual check if you’re not living in the terminal.

Troubleshooting and Gotchas

-s silently does nothing on battery. This is the gotcha that catches people. -s only prevents sleep while on AC power; on battery, macOS ignores that specific assertion. If a laptop keeps sleeping despite caffeinate -s, check pmset -g batt first. Pair -s with -i if you need coverage on battery too.

Orphaned background processes. If you background caffeinate with & and forget about it (or close the terminal without nohup), it can keep running and keep your Mac awake indefinitely with nothing obvious pointing back to why. Run pgrep caffeinate periodically on shared or lab Macs, and prefer -t or -w over a bare, untimed caffeinate & in anything scripted.

caffeinate is not pmset. pmset changes persistent, system wide power configuration (pmset -a disablesleep 1) that survives reboots and applies until you explicitly change it back. caffeinate only ever asserts a temporary, process scoped condition that vanishes when the process exits. Reach for caffeinate for anything task scoped; reach for pmset only when you actually want a standing policy change, and remember to revert it.

SSH sessions and disconnects. If you SSH into a Mac and run caffeinate in the foreground, closing the SSH session can take the process with it depending on your shell’s job control. For anything that needs to survive a disconnect, use nohup caffeinate -s -t 7200 & or run it inside tmux or screen.

Root, launchd, and login state contexts. A user space caffeinate process dies when that user logs out. If the assertion needs to survive logout (a LaunchDaemon triggered overnight job, for example), run caffeinate from the daemon context itself, or reconsider whether a pmset schedule is actually the right tool for that specific case.

Quick Reference

Task	Command
Prevent idle sleep for a script	`caffeinate -i ./script.sh`
Keep display on for 30 minutes	`caffeinate -d -t 1800`
Tie to an already running PID	`caffeinate -w <pid>`
Prevent full sleep (AC only)	`caffeinate -s`
Maximum coverage for unattended runs	`caffeinate -dimsu <command>`
Check what’s currently asserted	`pmset -g assertions`

Taming Mac Sleep from the Terminal: A Practical Guide to caffeinate

Prerequisites

How It Actually Works

Command Reference

Common Workflows

1. Keep the system awake for a long running job

2. Keep the display on for a demo or screen recording

3. Tie the assertion to a process you didn’t start with caffeinate

4. Prevent full system sleep, not just idle sleep

5. Stack every assertion for a “leave it alone” run

Verifying It’s Working

Troubleshooting and Gotchas

Quick Reference

Recent posts