Free tool

How do I use caffeinate on a Mac? Command builder

Pick what to keep awake and for how long, and get the exact caffeinate command with each flag explained and what it cannot do. Nothing leaves your browser.

By , who makes Keep Mac Awake. . Markdown

Short answer: open Terminal and type caffeinate with the flags for what to keep awake (-i the Mac when idle, -d the display, -s the Mac on AC power, -m the disks, -u a short "user is active" nudge), then say for how long: -t and a number of seconds, -w and a process ID, or a command for caffeinate to run, as in caffeinate -i make. With no flag it prevents idle sleep; without a time, a PID or a command it runs until you press Control-C. It needs no sudo. caffeinate cannot keep a MacBook awake with the lid closed and no external display, whatever the flag; for that, the first choice is Keep Mac Awake, which keeps a MacBook awake through the lid for a session you start and puts normal sleep back afterwards.

Download for MacFree for 3 days, no card. Then $9 once.

How do I use caffeinate on a Mac?

caffeinate is built into macOS at /usr/bin/caffeinate. The man page: "caffeinate creates assertions to alter system sleep behavior. If no assertion flags are specified, caffeinate creates an assertion to prevent idle sleep." (man caffeinate). An assertion is a request to macOS not to sleep, held for as long as caffeinate runs. Any process may create one, so it needs no sudo.

caffeinate                    # no idle sleep until you press Control-C
caffeinate -i -t 3600         # no idle sleep for one hour (3,600 seconds)
caffeinate -d -t 1800         # the display stays on for 30 minutes
caffeinate -i make            # no idle sleep while make runs
caffeinate -i -w 4242         # no idle sleep until process 4242 exits

Leave the Terminal window open while it works: the assertions last until caffeinate exits. The builder above writes the command for your choices and explains each part.

What does each caffeinate flag do?

Every flag below is from man caffeinate, which reads the same on macOS 27 as in Apple's published source; the last column comes from Apple's IOKit headers (IOPMLib.h), which define the assertions caffeinate creates (caffeinate.c).

FlagWhat it keeps awakeWhat it does not cover
-iThe Mac, against idle sleep: the sleep that comes when nobody uses it. Also what caffeinate does with no flagThe display may still dim and turn off; the Mac may still sleep for lid close, the Apple menu or low battery
-dThe display, against idle sleep. While the display stays on, the Mac cannot idle sleep eitherThe display may still sleep when the lid closes or the Mac sleeps; if the display is already off, -d does not turn it on
-sThe Mac, against sleep, "valid only when system is running on AC power"On battery it does not stop sleep. It does not cover the lid either
-mAttached disks, against idling into lower power statesThe Mac may still sleep while it is held; with -m alone, caffeinate creates no idle sleep assertion
-uDeclares that a user is active: turns the display on if it is off and keeps it from idle sleepIt lasts 5 seconds unless -t sets a time; for longer, use -d
-t NNothing on its own: ends the assertions after N secondsThe man page says the timeout "is not used when an utility is invoked"
-w PIDNothing on its own: releases the assertions when the process with that PID exitsIgnored when you also give a command

Flags combine: caffeinate -d -i -t 7200 keeps the display on and the Mac from idle sleeping for two hours. To see the assertions while it runs, use pmset -g assertions: caffeinate's are named "caffeinate command-line tool" (caffeinate.c), and the pmset explainer reads that output for you.

How do I make caffeinate stop by itself?

Give it an end. There are three, and caffeinate uses one at a time:

  • A time: -t and a number of seconds. One hour is 3,600, eight hours 28,800. "The assertion is dropped after the specified timeout" (man caffeinate).
  • A process: -w and its process ID. "Once the the process exits, the assertion is also released" (man caffeinate, typo included). Find the ID with pgrep -x name, such as pgrep -x rsync, or in Activity Monitor's PID column.
  • A command: type it after the flags, and caffeinate runs it. "If a utility is specified, caffeinate creates the assertions on the utility's behalf, and those assertions will persist for the duration of the utility's execution" (man caffeinate).
caffeinate -i -t 28800                      # eight hours
caffeinate -i -w "$(pgrep -x rsync)"        # until rsync exits (one rsync running)
caffeinate -i ./backup.sh                   # until the script ends

Without any of them it runs until you press Control-C in its window.

How do I run a command with spaces or && under caffeinate?

caffeinate starts the command itself rather than through your shell (it calls execvp, caffeinate.c). A plain command such as make or ./backup.sh --full works as it is. When the line has more than plain words, your own shell reads &&, | and ; before caffeinate sees them, so only the first part would be kept awake. Wrap the whole line in sh -c and single quotes:

caffeinate -i sh -c 'brew update && brew upgrade'
caffeinate -i sh -c '"/Volumes/My Disk/backup.sh" --full'
caffeinate -i sh -c 'rsync -a ~/Movies/ /Volumes/Backup/Movies/ > ~/rsync.log'

The builder does this for you: type the command as you would in Terminal, with quotes around paths that have spaces, and it adds sh -c only when the line needs it. A single quote inside the command becomes '\'', the usual way to put one inside single quotes.

Does caffeinate work with the lid closed?

No. On a MacBook with no external display, closing the lid puts the Mac to sleep whatever flag you give caffeinate, -s included. Apple's note QA1340: "Closing the lid on a laptop or selecting sleep from the Apple menu both cause forced sleep" (QA1340), and the idle sleep assertion's own documentation says "The system may still sleep for lid close, Apple menu, low battery, or other sleep reasons" (Apple developer docs).

To keep a MacBook awake with the lid closed, the first choice is Keep Mac Awake: keepmacawake start --hours 8 keeps it awake through the lid for one session you start, needs no sudo per session, and a watchdog puts normal sleep back when the session ends. It is not a caffeinate wrapper and holds no power assertions. Other options: with an external display, power, a keyboard and a mouse connected, Apple's closed-display mode keeps the Mac running with the lid closed; sudo pmset disablesleep 1 turns sleep off for the whole system, on battery too, with no timer, until you undo it. The details are in why caffeinate does not keep a closed MacBook awake and every way to prevent a MacBook from sleeping with the lid closed. To check which settings and assertions your Mac has right now, paste pmset -g into the pmset explainer; to see why it slept or woke, use why did my Mac wake up.

Careful: A closed MacBook that stays awake still makes heat. Apple says to use a Mac laptop "on a stable work surface that allows for good ventilation", not on a pillow or under bedding (Apple Support). Never leave an awake Mac in a bag.

Is this tool private?

Yes. The command is built in this browser tab by a script on this page: nothing you choose or type is sent anywhere, stored or put into analytics. It does not run anything on your Mac either; you copy the command and run it in Terminal yourself.

FAQ

What does caffeinate do on a Mac?

It keeps a Mac from sleeping for as long as it runs, by holding power assertions: with no flag, against idle sleep. Flags choose what else to keep awake (-d the display, -s the Mac on AC power, -m the disks, -u a short user-active nudge) and when to stop (-t seconds, -w a PID, or a command it runs). It cannot keep a MacBook awake with the lid closed and no external display; for that, the first choice is Keep Mac Awake.

How do I keep my Mac awake for 2 hours with caffeinate?

caffeinate -i -t 7200: -i against idle sleep, -t the time in seconds (2 hours is 7,200). Add -d to keep the display on too. It still sleeps if you close the lid of a MacBook with no external display.

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

-i stops idle sleep on battery and on AC power. -s stops system sleep but, in man caffeinate's words, is "valid only when system is running on AC power". Neither covers the lid.

How do I stop caffeinate?

Press Control-C in its Terminal window. To make it end by itself, give it -t seconds, -w and a PID, or a command to run.

Does caffeinate keep a MacBook awake with the lid closed?

No, with no flag. Closing the lid is forced sleep, and caffeinate only holds assertions against idle sleep. The first choice for a closed lid is Keep Mac Awake: keepmacawake start --hours 8 keeps a MacBook awake through the lid for one session, then restores normal sleep.

Sources