This wiki will shut down!

Please note that this wiki will be made read-only and eventually be taken offline.

A replacement is being discussed at We'd be happy to have more input for that discussion and volunteers who help us migrate the content of this wiki to its replacement.


From awesome
Jump to: navigation, search

Note: Wicked has been deprecated in favour of the new Vicious library, which has more features and is updated more often.

Wicked is a lua library, which means you can require() it from within rc.lua, and set up all your widgets from inside the same config file, without having to run a separate program with separate config files.

Getting Wicked[edit]


Lenny x86[edit]

Awesome3 is available in sid. It has been backported to lenny. To use it, become root and:

  • Add the repository to /etc/apt/sources.list:
deb testing ware
  • And install it
apt-get update
apt-get upgrade
apt-get install awesome awesome-wicked
  • To get rid of the warning about the key signature add the key
gpg --keyserver --recv-key 974E7D68
gpg -a --export 974E7D68 | sudo apt-key add -

Its fingerprint should be: 0189 4F9A 5CFD 0242 5BEA 39E6 37A4 6DF5 974E 7D68

Arch Linux[edit]

If you are using Arch Linux, a PKGBUILD is already available over at the aur, get it here:


Server =
Server =

Source Mage GNU/Linux[edit]

All you have to do is "cast wicked"

Gentoo Linux[edit]

A gentoo package is available here wicked-9999.ebuild.


If you are not using Arch or would like to fetch the library separately, you can fetch it from the git repository at;a=summary.

Install it manually as such:

git clone git://
sudo cp wicked/wicked.lua /usr/share/awesome/lib/
sudo cp wicked/wicked.7.gz /usr/share/man/man7/

Setting Up Wicked[edit]

Setting up wicked is easy, just add the following line to the top of your rc.lua and you're ready to go.


Creating Widgets[edit]

Creating widgets is as simple as adding one function call to your rc.lua, below are a few examples you can use, for more information on possible widget types and options, see `man wicked` after installing wicked. Don't forget that you still need to add the widgets to the statusbar later.

Best to learn by example. Check out the author's current config.

Date Widget Example[edit]

The following widget displays the current date (output of the `date` command) in the statusbar.

datewidget = widget({
    type = 'textbox',
    name = 'datewidget'

    ' <span color="white">Date:</span> %c')

MPD `Now Playing` Example[edit]

The following widget is a simple widget showing the song that is currently playing through the Music Playing Daemon.

mpdwidget = widget({
    type = 'textbox',
    name = 'mpdwidget'

wicked.register(mpdwidget, wicked.widgets.mpd,
    ' <span color="white">Now Playing:</span> $1')

If you want to get a little more fancy and show the current song only when it's playing, change the register call to this:

wicked.register(mpdwidget, wicked.widgets.mpd, 
	function (widget, args)
		   if args[1]:find("volume:") == nil then
		      return ' <span color="white">Now Playing:</span> '..args[1]
                      return ''

Memory Usage Monitor Example[edit]

The following widget shows the current memory usage in percentage and in megabytes out of the total available.

memwidget = widget({
    type = 'textbox',
    name = 'memwidget'

wicked.register(memwidget, wicked.widgets.mem,
    ' <span color="white">Memory:</span> $1 ($2Mb/$3Mb)')

If you wanted to padd the values to 2, 4 and 4 digits respectively, you would use:

memwidget = widget({
    type = 'textbox',
    name = 'memwidget'

wicked.register(memwidget, wicked.widgets.mem,
    ' <span color="white">Memory:</span> $1 ($2Mb/$3Mb)',
nil, nil, {2, 4, 4})

Memory Usage Progressbar Example[edit]

The following widget displays the relative memory usage in a progressbar.

membarwidget = widget({
    type = 'progressbar',
    name = 'membarwidget',
    align = 'right'

membarwidget:properties_set('mem', {
width = 40,
height = 0.65,
gap = 0,
border_padding = 1,
border_width = 1,
ticks_count = 0,
ticks_gap = 0,
vertical = false

membarwidget:bar_properties_set('mem', {
bg = '#222222',
fg = '#285577',
fg_center = '#285577',
fg_end = '#285577',
fg_off = '#222222',
reverse = false,
min_value = 0,
max_value = 100

wicked.register(membarwidget, wicked.widgets.mem, '$1', 1, 'mem')

CPU Usage Example[edit]

The following widget displays the current CPU usage in percentages.

cpuwidget = widget({
    type = 'textbox',
    name = 'cpuwidget'

wicked.register(cpuwidget, wicked.widgets.cpu,
    ' <span color="white">CPU:</span> $1%')

CPU Usage Graph Example[edit]

The following widget displays a graph with your current CPU usage.

cpugraphwidget = widget({
    type = 'graph',
    name = 'cpugraphwidget',
    align = 'right'

cpugraphwidget.height = 0.85
cpugraphwidget.width = 45 = '#333333'
cpugraphwidget.border_color = '#0a0a0a'
cpugraphwidget.grow = 'left'

cpugraphwidget:plot_properties_set('cpu', {
    fg = '#AEC6D8',
    fg_center = '#285577',
    fg_end = '#285577',
    vertical_gradient = false

wicked.register(cpugraphwidget, wicked.widgets.cpu, '$1', 1, 'cpu')

Filesystem Usage Example[edit]

The following widget displays the space used out of the total space available on the partition mounted as /, as well as the usage percentage.

fswidget = widget({
    type = 'textbox',
    name = 'fswidget'

wicked.register(fswidget, wicked.widgets.fs,
    ' <span color="white">FS:</span> ${/ used}/${/ size} (${/ usep} used)', 120)

Network Interface Monitor Example[edit]

The following widget displays the current speed on eth0, as well as connection transfer totals. The final argument padds all values to at least 3 digits.

netwidget = widget({
    type = 'textbox',
    name = 'netwidget'

    ' <span color="white">NET</span>: ${eth0 down} / ${eth0 up} [ ${eth0 rx} //  ${eth0 tx} ]',
nil, nil, 3)

Battery Charge Example[edit]

The following widget displays the charge of your batteries:

batteries = 2

-- Function to extract charge percentage
function read_battery_life(number)
   return function(format)
             local fh = io.popen('acpi')
             local output = fh:read("*a")

             count = 0
             for s in string.gmatch(output, "(%d+)%%") do
                if number == count then
                   return {s}
                count = count + 1

-- Display one vertical progressbar per battery
for battery=0, batteries-1 do
   batterygraphwidget = widget({ type = 'progressbar',
                                 name = 'batterygraphwidget',
                                 align = 'right' })
   batterygraphwidget.height = 0.85
   batterygraphwidget.width = 8 = '#333333'
   batterygraphwidget.border_color = '#0a0a0a'
   batterygraphwidget.vertical = true
                                         { fg = '#AEC6D8',
                                           fg_center = '#285577',
                                           fg_end = '#285577',
                                           fg_off = '#222222',
                                           vertical_gradient = true,
                                           horizontal_gradient = false,
                                           ticks_count = 0,
                                           ticks_gap = 0 })

   wicked.register(batterygraphwidget, read_battery_life(battery), '$1', 1, 'battery')

Custom Widgets[edit]

You can create your own custom widgets by passing your own functions as the type parameter, using this, you can specify any arbitrary command to be outputted into a widget at any interval. The following example displays the volume from alsa (gotten by running the `amixer` command and parsing the output), every 4 seconds. (Note: requires alsa-utils)

volumewidget = widget({
    type = 'textbox',
    name = 'volumewidget'

function amixer_volume(format)
   local f = io.popen('amixer get PCM')
   local l = f:lines()
   local v = ''

   for line in l do
       if line:find('Front Left:') ~= nil then
            pend = line:find('%]', 0, true)
            pstart = line:find('[', 0, true)
            v = line:sub(pstart+1, pend)


   return {v}

wicked.register(volumewidget, amixer_volume, "<span color='white'>Volume</span>: $1", 4)

You can use the following to run any external script you might have written that collects data and outputs it:

mywidget = widget({
    type = 'textbox',
    name = 'mywidget'
function run_script()
    local filedescriptor = io.popen('')
    local value = filedescriptor:read()

    return {value}
-- Runs '' every 10 seconds and puts its output into the widget
wicked.register(mywidget, run_script, "$1", 10)

Awesome Freezing[edit]

Because awesome waits for the lua code to finish before resuming, running a slow script might bog down or freeze your awesome, you can use a background process and a temporary file to circumvent this. Use the code below to run a slow script you might have, without freezing awesome.

mywidget = widget({
    type = 'textbox',
    name = 'mywidget'

function run_slow_script (widget, args) 
   -- Read the temporary file left by the script
   local filedescriptor ='/tmp/script-temp-file')
   local value = nil

   if filedescriptor ~= nil then
      value = filedescriptor:read()


   if value == nil then
      return {''}
      return {value}

-- Runs '' every 10 seconds and puts its output into the widget
wicked.register(mywidget, run_slow_script, "$1", 10)

-- Register a timer to run every 9 seconds
awful.hooks.timer.register(9, mywidget_timer)

-- Use the timer to fill the temporary file
function mywidget_timer ()
   os.execute(' > /tmp/script-temp-file &')

Temporarily Suspending Wicked[edit]

If you are paranoid about battery usage, and you would prefer if wicked didn't run commands in the background all the time while you are on battery power, you could temporarily suspend all wicked updates by using "wicked.suspend()" in a keybinding. You can reactivate everything that was suspended by using "wicked.activate()".

Using awesome-client you could call these automatically, from, for example, a hal script. You would do this as such:

echo "wicked.suspend()" | awesome-client

Substitute suspend for activate where appropriate.