Computing is usually defined as the activity of using and improving computer hardware and software. It is the computer-specific part of information technology...
, pmset is a command line utility to manipulate power management settings under the Darwin
Darwin (operating system)
Darwin is an open source POSIX-compliant computer operating system released by Apple Inc. in 2000. It is composed of code developed by Apple, as well as code derived from NeXTSTEP, BSD, and other free software projects....
Mac OS X is a series of Unix-based operating systems and graphical user interfaces developed, marketed, and sold by Apple Inc. Since 2002, has been included with all new Macintosh computer systems...
operating systems. It can assign sleep settings, schedule sleep and wake times, and display power information.
Darwin is an open source POSIX-compliant computer operating system released by Apple Inc. in 2000. It is composed of code developed by Apple, as well as code derived from NeXTSTEP, BSD, and other free software projects....
Mac OS X version 10.2 "Jaguar" is the third major release of Mac OS X, Apple's desktop and server operating system. It superseded Mac OS X v10.1 code name Puma and preceded Mac OS X Panther...
. It has been updated periodically since its introduction, and is still available as of Darwin 10.3 and Mac OS X 10.7 "Lion".
Behavior
The utility sets or lists power management settings. Some of the functionality provided by the utility is available through the GUI interface of the Energy Saver
System Preferences
System Preferences is an application included with the Mac OS X operating system that allows users to modify various system settings which are divided into separate preference panes...
preference pane. However, pmset allows for greater flexibility and access to several options not available in the GUI.
The utility can set different power management settings depending on usage scenario. Different settings can be applied for when the machine is running off a charger, battery, UPS
Uninterruptible power supply
An uninterruptible power supply, also uninterruptible power source, UPS or battery/flywheel backup, is an electrical apparatus that provides emergency power to a load when the input power source, typically mains power, fails...
, or all three. The appropriate flags are as follows:
-c (charger), adjust settings used while connected to a charger
-b (battery), adjust settings used when running off a battery
An uninterruptible power supply, also uninterruptible power source, UPS or battery/flywheel backup, is an electrical apparatus that provides emergency power to a load when the input power source, typically mains power, fails...
), adjust settings used when running off a UPS
-a (all, default) adjust settings for all scenarios
Additional arguments be supplied when assigning any power management settings. Power management arguments are discussed in greater detail below. When invoking the command, only specified arguments modify power management options. Any arguments already set will be unmodified by pmset unless those arguments are specifically included.
The utility can schedule wake, sleep, power on or power off events. Events can be recurring based on arbitrary weekday and time combinations, or scheduled for future dates and times. The syntax for scheduling an event is as follows:
Previously stored events will be overwritten upon running this command. To schedule multiple events they must be entered in one command string. For example, to set a shutdown event every day of the week at 23:59 and a wake or power on event every day of the week at 7:00 enter the following:
The get flag displays information about the current power management configuration, or a log of recent activity. If no additional arguments are supplied the flag will only display current settings. Additional get arguments are discussed in greater detail below. The get flag is as follows:
-g get, list current power management settings
To view the currently scheduled events type:
pmset -g sched
The utility is also able to configure hibernation and safe sleep options, and change Energy Saver profiles.
Power Management Settings
The pmset utility recognizes the following arguments. Arguments can be passed in serial form in any order. Any bad syntax or unrecognized argument will cause the entire command to fail, resulting in an error message and brief help screen. Power management settings can only be changed by a privileged user.
displaysleep display sleep timer in minutes, 0 to disable display sleep
disksleep disk spindown timer in minutes, 0 to disable disk sleep
sleep system sleep timer in minutes, 0 to disable sleep
womp wake on "magic" Ethernet packet, 1 to enable or 0 to disable
hibernatemode change hibernation mode, 0 for RAM powered while sleeping; 1 for RAM contents written to disk and system totally unpowered; 3 for RAM both powered and written to disk; 5 is the same as mode 1, but for use with secure virtual memory; 7 is the same as mode 3, but for use with secure virtual memory; 25 for hibernation in OS X Lion, with RAM contents written to disk and system totally unpowered
hibernatefile change hibernation image file location; image may only be located on the root volume
ring wake on modem ring, 1 to enable or 0 to disable
autorestart automatic restart after loss of power, 1 to enable or 0 to disable
dps dynamically change processor speed based on load, 1 to enable or 0 to disable
reduce permanently reduce processor speed, 1 to enable or 0 to disable
powerbutton put the machine to sleep when the power button pressed instead of shutting it down, 1 to enable or 0 to disable
lidwake (laptop only) wake the machine when the laptop lid is opened, 1 to enable or 0 to disable
acwake (laptop only) wake the machine when the power source is changed, such as when AC power is removed and the machine switches to battery power, 1 to enable or 0 to disable
lessbright (laptop only) slightly turn down display brightness when switching to a specified power source, 1 to enable or 0 to disable
halfdim display sleep will use an intermediate half-brightness state between full brightness and fully off, 1 to enable or 0 to disable
The Sudden Motion Sensor is Apple's patent-pending motion-based hardware and data-protection system used in their notebook computer systems. Apple introduced the system January 1, 2005 in its refreshed PowerBook line, and included it in the iBook line July 26, 2005...
to park disk heads on sudden changes in G force, 1 to enable or 0 to disable
haltlevel (UPS only) UPS charge in percentage, shutdown the machine when UPS reaches a specified charge level
haltafter (UPS only) UPS charge in minutes, shutdown machine after drawing on UPS for specified number of minutes
haltremain (UPS only) UPS charge in minutes, shutdown machine when specified time remains on UPS
ttyskeepawake prevent idle system sleep when any tty (such as a remote login session) is active; a tty is inactive only when its idle time exceeds the system sleep timer, 1 to enable or 0 to disable
Settings may be adjusted independently for circumstances where the machine is attached to a charger, when running off a battery (in the case of a laptop), or when running off a UPS (if available). Settings can also be adjusted for all four scenarios simultaneously; this is the default option, for when no usage flag is specified. Power management options can be specified for different profiles by appending -c (charger), -b (battery), -u (UPS) or -a (all) flags. The following example will set the machine to sleep after 10 minutes and sleep the display after five minutes, but only when powered by the battery.
pmset -b sleep 10 displaysleep 5
The following command will assign slightly different power management settings for circumstances where the machine is powered by the charger. Here, the machine is set to sleep after 30 minutes and the display is set to never sleep, but only when set by the charger. Issuing both commands will not interfere with each other.
pmset -c sleep 30 displaysleep 0
Arguments can be entered in serial form to set or modify several power management parameters with one command. The following command will set the machine to never sleep (sleep 0), enable the Sudden Motion Sensor (sms 1), set the display to sleep after 20 minutes (displaysleep 20), disable processor speed reduction (reduce 0), enable intermediate display dimness (halfdim 1), enable the machine to wake when the lid is opened (lidwake 1), prevent the system from seeping when a tty session (such as SSH) is active (ttyskeepawake 1), disable waking the machine when the AC adapter is inserted (acwake 0), disable an automatic restart after power is removed and restored (autorestart 0), enable dynamic change of processor speed based on system load (dps 1), enable wake on modem ring (ring 1), enable wake on receipt of "magic" Ethernet packet (womp 1), and disable hard disk sleep (disksleep 0):
Because the above example did not include a usage flag, the settings specified will apply to all usage scenarios. Subsequent commands that do specify a usage flag will only affect settings for that usage scenario. For instance, pmset -b sleep 10 will cause the machine to sleep after 10 minutes, but only when the battery is attached. All other settings will apply when the battery is attached, and all settings in the above example will apply when a charger or UPS is attached.
Mac OS X Leopard is the sixth major release of Mac OS X, Apple's desktop and server operating system for Macintosh computers. Leopard was released on 26 October 2007 as the successor of Tiger , and is available in two variants: a desktop version suitable for personal computers, and a...
, all changes made through pmset are saved in a persistent preferences file at /Library/Preferences/SystemConfiguration/com.apple.PowerManagement.plist. This file can be modified manually using the defaults command, but those changes will not be taken up immediately by the power management system. Manual edits of com.apple.PowerManagement.plist also stand the risk of being overwritten. The command pmset touch will reread existing settings from disk and apply them to the system.
Schedule Settings
The pmset command is able to schedule system sleep, shutdown, wakeup or power on events. The schedule argument is for setting up one-time power events, and repeat is for setting up daily or weekly events. Scheduling of events can only be done by a privileged user.
The schedule argument recognizes the following additional arguments:
type; one of sleep, wake, poweron, shutdown or wakeorpoweron
date and time (schedule only); in the format "MM/dd/yy HH:mm:ss"; must be in 24 hour format, must be in quotes
time (repeat only); in the format HH:mm:ss; must be in 24 format, but does not have to be in quotes
weekdays; a subset of MTWRFSU such as M or MTWRF are valid, as are strings weekdays, weekends, and everyday
owner; a string describing the person or program who is scheduling the power event (optional)
The utility can be very unforgiving of improper syntax. Any errors in syntax will cause the command to fail and will display a brief help message. The syntax for a scheduled event is as follows:
Only one type of event (sleep, wake, et cetera) can be specified, and the date chosen must be in the future. The utility expects to be able to store this information in the PMU
Power Management Unit
The Power Management Unit is a microcontroller that governs power functions of digital platforms. This microchip has many similar components to the average computer, including firmware and software, memory, a CPU, input/output functions, timers to measure intervals of time, as well as analog to...
, and so may not work reliably on non-Apple hardware. The date and time string must be enclosed in quotation marks.
Scheduled wake, sleep and power events are stored in a persistent preferences file in /Library/Preferences/SystemConfiguration/com.apple.AutoWake.plist. This file can be manually edited using the defaults command, but any changes so made stand a serious risk of being overwritten. Also, such edits will not be immediately taken up by the system.
List Options
The list flag, -g, displays information about the current power configuration. The flag alone, with no additional arguments, will display current power management settings. Additional arguments will display more specific information. The get functions of pmset do not require privileged access. The utility recognizes the following arguments:
live like the default option, displays the settings currently in use
custom will display custom settings for all power sources, although these settings may not currently be in use
cap capabilities, display which power management features the machine supports
sched schedule, display scheduled startup, wake, shutdown and sleep events
ups will display UPS emergency thresholds
ps power source, display status of connected batteries and UPSs
pslog display an ongoing log of power source state
rawlog display an ongoing log of power source state as read directly from battery
profiles
Only one get argument can be passed to pmset, and it must be preceded by the get flag. For instance, to display scheduled events, type pmset -g sched. The utility will not return an error is more than one get argument is provided, but all other than the first will be ignored.
Sample usage
The following examples demonstrate the output of the pmset command on an Apple PowerBook G4 running OS X 10.5.4 "Leopard".
The following example will put the relevant computer to sleep immediately:
pmset sleepnow
The following example will apply only to laptops when powered by the battery. It will set the machine to sleep after 5 minutes of inactivity, put the display to sleep after 2 minutes, and spin down the hard disk after 3 minutes. Only privileged users can issue this command. If the command is issued successfully and is without syntax errors, pmset will exit silently with an exit code of 0. To verify that the system took the new configuration, issue the command pmset -g.
pmset -b sleep 5 displaysleep 2 disksleep 3
The following example will apply only to machines being powered by a UPS. It will set the machine to perform an emergency shutdown when 5 percent battery remains on the UPS, or 5 minutes estimated draw time remains, whichever comes first. Only privileged users can issue this command. If the command is issued successfully and is without syntax errors, pmset will exit silently with an exit code of 0. To verify that the system took the new configuration, issue the command pmset -g.
pmset -u haltlevel 5 haltremain 5
The following example will apply for all usage scenarios. It will set the machine to wake on receipt of a "magic" Ethernet packet, wake if the modem detects a ring, and prevent the system from sleeping if a tty session is active. Only privileged users can issue this command. If the command is issued successfully and is without syntax errors, pmset will exit silently with an exit code of 0. To verify that the system took the new configuration, issue the command pmset -g.
pmset -a womp 1 ring 1 ttyskeepawake 1
The following example sets a one-time scheduled power event. The machine will be set to shut down 01/10/2009 at 10:00 PM. Only privileged users can issue this command. If the command is issued successfully and is without syntax errors, pmset will exit silently with an exit code of 0. To verify that the system took the new configuration, issue the command pmset -g sched.
pmset schedule shutdown "01/10/2009 22:00:00"
The following example sets a repeating power event. The machine will wake or power on every weekday at 8:00 AM. Only privileged users can issue this command. If the command is issued successfully and is without syntax errors, pmset will exit silently with an exit code of 0. To verify that the system took the new configuration, issue the command pmset -g sched.
pmset repeat wakeorpoweron MTWRF 08:00:00
Here, example output from pmset -g. At the time, the machine was being powered by the charger, while simultaneously charging the battery. The command prints the current configuration.
$ pmset -g
Active Profiles:
Battery Power -1
AC Power -1*
Currently in use:
sleep 0
sms 1
displaysleep 20
reduce 0
halfdim 1
lidwake 1
ttyskeepawake 1
acwake 0
autorestart 0
dps 1
ring 1
womp 1
disksleep 0
Here, example output from pmset -g sched. In this example, the machine has already been configured for a repeating event to start or wake up every weekday at 8:00 AM. The command prints the repeating event; note that the next such occurrence appears as a scheduled power event.
$ pmset -g sched
Repeating power events:
wakepoweron at 8:00AM weekdays only
Scheduled power events:
[0] wakeorpoweron at 08/04/08 08:00:00 by Repeating
External links
pmset(1) manual page at Apple Developer Connection
