Tue 06 October 2026

Python Package: laptop_battery_status

Posted by Al Sweigart in misc   

laptop_battery_status is a pure Python package for getting the battery status of your laptop. It reports the battery charge, the time remaining, and whether the computer is plugged in. It works on Windows, macOS, and Linux and runs on Python 3.5 and later. Install with pip install laptop_battery_status. Git repo.

Quickstart

>>> import laptop_battery_status as lbs
>>> lbs.is_plugged_in()
True
>>> lbs.is_charging()
True
>>> lbs.battery_level()
87.0
>>> lbs.battery_minutes_remaining()
inf

Unplug the laptop and the same calls report the runtime left:

>>> lbs.is_plugged_in()
False
>>> lbs.battery_minutes_remaining()
272.0

Functions

Function Returns
is_plugged_in() True if running on AC power, otherwise False.
battery_level() A float from 0.0 to 100.0 for the percent of charge left.
battery_minutes_remaining() A float of the minutes of runtime left, or float('inf') while plugged in.
is_charging() True if the battery is actively charging, otherwise False.
battery_present() True if a battery is installed, otherwise False.

The battery functions raise NoBatteryError on a desktop computer or in a virtual machine.

is_plugged_in() always returns True on desktop computers.

Exceptions

All exceptions subclass BatteryStatusError, which subclasses RuntimeError.

  • NoBatteryError - no battery is installed.
  • UnsupportedPlatformError - the operating system isn't Windows, macOS, or Linux.
  • BatteryStatusError - the power information couldn't be read, or the OS reported the AC power or charging state as unknown.

How it works

No third party packages are used.

  • Windows calls the Win32 GetSystemPowerStatus() function through ctypes.
  • macOS calls the IOKit IOPowerSources functions through ctypes, and falls back to parsing the output of pmset -g batt.
  • Linux reads the files under /sys/class/power_supply, and falls back to parsing the output of upower and then acpi. The kernel doesn't provide a time estimate, so the remaining minutes are calculated from the current charge and the rate it's being drawn at, which makes the number jumpier than the one in a desktop environment's battery menu.

Machines with more than one battery are reported as a single combined battery.


Check out other books by Al Sweigart, free online or available for purchase:

...and other books as well! Or register for the online video course. You can also donate to or support the author directly.