PowerTOP is a Linux tool used to diagnose issues with power consumption and power management. In addition to being a diagnostic tool, PowerTOP also has an interactive mode you can use to experiment with various power management settings, for cases where the Linux distribution has not enabled those settings.

Build dependencies

PowerTOP is written in C++ and targets Linux. It requires the Meson build system and the following libraries:

• ncurses (required)
• libnl-3 (required)
• libtracefs (required)
• libtraceevent (required)
• libpci (optional — only needed if the system has PCI devices)
• gettext (optional — for translated messages)

Example packages to install on Ubuntu:

sudo apt install meson ninja-build libpci-dev libnl-3-dev libnl-genl-3-dev \
libncursesw5-dev libtracefs-dev libtraceevent-dev gettext pkg-config

Building PowerTOP

To build PowerTOP from the cloned source:

meson setup build
ninja -C build

To run the test suite:

meson setup -Denable-tests=true build_test
ninja -C build_test test

Running PowerTOP

PowerTOP must be run as root. When invoked without arguments it starts in interactive mode, which resembles top. Use the Tab and Shift-Tab keys to navigate between the Overview, Idle stats, Frequency stats, Device stats, Tunables, and WakeUp tabs.

Run powertop --help to see all options.

Kernel configuration

PowerTOP needs some kernel configuration options enabled to function properly. Modern distribution kernels typically have all of these enabled already. If you are running a minimal or custom kernel, check for:

CONFIG_NO_HZ
CONFIG_HIGH_RES_TIMERS
CONFIG_CPU_FREQ_GOV_ONDEMAND
CONFIG_PERF_EVENTS
CONFIG_TRACEPOINTS
CONFIG_TRACING
CONFIG_DEBUG_FS
CONFIG_POWERCAP
CONFIG_INTEL_RAPL    # Intel systems only

Generating reports

PowerTOP supports three report formats. All report modes take one measurement cycle (controlled by --time) and then write the report and exit.

HTML — rich report suitable for sharing:

powertop --html                       # writes powertop.html
powertop --html=myreport.html         # writes myreport.html

Markdown — plain-text report suitable for viewing in any Markdown renderer:

powertop --markdown                   # writes powertop.md
powertop --markdown=myreport.md       # writes myreport.md

CSV — machine-readable report:

powertop --csv                        # writes powertop.csv
powertop --csv=myreport.csv           # writes myreport.csv

Control how long PowerTOP measures before writing the report:

powertop --html --time=60             # measure for 60 seconds, then report

Run multiple measurement iterations (useful for averaging):

powertop --html --iteration=5 --time=20   # 5 iterations × 20 s each

Run a workload while measuring:

powertop --html --workload=/path/to/script.sh

Important: Because PowerTOP is intended for privileged (root) use, reports — especially those generated with --debug — will contain verbose system information. PowerTOP does not sanitize or anonymize its reports. Be mindful of this when sharing them.

Filing a bug report

Generate and share a --debug HTML report:

powertop --debug --html=bugreport.html

Then file the issue at: https://github.com/fenrus75/powertop/issues

Automated tuning

PowerTOP can apply all recommended power-saving settings in one shot without entering interactive mode:

sudo powertop --auto-tune

To preview what changes would be made without actually applying them:

sudo powertop --auto-tune-dump

The output of --auto-tune-dump is a list of shell commands. You can redirect it to a script to apply selectively or at boot time:

sudo powertop --auto-tune-dump > tune.sh
# review tune.sh, then:
sudo bash tune.sh

Calibrating power estimates

PowerTOP, when running on battery, tracks power consumption and activity to build up per-device power estimates. You can improve the accuracy of these estimates by running a calibration cycle at least once:

powertop --calibrate

Calibration cycles through various display brightness levels (including "off"), USB device activities, and other workloads. Run it on battery with no other active workload for best results.

Other useful options

Option	Description
--time=N	Collect data for N seconds per iteration (default: 20)
--iteration=N	Run N measurement iterations (default: 1)
--sample=N	Power consumption sampling interval in seconds (default: 5)
--workload=FILE	Execute FILE as a workload during measurement
--once	Run one measurement cycle and exit (non-interactive)
--quiet	Suppress stderr output
--debug	Enable debug-level output
--version	Print version information

Extech Power Analyzer / Datalogger support

PowerTOP supports the Extech Power Analyzer/Datalogger (model 380803) over a serial connection. Pass the device node on the command line:

powertop --extech=/dev/ttyUSB0

(where ttyUSB0 is the device node of the serial-to-USB adapter)

HTML/CSS validation

If you make changes to the HTML reporting code, validate the output using:

• https://validator.w3.org/#validate_by_upload
• https://jigsaw.w3.org/css-validator/#validate_by_upload

Contributing to PowerTOP and getting support

There are numerous ways to contribute to PowerTOP. See CONTRIBUTE.md for details. The short version: fork the repository and send pull requests.

To file a bug or feature request:

• https://github.com/fenrus75/powertop/issues

Code from other open source projects

PowerTOP contains code from other open source projects; we thank the authors for their work. Specifically, PowerTOP contains code from:

Parse Event Library - Copyright 2009, 2010 Red Hat Inc  Steven Rostedt <srostedt@redhat.com>
nl80211 userspace tool - Copyright 2007, 2008	Johannes Berg <johannes@sipsolutions.net>

Copyright and License

PowerTOP
Copyright (C) 2024  Intel Corporation

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; version 2.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA

See COPYING file for a copy of the aforementioned (GPLv2) license.

SPDX Tag

/* SPDX-License-Identifier: GPL-2.0-only */

From: https://spdx.org/licenses/GPL-2.0-only.html