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

Beautiful is a lua library that allows you to theme awesome using an external file, it becomes very easy to dynamically change your whole awesome colours and wallpaper without changing your rc.lua.

It has been written for people who enjoy changing their colours/wallpaper from time to time without editing their rc.lua, store old colours values, write new ones etc.

Beautiful is designed for awesome 3 only.

Setting up Beautiful[edit]

First, you must use:

beautiful = require('beautiful')

to include the library in your configuration file.

Then, you will have to initialize Beautiful with a theme file using:


A default theme file is provided and is located at /usr/local/share/awesome/themes/default/theme.lua or /usr/share/awesome/themes/default/theme.lua, depending on your distro.

The theme file is essentially another Lua file which returns a table with key-value pairs (such as 'bg_normal' = '#222222').

Awful can handle Beautiful avoiding you to pass plenty arguments to awful's functions in your configuration file.

Now you are ready to go. Basically, you can now replace each colour variable definition by (for instance):

bg_focus = beautiful.bg_focus
You can access all keys in the currently registered theme as

To start making your own theme, run:

cp -r /usr/local/share/awesome/themes ~/.config/awesome/


cp -r /usr/share/awesome/themes ~/.config/awesome/

Don't forget to change the theme file path in your rc.lua:

beautiful.init(awful.util.getdir("config") .. "/themes/default/theme.lua")


Custom variables[edit]

You should never change default variable names (font, bg_normal and stuff) as those names are used by awful, this would break your configuration file. But you can add as many new variables as you wish.

For instance, if you wish to theme your widgets you can use:

fg_off_widget = #ffffff
fg_widget = #000000
fg_end_widget = #ff0000

And in your rc.lua:

my_widget:bar_properties_set("data_name", {
   border_color = beautiful.border_normal,
   fg_off = beautiful.fg_off_widget,
   fg = beautiful.fg_widget,
   fg_end = beautiful.fg_end_widget

In this example we mixed both default theme variables (beautiful.border_normal) and custom variables (beautiful.*_widget). You can imagine to set your own specific icons and stuff. But be aware that if you start using custom variables in your rc.lua, every theme files you have should define those variables too, otherwise it will break your configuration file.

Setting up your wallpaper[edit]

Beautiful can handle your wallpaper, thus you don't need to set it up in your .xinitrc or .xsession files. This allows you to have a specific wallpaper for each theme. If you take a look at the default theme file you'll see a wallpaper_cmd key, the given command is executed when beautiful.init("path_to_theme_file") is run. You can put here you own command or remove/comment the key if you don't want Beautiful to interfere with your wallpaper business.

For instance, if you use fbsetbg to set your wallpaper, you can write:

wallpaper_cmd = fbsetbg -f .config/awesome/themes/awesome-wallpaper.png

If you have multiple screens and you want a different wallpaper on each one, you can use:

wallpaper_cmd = { "fbsetbg -f .config/awesome/themes/awesome-wallpaper1.png",
                  "fbsetbg -f .config/awesome/themes/awesome-wallpaper2.png" }


Usage of symlinks[edit]

It has been said that Beautiful avoids you to edit your rc.lua file when you want to change your awesome theme, actually that is not true as you must change the path to your theme file in the beautiful.init() function. But you can make a symbolic link of your current theme and use it to initialize Beautiful, thus you'll only have to point that link to another file and restart awesome (ctrl+mod4+r by default) to change theme.

Now you can write a function to feed a popup to instantly change your theme, we assume that your theme path is set like:

beautiful.init(awful.util.getdir("config") .. "/current_theme/theme.lua")

Now write:

mythememenu = {}

function theme_load(theme)
   local cfg_path = awful.util.getdir("config")

   -- Create a symlink from the given theme to /home/user/.config/awesome/current_theme
   awful.util.spawn("ln -sfn " .. cfg_path .. "/themes/" .. theme .. " " .. cfg_path .. "/current_theme")

function theme_menu()
   -- List your theme files and feed the menu table
   local cmd = "ls -1 " .. awful.util.getdir("config") .. "/themes/"
   local f = io.popen(cmd)

   for l in f:lines() do
	  local item = { l, function () theme_load(l) end }
	  table.insert(mythememenu, item)


-- Generate your table at startup or restart

-- Modify your awesome menu to add your theme sub-menu
myawesomemenu = {
   { "manual", terminal .. " -e man awesome" },
   { "edit config", editor_cmd .. " " .. awful.util.getdir("config") .. "/rc.lua" },
   { "themes", mythememenu },
   { "restart", awesome.restart },
   { "quit", awesome.quit }

Share your themes[edit]

Do not hesitate to share your own themes with the awesome awesome's community!