Are you happy with your logging solution? Would you help us out by taking a 30-second survey? Click here


Plug and play battery percentage and icon indicator for Tmux.

Subscribe to updates I use tmux-battery

Statistics on tmux-battery

Number of watchers on Github 196
Number of open issues 6
Average time to close an issue about 2 months
Main language Shell
Average time to merge a PR 4 days
Open pull requests 9+
Closed pull requests 8+
Last commit almost 2 years ago
Repo Created over 5 years ago
Repo Last Updated over 1 year ago
Size 125 KB
Organization / Authortmux-plugins
Page Updated
Do you use tmux-battery? Leave a review!
View open issues (6)
View tmux-battery activity
View on github
Fresh, new opensource launches 🚀🚀🚀
Trendy new open source projects in your inbox! View examples

Subscribe to our mailing list

Evaluating tmux-battery for your project? Score Explanation
Commits Score (?)
Issues & PR Score (?)

Tmux battery status

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


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: :battery: (" " when not on OS X)
  • charging: :zap:
  • discharging: Moon icons depending on your battery level
  • attached but not charging: :warning:

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 :sunglasses:
  • set -g @batt_charging_icon :+1:
  • set -g @batt_attached_icon :neutral_face:
  • 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



tmux-battery open issues Ask a question     (View All Issues)
  • about 3 years Time to charge display
tmux-battery open pull requests (View All Pulls)
  • Chromebook Support for battery stat
  • Range formatting and graph
  • Optional highlight for battery level
  • Added commands that work with windows/cygwin
  • add support for UPower version 0.99.4
  • Adds support for changing bg color based on battery percentage.
  • adapted script files to also print colored fg sequence
  • Show time to charge battery on Mac OS
  • only show status when AC is offline
tmux-battery list of languages used
Other projects in Shell