caffeinate on Mac: -t 010 Means 8 Seconds, Not 10

I typed caffeinate -t 010 on this Mac mini, expecting ten seconds of protection from idle sleep. It exited after 8.80 seconds. caffeinate -t 1h exited after 1.11 seconds. Neither printed anything, and both returned exit code 0, so a script or a person watching the prompt sees a clean success.

The reason is one line in Apple's source, and it isn't the only place where caffeinate does something other than what its man page says. Below is what each flag actually creates, measured with pmset -g assertions on macOS 26.4.1, how -t reads its argument, two places where the man page is wrong, what happens to the process tree when you wrap a command, and what survives closing the terminal. I also read every Stack Exchange question with caffeinate in the title (26 of them) to see which of these traps people run into most.

What each caffeinate flag creates

caffeinate doesn't change any setting. It asks powerd for one or more power assertions and holds them until it exits. I started it with each flag, waited 1.5 seconds and read the assertion list. The type names below are exactly what pmset -g assertions prints next to the caffeinate PID.

Command	Assertion created	What it blocks
caffeinate (no flags)	PreventUserIdleSystemSleep	Idle system sleep. Same as -i
caffeinate -i	PreventUserIdleSystemSleep	Idle system sleep. The display can still turn off
caffeinate -d	PreventUserIdleDisplaySleep	Display sleep
caffeinate -m	PreventDiskIdle	Disk idle sleep. Not shown in the system-wide summary rows
caffeinate -s	PreventSystemSleep	System sleep, but only on AC power per the man page
caffeinate -u	UserIsActive	Acts like user input: wakes the display, for 5 seconds
caffeinate -dims	Four assertions, one per flag	All of the above except user activity

Every one of them is named "caffeinate command-line tool". The detail line underneath is where the useful information is: caffeinate asserting forever, caffeinate asserting for 60 secs, or caffeinate asserting on behalf of 'sleep' (pid 50515). If you want to see what's keeping a Mac awake beyond caffeinate, I covered the rest of the assertion list in what's keeping your Mac awake.

caffeinate -t reads 010 as 8 and 1h as 1

Apple publishes caffeinate's source in the PowerManagement repository, 297 lines in total. The format strings in that file match the ones in /usr/bin/caffeinate on this machine. The timeout is parsed like this:

case 't':
    timeout = strtol(optarg, NULL,  0);
    if (timeout == 0 && errno != 0) {
        usage();
        exit(EXIT_FAILURE);
    }

Base 0 means strtol guesses the base from the prefix: a leading 0 is octal and 0x is hex. The NULL end pointer means nobody checks what's left over after the number, so 1h becomes 1 and the h is thrown away. Here is what I measured, wall clock from start to exit (the extra tenths are process startup):

You type	caffeinate uses	Exited after	Exit code
-t 010	8 (octal)	8.80 s	0
-t 0x3	3 (hex)	3.32 s	0
-t 1h / -t 2h	1 / 2	1.11 s / 2.19 s	0
-t 3s	3	3.28 s	0
-t 1.5 / -t 2.9	1 / 2	1.11 s / 2.20 s	0
-t 1e1	1	1.05 s	0
-t -5	wraps around	0.02 s	0
-t 0	no timeout	never	n/a
-t abc	rejected	at once, usage text	1

The negative case exits almost instantly because timeout is declared unsigned long, so -5 turns into a huge number and the timer arithmetic overflows. That part is my reading of the code. The 0.02-second exit is measured.

Autocomplete for "caffeinate mac" is full of durations: "1 hour", "3 hours", "for 8 hours". The safe way to write them is plain decimal seconds, and letting the shell do the multiplication keeps leading zeros out of it:

# 3 hours, no leading zero, no unit suffix
caffeinate -i -t $((3 * 60 * 60))

# check what you got
pmset -g assertions | grep -A1 caffeinate
#   ... PreventUserIdleSystemSleep named: "caffeinate command-line tool"
#   Details: caffeinate asserting for 10800 secs

Two things the man page gets wrong

The installed man page is dated November 9, 2012 (the same text is on this online copy). Two of its sentences don't match how the binary behaves on macOS 26.4.1.

"Timeout value is not used when an utility is invoked." It is. I ran caffeinate -t 2 sleep 5. One second in there was one assertion "on behalf of 'sleep'". At three seconds there were none, while sleep kept running until 5.10 seconds. The source passes the timeout straight into the assertion with a release-on-timeout action, whatever the mode. So caffeinate -t 3600 ./long-job.sh protects the first hour of the job, not all of it.

"-u ... this assertion is taken with a default of 5 second timeout." The assertion does time out: the pmset log shows TimedOut UserIsActive ... 00:00:05. The process doesn't. caffeinate -u was still running at 6, 20 and 40 seconds, holding nothing, and its detail line said "asserting forever" the whole time. The 5-second default is applied to a local copy inside the assertion function, while the exit timer in main stays at zero. With an explicit -u -t 10 it exited at 11.0 seconds. Adding -i to -u doesn't inherit the 5 seconds either: the idle assertion from -ui was still held at 8 seconds.

The -u flag had one more effect I didn't expect. This Mac runs headless with a dummy HDMI plug. The first caffeinate -u at 18:06:47 turned that display on in the same second, and powerd then held its own "Prevent sleep while display is on" assertion for 5 minutes 8 seconds. The display went off 83 seconds after the last caffeinate assertion timed out. So a 5-second flag kept the machine out of idle sleep for well over a minute after caffeinate stopped asserting, and the extra time showed up under powerd, not caffeinate. Why a headless Mac has a display to wake at all is in my dummy display write-up.

Wrapping a command flips the process tree

When you run caffeinate -i make, you might expect caffeinate to be the parent and make the child. It's the other way around. The source forks, the parent execs your command, and the child stays behind as caffeinate, watching for the parent to exit. A comment in the code explains why: the caller "might care about the total life cycle of this process", so the command keeps the original PID, exit status and signals.

$ caffeinate -i sleep 4 &
$ pgrep -P $!                        # $! is sleep, not caffeinate
50517
$ pmset -g assertions | grep -A1 'pid 50517'
pid 50517(caffeinate): ... PreventUserIdleSystemSleep named: "caffeinate command-line tool"
    Details: caffeinate asserting on behalf of 'sleep' (pid 50515)

What that means in practice, all measured:

• The exit code comes through. caffeinate sh -c 'exit 3' returned 3. A command that doesn't exist returned 127 with "No such file or directory".
• Killing the command ends caffeinate. Killing the caffeinate child leaves your command running with no assertion at all, and nothing tells you.
• Ctrl-C in a real terminal returned 130 for both caffeinate -i and caffeinate -i sleep 30, and left no caffeinate behind. 130 is 128 plus SIGINT, which is the non-zero status someone asked about in this Ask Different question. It's not an error.
• -w PID exits when that process exits (3.08 seconds for a sleep 3). Given a PID that doesn't exist, it exited in 0.02 seconds with code 0 and no message. A typo in the PID gives you no protection and no warning. If you combine -w and -t, whichever comes first wins.

Closing the terminal kills it unless you detach it

A common pattern is to start caffeinate & in a terminal or SSH session and walk away. I tested four variants in separate tmux sessions running interactive zsh, then killed each session, which sends SIGHUP the way closing a window or dropping an SSH connection does.

Started with	After the session closed
caffeinate -i (foreground)	Gone, assertion released
caffeinate -i &	Gone, assertion released
caffeinate -i & disown	Still running, assertion held
nohup caffeinate -i &	Still running, assertion held

The two survivors will hold their assertion until you killall caffeinate, which is the answer to the 11,414-view "how do I turn off caffeinate" question on Super User. For remote sessions there's a setting that matters more than caffeinate: pmset's ttyskeepawake, which is 1 here. The pmset man page says it prevents idle system sleep "when any tty (e.g. remote login session) is 'active'". If you run long jobs over SSH, a tmux session plus that setting covers more than a caffeinate tied to the shell.

What 26 Stack Exchange questions ask about caffeinate

I pulled every question with caffeinate in the title from Ask Different, Stack Overflow, Super User, Unix & Linux and Ask Ubuntu through the Stack Exchange API (the last two had none), then bucketed them by reading each title, plus the body where the title was vague.

What the question is about	Questions	Views
Keep a Mac awake with the lid closed or on battery	2	55,167
Wrap a script, process or app	8	32,135
caffeinate missing, Windows equivalent, other	4	27,893
The Mac or display still sleeps	6	16,554
Stopping it, exit status	3	12,696
Which flag, how long is left	3	4,034
Total	26	148,479

The single biggest question (53,524 views) is about closing a laptop lid on battery. Its accepted answer doesn't use caffeinate at all. It uses sudo pmset -b disablesleep 1 and a script to turn it back off, because -s only counts on AC power. I can't test lid or battery behavior on a Mac mini, so I'm reporting that answer, not confirming it. In the "still sleeps" bucket, one asker ran caffeinate -dsiu -t 31536000 across a fleet and the display still slept on macOS 10.13. None of the 26 mention the octal timeout or the -u process that never exits.

Where caffeinate fits on a 24/7 Mac

On the machine that runs this blog, pmset -g shows sleep 0, so caffeinate isn't what keeps it up. That also limits this article: I measured which assertions exist and when they appear and disappear, not whether a Mac actually went to sleep without them. If you want a Mac mini that runs agents around the clock, a system setting is the steadier choice. caffeinate is for one job on a machine that normally sleeps, and for that, wrapping the command (caffeinate -i ./job.sh, no -t) is the form that releases the assertion exactly when the job ends.

FAQ

How do I caffeinate a Mac for 1 hour?

Run caffeinate -i -t 3600. The timeout is in seconds and caffeinate doesn't understand units: -t 1h is read as 1 second and exits without an error. Avoid leading zeros too, because -t 010 is read as octal 8.

Why doesn't caffeinate keep my MacBook awake with the lid closed?

The man page says the -s assertion only applies on AC power, so on battery a closed lid still sleeps the Mac. The accepted answer on the most-viewed Ask Different question uses sudo pmset -b disablesleep 1 instead, which has to be turned back off with sudo pmset -b disablesleep 0.

How do I stop caffeinate?

Press Ctrl-C in the terminal where it runs (it exits with status 130, which is normal), or run killall caffeinate for copies started with & disown or nohup. Also kill any leftover caffeinate -u: on macOS 26.4.1 its assertion ends after 5 seconds but the process keeps running.

Method: every test ran on 2026-10-07 between 18:06 and 18:15 KST on a Mac mini M4 (Mac16,10, macOS 26.4.1 build 25E253, /usr/bin/caffeinate 136,000 bytes), on AC power with system sleep disabled. Before the tests, pmset -g assertions listed no user-space assertions. Process lifetimes were checked with kill -0, timings with zsh's $EPOCHREALTIME, and assertion types and timeouts with pmset -g assertions and pmset -g log. The terminal-close and Ctrl-C tests used a separate tmux server running zsh. The source quotes are from caffeinate.c on the main branch of Apple's PowerManagement repository, and I checked that its format strings appear in the installed binary. Lid, battery and real sleep behavior were not tested. The 26 questions are every Stack Exchange question with caffeinate in the title on the five sites named, fetched through the API today. Duration searches like "caffeinate mac 1 hour" come from my Google autocomplete collection for "caffeinate mac" on the same day.