How do I use the caffeinate command on a Mac?

What does the caffeinate command do?

The caffeinate command creates power assertions that change how macOS sleeps, then holds those assertions until caffeinate exits, a timeout ends, or a wrapped utility finishes (man caffeinate on macOS). The binary is /usr/bin/caffeinate. Apple’s Mac User Guide also names caffeinate as the command-line way to keep a headless Mac awake.

If you pass no assertion flags, caffeinate creates an assertion that prevents idle sleep. If you pass a utility, caffeinate creates the assertions on that utility’s behalf and keeps them for the life of the utility. Otherwise it creates the assertions itself and keeps them until the caffeinate process exits.

man pmset on macOS says processes can override power-management settings with I/O Kit power assertions, and that pmset -g assertions lists those processes. That is the mechanism caffeinate uses, and the way you check it. For other ways to keep a Mac awake, including System Settings, see how to keep a Mac awake.

What does each caffeinate flag do?

The caffeinate flags choose an assertion type, set a timeout, or wait for a process to exit. The meanings below come from man caffeinate on macOS. The assertion names are the strings pmset -g assertions printed while each flag was running.

Flag	Assertion it creates	What it prevents	Notes
(none)	PreventUserIdleSystemSleep	Idle system sleep	Default when you omit -d, -i, -m, -s, and -u.
-d	PreventUserIdleDisplaySleep	Idle display sleep	Also prevents idle system sleep while the display hold applies, without creating a separate idle-system assertion.
-i	PreventUserIdleSystemSleep	Idle system sleep	Same assertion type as the default.
-m	PreventDiskIdle	Disk idle sleep	Matches the man page line “prevent the disk from idle sleeping.”
-s	PreventSystemSleep	System sleep	Valid only while the Mac is on AC power.
-u	UserIsActive	Display idle sleep	Turns the display on if it is off. Without -t, the timeout is 5 seconds.
-t	(timeout, not an assertion type)	Drops the assertion after N seconds	Unused when you also pass a utility.
-w	(wait, not an assertion type)	Releases the assertion when that pid exits	Ignored when you also pass a utility.

The synopsis groups the assertion switches as [-disu], so you can combine them. caffeinate -di creates both the display assertion and the idle-system assertion. pmset -g assertions then shows both PreventUserIdleDisplaySleep and PreventUserIdleSystemSleep under the caffeinate pid.

-t and -w do not pick an assertion type. They only bound an assertion you already created, or the default idle-sleep assertion if you created none.

How to keep a Mac awake for a set time with caffeinate -t

caffeinate -t takes a timeout in seconds and drops the assertion after that many seconds (man caffeinate on macOS). Multiply minutes by 60, or hours by 3600.

How long	Seconds	Command
1 minute	60	caffeinate -t 60
15 minutes	900	caffeinate -t 900
1 hour	3600	caffeinate -t 3600
2 hours	7200	caffeinate -t 7200
8 hours	28800	caffeinate -t 28800

caffeinate -t 3600

That command uses the default idle-sleep assertion, then drops it after 3600 seconds. Add -d if the display also needs to stay on:

caffeinate -di -t 7200

Do not put a utility after -t if you want the timer. The man page says the timeout value is not used when a utility is invoked. caffeinate -t 3600 make holds assertions for as long as make runs, not for one hour.

-u is the odd case. If you omit -t, man caffeinate on macOS gives -u a 5 second timeout. caffeinate -u -t 60 holds the UserIsActive assertion for 60 seconds instead.

How to keep a Mac awake until a command finishes

Run caffeinate -i before a utility to prevent idle system sleep until that utility finishes, or use caffeinate -w with an existing process ID. man caffeinate on macOS describes both: pass the utility as arguments, or pass -w and a pid.

The man page example is caffeinate -i make. caffeinate forks, execs make in the child, and holds an assertion that prevents idle sleep for as long as that process runs.

caffeinate -i make

Pass the utility you normally use and its arguments. For example, if your job uses python:

caffeinate -i python long_job.py

When a utility is present, -t is ignored and -w is ignored. The assertion lasts for the utility, not for a clock and not for some other pid.

If the job is already running, use -w with that process ID. Once the process exits, caffeinate releases the assertion.

caffeinate -w 12345

pgrep prints matching process IDs (man pgrep on macOS). -n keeps only the newest match, which matters because -w takes one pid:

pgrep -l -x make
# Check the matching job, then replace 12345 with its process ID.
caffeinate -w 12345

The PID 12345 is only an example. pgrep -l -x make lists exact process-name matches with their IDs, so you can select the intended build. Feed one PID to -w; the newest match may be a different build, and an empty match is not a usable PID.

For long agent runs, wrapping the CLI is the same pattern. Keep a Mac awake while coding agents run covers when a wrapper is enough and when a menu-bar hold is easier.

When to use caffeinate -d versus caffeinate -i

Use caffeinate -d to prevent idle display sleep, or caffeinate -i to prevent idle system sleep while allowing the display to turn off. Those are different assertions (man caffeinate on macOS; pmset -g assertions names them PreventUserIdleDisplaySleep and PreventUserIdleSystemSleep).

Run -i (or bare caffeinate) when the Mac should stay awake and the display may turn off. That is the setup Apple names for a headless Mac that still needs to stay up.

Run -d when the screen itself must stay on. pmset -g assertions for a -d-only process showed PreventUserIdleDisplaySleep and did not add PreventUserIdleSystemSleep. Apple’s IOPMLib.h says the display hold also prevents idle system sleep while it applies. To request both named assertion types explicitly, pass both:

caffeinate -di

The -u flag declares user activity for a short hold. It declares that the user is active, turns the display on if it is off, and prevents display idle sleep. Without -t, the assertion lasts 5 seconds; use an explicit timeout for a longer hold.

Does caffeinate -s work on battery power?

caffeinate -s creates an assertion that prevents the system from sleeping, and man caffeinate on macOS states that this assertion is valid only when the system is running on AC power.

On a Mac drawing from AC power, pmset -g assertions listed that assertion as PreventSystemSleep. pmset -g batt is the check for the current source (man pmset on macOS).

The manual documents -i for idle system sleep and limits -s to AC power. A live check here showed PreventSystemSleep for -s, but Apple’s IOPMLib.h marks that assertion type as deprecated. Use -i for ordinary idle-sleep prevention.

Neither flag promises protection against forced sleep, such as closing the lid.

How to stop caffeinate

Stop a foreground caffeinate command with Control-C in its Terminal window; stopping caffeinate releases its assertions (man caffeinate on macOS). Apple’s Terminal User Guide says to click the window that is running the command and press Control-C, which sends a signal that causes most commands to terminate.

If caffeinate is not in the foreground, find the pid and send the default TERM signal. man kill on macOS says kill sends TERM unless you name another signal.

pgrep -l caffeinate
kill 12345

pgrep -l prints the pid and the name (man pgrep on macOS). After kill, run pmset -g assertions again. The caffeinate command-line tool lines for that pid should be gone.

A caffeinate hold ends if a hangup terminates its process. nohup invokes a utility and ignores SIGHUP (man nohup on macOS). Backgrounding with & alone does not ignore hangups. If you need caffeinate to survive a hangup, start it under nohup:

nohup caffeinate -i -t 7200 >/tmp/caffeinate.out 2>&1 &

How to confirm caffeinate is working

pmset -g assertions prints a summary of power assertions, which may prevent system sleep or display sleep (man pmset on macOS; available on Mac OS X 10.6 and later). While caffeinate is running, look for a pid named caffeinate, the assertion type from the flag table, and the name caffeinate command-line tool.

pmset -g assertions

A live caffeinate line looks like this shape:

pid 12345(caffeinate): PreventUserIdleSystemSleep named: "caffeinate command-line tool"

Details can add caffeinate asserting forever, caffeinate asserting for N secs, or caffeinate asserting on behalf of a utility. The localized line is THE CAFFEINATE TOOL IS PREVENTING SLEEP.

If those lines are missing, caffeinate is not holding an assertion. What is keeping a Mac awake walks through the rest of the pmset -g assertions output, including holds created by other apps.

What are the limits of caffeinate?

The caffeinate command cannot prevent forced system sleep and holds assertions only while its process is alive. Its manual documents no menu bar countdown or configurable heat or battery stop.

Use pmset -g assertions to inspect a hold. A timeout, utility exit, or process termination ends the relevant assertion. For a background session that needs to ignore hangups, use the nohup example above; backgrounding alone does not provide that protection.

The man page also does not describe a stop for heat or low battery. Apple’s I/O Kit Power Management notes add a harder limit: power assertions cannot prevent forced system sleep, including lid-close sleep, Apple menu sleep, thermal emergency sleep, or low battery sleep. Delaying or preventing sleep can also increase power consumption.

Caffeinate versus Napless

The caffeinate command provides Terminal holds; Napless provides menu bar timers with status and safety checks.

	caffeinate	Napless
How you start it	Terminal: flags, -t seconds, a utility, or -w pid	Free: Keep Awake For and Keep Awake Until from the menu bar. Napless Pro (coming soon) also wraps a job with napless run -- <command>.
Status	pmset -g assertions; no menu bar countdown	Time left in the menu bar, honest status, Check Health, and napless doctor
Heat	No heat stop in man caffeinate	Stop If Your Mac Gets Too Hot is on by default. Serious or critical thermal state ends timed keep-awake.
Battery	No battery stop in man caffeinate	Free can stop on low battery. A deliberate battery pause shows a reason without the orange warning triangle.
Command wrap	caffeinate [utility] or caffeinate -w <pid>	Pro (coming soon): napless run -- <command>
Cost	Built into macOS at /usr/bin/caffeinate	Free to download. Napless Pro is coming soon at $7.99 one time, up to 3 Macs.

Napless Free also has a global shortcut and a Control Center control on macOS 26 and later. Napless Help places heat protection in Settings → General → Safety. After cooling, a timed session needs a new start; automatic keep-awake can resume after thermal state stays fair or cooler for 5 minutes. Keep Awake With Lid Closed is coming in an update.

If you already live in Terminal, caffeinate is enough for a timed hold or a wrapped job. If you want the time left in the menu bar, a health check, or a stop when the Mac is hot, use Napless Help for the current Free behavior and the Pro features that are still coming.

Questions

What does the caffeinate command do on a Mac?

The caffeinate command creates power assertions that change macOS sleep behavior. With no flags it prevents idle sleep until caffeinate exits, a timeout ends, or a wrapped utility finishes.

How do I keep a Mac awake for one hour with caffeinate?

Run caffeinate -t 3600 in Terminal. The -t value is seconds, so 3600 is one hour, and man caffeinate on macOS says the assertion is dropped after that timeout.

What is the difference between caffeinate -d and caffeinate -i?

caffeinate -d creates an assertion that prevents the display from sleeping. caffeinate -i creates an assertion that prevents idle system sleep. The default with no flags is the idle-sleep assertion, the same type as -i.

How do I stop caffeinate?

In the Terminal window running a foreground caffeinate, press Control-C. To stop another instance, send the default TERM signal with kill and that process ID.

Does caffeinate -s work on battery power?

man caffeinate on macOS says the -s assertion is valid only when the system is running on AC power.