Plug and play battery percentage and icon indicator for Tmux.
Switch branches/tags
Clone or download
hulkk and martinbeentjes fix time to charge display on mac, closes #28 (#68)
* fix time to charge display on mac, closes #28
* add charging colour to battery_status_fg
* fix incorrect colours when discharging
* change charging colour default to green
* add text to show charged when applicable instead of 0:00
Latest commit c2cd5c8 Aug 3, 2018

Tmux battery status

Enables displaying battery percentage and status icon in tmux status-right.


In order to read the battery status, this plugin depends on having either one of the following applications installed:

  • pmset
  • upower
  • acpi
  • termux-battery-status

In a normal situation one of these above should be installed on your system by default and thus it would not be necessary to install one of them.

Installation with Tmux Plugin Manager (recommended)

Add plugin to the list of TPM plugins in .tmux.conf:

set -g @plugin 'tmux-plugins/tmux-battery'

Hit prefix + I to fetch the plugin and source it.

If format strings are added to status-right, they should now be visible.

Manual Installation

Clone the repo:

$ git clone ~/clone/path

Add this line to the bottom of .tmux.conf:

run-shell ~/clone/path/battery.tmux

Reload TMUX environment:

# type this in terminal
$ tmux source-file ~/.tmux.conf

If format strings are added to status-right, they should now be visible.


Add #{battery_icon}, #{battery_percentage} #{battery_remain}, or #{battery_status_bg} format strings to existing status-right tmux option. Example:

# in .tmux.conf
set -g status-right '#{battery_status_bg} Batt: #{battery_icon} #{battery_percentage} #{battery_remain} | %a %h-%d %H:%M '


Battery full (for OS X):
battery full

Battery discharging, custom discharge icon:
battery discharging, custom icon

Battery charging:
battery charging

Battery remain:
battery remain

Battery fully charged:

Battery between 99% and 51% charged:

Battery between 50% and 16% charged:

Battery between 15% and dead:

This is done by introducing new format strings that can be added to status-right option:

  • #{battery_icon} - will display a battery status icon
  • #{battery_percentage} - will show battery percentage
  • #{battery_remain} - will show remaining time of battery charge
  • #{battery_status_bg} - will set the background color of the status bar based on the battery percentage
  • #{battery_status_fg} - will set the foreground color of the status bar based on the battery percentage
  • #{battery_graph} - will show battery percentage as a bar graph ▁▂▃▅▇

Changing icons

By default, these icons are displayed:

  • charged: "🔋" ("❇ " when not on OS X)
  • charging: "⚡️"
  • discharging: Moon icons depending on your battery level
  • attached but not charging: "⚠️"

You can change these defaults by adding the following to .tmux.conf (the following lines are not in the code block so that emojis can be seen):

  • set -g @batt_charged_icon "😎"
  • set -g @batt_charging_icon "👍"
  • set -g @batt_attached_icon "😐"
  • set -g @batt_full_charge_icon "🌕 "
  • set -g @batt_high_charge_icon "🌖 "
  • set -g @batt_medium_charge_icon "🌗 "
  • set -g @batt_low_charge_icon "🌘 "

Don't forget to reload tmux environment ($ tmux source-file ~/.tmux.conf) after you do this.

Warning: The battery icon change most likely will not be instant. When you un-plug the power cord, it will take some time (15 - 60 seconds) for the icon to change. This depends on the status-interval tmux option. Setting it to 15 seconds should be good enough.

Shortened remaining output

To shorten the output of #{battery_remain}, set the following variable:

set -g @batt_remain_short true

This will hide output if the battery is charging or charged, and shorten the time remaining (when discharging) to ~H:MM.

Tmux Plugins

This plugin is part of the tmux-plugins organisation. Checkout plugins as resurrect, logging, online status, and many more over at the tmux-plugins organisation page.

You might want to follow @brunosutic on twitter if you want to hear about new tmux plugins or feature updates.



  • Adam Biggs
  • Aleksandar Djurdjic
  • Bruno Sutic
  • Caleb
  • Evan N-D
  • Jan Ahrens
  • Joey Geralnik
  • Joseph
  • Martin Beentjes
  • Mike Foley
  • Ryan Frantz
  • Seth Wright
  • Tom Levens