Mac Terminal Command to Keep Screen On (caffeinate)

The Mac Terminal command to keep the screen on is:

caffeinate -d

It keeps the display awake until you press Ctrl+C. To stop it automatically after a set time, add -t with a number of seconds, like caffeinate -d -t 3600 for one hour. caffeinate ships with macOS (/usr/bin/caffeinate), so there’s nothing to install. Everything below was tested on a MacBook Air running macOS Tahoe 26.6.2.

What each caffeinate flag does

Flag	Prevents	Notes from testing
(none)	System idle sleep	Same as `-i`
`-d`	Display sleep	What most people want for “keep screen on”
`-i`	System idle sleep	Screen can turn off, but downloads and builds keep running
`-m`	Disk idle sleep	Shows as `PreventDiskIdle 1`. Rarely needed on SSD Macs
`-s`	All system sleep	Only on AC power. On battery it does nothing
`-u`	Declares the user active	Wakes the screen. Times out after about 5 seconds (see below)
`-t N`	(modifier)	Release after N seconds
`-w PID`	(modifier)	Release when that process exits

You can combine them. caffeinate -di keeps both the screen and the system awake.

Keep the screen on, and prove it’s working

Run caffeinate in the background for a few seconds and check what macOS sees:

caffeinate -d -t 3 &
pmset -g assertions | sed -n '2,14p'

Assertion status system-wide:
   BackgroundTask                 0
   ApplePushServiceTask           0
   UserIsActive                   1
   PreventUserIdleDisplaySleep    1
   SoftwareUpdateTask             0
   PreventSystemSleep             0
   ExternalMedia                  0
   PreventUserIdleSystemSleep     1
   NetworkClientActive            0
Listed by owning process:
   pid 94948(caffeinate): [0x00404be300059a55] 00:00:01 PreventUserIdleDisplaySleep named: "caffeinate command-line tool"  
	Details: caffeinate asserting for 3 secs

PreventUserIdleDisplaySleep 1 is the line that keeps your screen on. Once the 3 seconds pass, it drops back to 0:

   PreventUserIdleDisplaySleep    0
   PreventSystemSleep             0
   PreventUserIdleSystemSleep     1

Note that PreventUserIdleSystemSleep stayed at 1. That wasn’t from caffeinate. On my Mac it came from powerd, with the reason “Prevent sleep while display is on.” So keeping the display awake with -d also keeps the system awake as a side effect. If you only need a background job to finish, -i is the lighter choice. It lets the screen turn off.

Keep the Mac awake for a set time (and why there’s no `timeout`)

Lots of Linux guides wrap commands in timeout. On macOS that fails:

command -v timeout; echo "rc=$?"
timeout 3 echo hi

rc=1
zsh:1: command not found: timeout

macOS doesn’t ship timeout, and it doesn’t ship gtimeout either. You have three options:

Use caffeinate -t. For staying awake, this is all you need:
```
caffeinate -d -t 1800   # screen on for 30 minutes
```
Install GNU coreutils with Homebrew. It adds gtimeout (with a g in front). I didn’t install it on the test Mac:
```
brew install coreutils
gtimeout 60 some-command
```
If brew itself says “command not found,” see how to fix zsh: command not found: brew.
Use the built-in Perl. /usr/bin/perl is still on Tahoe, and this one-liner works like timeout:
```
perl -e 'alarm shift; exec @ARGV' 2 sleep 10; echo "rc=$?"
```
```
rc=142
```
It killed sleep 10 after 2 seconds. Exit code 142 means “killed by the alarm signal.”

Keep the Mac awake while a command runs

Put the command after caffeinate. The Mac stays awake until the command ends:

caffeinate -i make build

I tested this with a stand-in “build” that sleeps for 2 seconds:

caffeinate -i zsh -c 'sleep 2; echo build finished' &
pmset -g assertions | grep -A1 caffeinate

   pid 95706(caffeinate): [0x00404cb000019ac6] 00:00:00 PreventUserIdleSystemSleep named: "caffeinate command-line tool"  
	Details: caffeinate asserting on behalf of 'zsh' (pid 95704)
build finished

Once the command finished, the assertion was gone.

A tested gotcha about PIDs. When you give caffeinate a command, the PID you get from $! is the command, not caffeinate. In the output above, the assertion is owned by pid 95706, but the job itself was pid 95704. I confirmed it with ps. The background PID showed up as sleep, not caffeinate. So if you kill $!, you stop your build, not the keep-awake.

A second gotcha: -t is not ignored. The caffeinate man page on Tahoe (dated 2012) says the timeout “is not used when an utility is invoked.” That’s not what happened on 26.6.2:

caffeinate -i -t 2 sleep 5 &

@1s: 1
@3s: 0
@4.5s: 0

Those are counts of active caffeinate assertions. The assertion dropped after 2 seconds, while sleep 5 kept running. Without -t, the assertion lasted the full run. So don’t add -t to a long build “just in case.” The Mac can go to sleep partway through the build.

Keep the Mac awake until another process finishes

Already started a long download or script? Find its PID and use -w:

sleep 4 &
caffeinate -i -w $!

   pid 95220(caffeinate): [0x00404c1400019a70] 00:00:01 PreventUserIdleSystemSleep named: "caffeinate command-line tool"  
	Details: caffeinate asserting on behalf of Process ID 95219

When the sleep ended, caffeinate exited on its own. To find the PID of something running elsewhere, use pgrep -l name or lsof. The kill process on port guide shows how to find PIDs by port.

caffeinate -s and -u: two flags that surprise people

-s does nothing on battery. The man page says this assertion “is valid only when system is running on AC power.” My test MacBook Air was on battery. caffeinate -s still created its assertion, but the system-wide value stayed at 0:

   PreventSystemSleep             0
   pid 95196(caffeinate): [0x00404c0c00079a6d] 00:00:01 PreventSystemSleep named: "caffeinate command-line tool"

On a laptop away from the charger, use -i (or -di) instead.

-u lasts about 5 seconds, but the process never exits. caffeinate -u on its own reported “asserting forever.” In practice the assertion vanished between 4 and 5 seconds, and the caffeinate process kept running with nothing to show for it:

@1s: 1
@2s: 1
@3s: 1
@4s: 1
@5s: 0
@6s: 0
@7s: 0
  PID ELAPSED COMM
95894   00:07 caffeinate

So -u is good for waking the screen once, not for keeping it on. If you use it in a script, pair it with -t so it exits. caffeinate -u -t 2 exited by itself after 2 seconds.

Stopping caffeinate

Running in the foreground: press Ctrl+C.
Running in the background: kill %1 in the same Terminal, or pkill caffeinate (this stops every caffeinate you started).
Closing the Terminal window normally ends it too, because the shell hangs up its background jobs when it exits.

To check that nothing is still holding your Mac awake, run pmset -g assertions | grep caffeinate. No output means you’re clear.

Common questions

How do I keep my Mac screen on without Terminal?

Change the display sleep timer in System Settings > Lock Screen (the “Turn display off…” options). To see the current value from Terminal, run pmset -g | grep displaysleep. My test Mac showed displaysleep 10, which is 10 minutes. caffeinate is better when you only want it for one task.

Does caffeinate work with the lid closed?

Don’t count on it. I didn’t test the lid here. A MacBook normally sleeps when you close the lid, unless it’s on power with an external display connected (Apple calls this closed-display mode). And -s only applies on AC power, as shown above.

Will caffeinate drain my battery?

Only as much as keeping the Mac awake normally would. The caffeinate process itself showed 0.0 %CPU and about 3 MB of memory in ps. Using -i instead of -d saves the most power, because the screen can still turn off.

Is there a caffeinate option to run forever?

Yes. Plain caffeinate (or caffeinate -d) with no -t runs until you stop it.

Why does `caffeinate -x` show an error?

There’s no -x flag. The usage line on Tahoe is caffeinate [-disu] [-t timeout] [-w Process ID] [command arguments...]. -m works (it set PreventDiskIdle 1 in my test) but isn’t in that summary.