Linux laptop battery logging tool
A simple Python app with few dependencies that reads your sysfs-class-power numbers and records them to a local sqlite3 db with an "event" tag.
It was built to track suspend power usage for Framework laptops, but it should work on other Linux laptops that expose battery data through /sys/class/power_supply.
Native Python packaging is the recommended install path:
pipx install batteryloguv tool install batterylogpip install batterylog
INSTALL.sh is the legacy install format. It remains supported for existing installs and upgrades.
Existing legacy command behavior is part of the upgrade contract: batterylog.py suspend, batterylog.py resume, and the zero-argument report should keep working for upgraded legacy installs.
Existing legacy data is also part of that contract: upgrades should not silently relocate or replace /opt/batterylog/batterylog.db.
If schema upgrades are needed in the future, they should happen transparently in place for the active database rather than requiring manual intervention.
Install batterylog, then run:
batterylogFor persistent system hook installs from this repo, the legacy helper still works:
git clone https://github.com/lhl/batterylog.git
cd batterylog
./INSTALL.shThe default invocation reports the most recent complete suspend/resume cycle:
batterylogRecent-cycle views:
batterylog history --limit 10
batterylog summary --limit 10
batterylog history --discharging-onlyAdministrative commands:
batterylog --help
batterylog --version
sudo batterylog install-hook
sudo batterylog uninstall-hook
batterylog migrate-db --from /opt/batterylog/batterylog.db --to /var/lib/batterylog/batterylog.dbCharging sessions are reported as battery gain instead of negative usage, and suspend/resume rows now record charger-state context for later inspection.
For legacy /opt installs, replace batterylog with /opt/batterylog/batterylog.py.
batterylog stores its data in a local sqlite database.
Default locations:
- Packaged CLI use without a managed system hook:
$XDG_STATE_HOME/batterylog/batterylog.db - If
XDG_STATE_HOMEis not set:~/.local/state/batterylog/batterylog.db - Managed system hook installs from
sudo batterylog install-hook:/var/lib/batterylog/batterylog.db - Legacy
/optinstalls:/opt/batterylog/batterylog.db
Path resolution precedence:
--db /path/to/batterylog.dbBATTERYLOG_DB=/path/to/batterylog.db/etc/batterylog/config.tomlwritten byinstall-hook- legacy sibling path for
/opt/batterylog/batterylog.py - user default XDG state path
Custom paths:
- One-off command:
batterylog --db /path/to/batterylog.db - Per-shell/session override:
BATTERYLOG_DB=/path/to/batterylog.db batterylog - Managed system hook with a custom DB:
sudo batterylog install-hook --db /path/to/batterylog.db
What is stored:
- one row per
suspendorresumeevent - timestamp and battery identifier
- battery cycle count and raw charge/current/voltage snapshot values
- derived energy/power values used for reporting
- battery status and line-power state when available
Automatic schema upgrades run in place on the active database. When a migration
changes an existing DB, batterylog leaves a sibling .bak file behind.
Make sure you meet the requirements, clone the repo, and run INSTALL.sh.
The legacy installer stages or refreshes /opt/batterylog, then runs the managed hook installer with the legacy DB path so logging continues to write to /opt/batterylog/batterylog.db.
Future installer work will keep this path functioning for upgrades and reinstalls, but new packaged releases should eventually be preferred over this legacy flow.
You can run /opt/batterylog/batterylog.py without any parameters and it will calculate the power usage from the last suspend/resume cycle:
$ /opt/batterylog/batterylog.py
Slept for 8.72 hours
Used 6.10 Wh (394.1 mAh), an average rate of 0.70 W (45.2 mA)
For your 53.67 Wh (3467.1 mAh) battery this is 1.30%/hr or 31.29%/day
This script looks for the first battery at /sys/class/power_supply/BAT*. It has currently only been tested with a Framework laptop, and some machines may not expose every value it expects. The tool is intentionally small and CLI-first: it stores the raw suspend/resume history in sqlite and exposes a few practical reporting commands on top.
Reports include secondary mAh and mA figures alongside Wh and W, which makes it easier to compare batterylog output against charge-based tools such as tlp-stat -b.
The new history and summary commands cover the most common review use cases without adding a heavier UI layer.
Common install commands:
pipx install batterylog
uv tool install batterylog
pip install batterylogEphemeral CLI checks:
uvx batterylog --helpFor a persistent system suspend hook from a repo checkout, INSTALL.sh is still the simplest documented setup in this project today.
- Linux with battery data exposed through
/sys/class/power_supply - systemd
- Python
3.10+ sqlite3CLI is optional, but useful for manual inspection/debugging
- Arch Linux AUR: batterylog-git packaged by Stetsed
- Reference AUR packaging for the current tree:
packaging/aur/PKGBUILD
- powertop - power usage realtime monitoring swiss army knife; can export reports
- powerstat - useful for measuring idle power usage; generates vmstat-style output and TUI histograms
- turbostat - state/temp/clock/power info for Intel CPUs
- battery-stats - long-term battery logging/capture
- batstat - small C app that does continuous logging of battery info into a sqlite DB
- uPower - D-Bus layer that stores power history/stats
- GNOME Power Statistics - GUI that uses uPower stats
- powir - Windows app, but lots of nice features
- SleepStudy - Windows built-in that also generates reports