Skip to content
universal status bar content generator
C CMake Shell Lua C++
Branch: master
Clone or download
shdown plugins/battery-linux: introduce 'use_energy_full_design', fix a bug
The bug was that, in Lua, 's ~= 0', where 's' is a string, always
returns false, and 'p.power_now' was a string. Oops.
Latest commit 4074d05 Dec 24, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
DOCS Replace's with README.rst's; generate mans from them Nov 15, 2018
contrib Simplify the `battery-linux` plugin Jun 22, 2019
examples examples/{i3,dwm}/time-battery-combined.lua: handle "Not charging"... Jun 30, 2019
libls Don't rely on that LS_VECTOR_OF(T) is allocated as if with malloc() Oct 24, 2019
plugins plugins/battery-linux: introduce 'use_energy_full_design', fix a bug Dec 24, 2019
tests New functions to simplify marshalling of numbers Jul 2, 2019
.gitignore Replace's with README.rst's; generate mans from them Nov 15, 2018
.travis.yml plugins/wireless: add Jan 3, 2019
CMakeLists.txt Remove plugins/{ipaddr,wireless} in favor of plugins/network-linux Jan 21, 2019
LICENSE.txt Initial commit Jan 10, 2017 add “Acknowledgements” section Jan 22, 2019 try as well Nov 15, 2018 use $RELEASE_MSG for release message May 3, 2017

Build Status

luastatus is a universal status bar content generator. It allows you to configure the way the data from event sources is processed and shown, with Lua.

Its main feature is that the content can be updated immediately as some event occurs, be it a change of keyboard layout, active window title, volume or a song in your favorite music player (provided that there is a plugin for it) — a thing rather uncommon for tiling window managers.

Its motto is:

No more heavy-forking, second-lagging shell-script status bar generators!



Above is i3bar with luastatus with Bitcoin price, time, volume, and keyboard layout widgets.

Key concepts


In short:

  • plugin is a thing that decides when to call the callback function widget.cb and what to pass to it;
  • barlib (bar library) is a thing that decides what to with values that widget.cb function returns;
  • there are also derived plugins, which are plugins written in Lua that use regular plugins.


ALSA volume widget:

widget = {
    plugin = 'alsa',
    opts = {
        channel = 'PCM'
    cb = function(t)
        if t.mute then
            return {full_text = '[mute]', color = '#e03838'}
            local percent = (t.vol.cur - t.vol.min)
                          / (t.vol.max - t.vol.min)
                          * 100
            return {full_text = string.format('[%3d%%]', math.floor(0.5 + percent)),
                    color = '#718ba6'}
    event = function(t)
        if t.button == 1 then     -- left mouse button
            os.execute('urxvt -e alsamixer &')

GMail widget (uses the derived plugin imap):

-- Expects 'credentials.lua' to be present in the current directory; it may contain, e.g.,
--     return {
--         gmail = {
--             login = 'john.smith',
--             password = 'qwerty'
--         }
--     }
credentials = require 'credentials'
widget = luastatus.require_plugin('imap').widget{
    host = '',
    port = 993,
    mailbox = 'Inbox',
    use_ssl = true,
    timeout = 2 * 60,
    handshake_timeout = 10,
    login =,
    password =,
    error_sleep_period = 60,
    cb = function(unseen)
        if unseen == nil then
            return nil
        elseif unseen == 0 then
            return {full_text = '[-]', color = '#595959'}
            return {full_text = string.format('[%d unseen]', unseen)}
    event = [[                    -- separate-state event function
        local t = ...             -- obtain argument of this implicit function
        if t.button == 1 then     -- left mouse button
            os.execute('xdg-open &')

See more examples here.


cmake . && make && sudo make install

You can specify a Lua library to build with: cmake -DWITH_LUA_LIBRARY=luajit .

You can disable building certain barlibs and plugins, e.g. cmake -DBUILD_PLUGIN_XTITLE=OFF .

You can disable building man pages: cmake -DBUILD_DOCS=OFF .

Getting started

It is recommended to first have a look at the luastatus' man page.

Then, read the barlib's and plugins' documentation, either via directly viewing barlibs/<name>/README.rst and plugins/<name>/README.rst files, or via installing the man pages and reading luastatus-barlib-<name>(7) and luastatus-plugin-<name>(7).

Barlib-specific notes on usage follow.


luastatus-i3-wrapper should be specified as the i3bar's status command in the i3 config, e.g.:

bar {
    status_command cd ~/.config/luastatus && exec luastatus-i3-wrapper -B no_separators time-battery-combined.lua alsa.lua xkb.lua

See also README for i3 and examples for i3.


luastatus should simply be launched with -b dwm, e.g.:

luastatus -b dwm -B separator=' • ' alsa.lua time-battery-combined.lua

See also README for dwm and examples for dwm.


lemonbar should be launched with luastatus-lemonbar-launcher, e.g.:

luastatus-lemonbar-launcher -p -B#111111 -p -f'Droid Sans Mono for Powerline:pixelsize=12:weight=Bold' -- -Bseparator=' ' alsa.lua time-date.lua

See also README for lemonbar and examples for lemonbar.


luastatus should be launched with luastatus-stdout-wrapper; or write your own wrapper, see e.g. the wrapper for launching dvtm with luastatus.

See also README for stdout and and examples for stdout.

Supported Lua versions

  • 5.1
  • LuaJIT, which is currently 5.1-compatible with "some language and library extensions from Lua 5.2"
  • 5.2
  • 5.3
  • 5.4 (work1, work2 pre-release versions)

Reporting bugs, requesting features, suggesting patches

Feel free to open an issue or a pull request.

Migrating from older versions

See the Migration Guide.


  • I would like to thank wm4 for developing mpv, which, also being a “platform” for running Lua scripts, served as an inspiration for this project.
You can’t perform that action at this time.