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.

My first awesome

From awesome
Jump to: navigation, search

This little tutorial is for people who never used a tiling window manager before and don't have fancy hacking skills. We will explore the awesome world of awesome step by step and finally come up with a working desktop, providing some basic knowledge on how to configure awesome in the process. We will start with the default rc.lua that comes with awesome, play around a little and try to make it more beautiful and useful with widgets. For this tutorial you don't need any programming skills besides using a text editor.

Explore Awesome[edit]

I will assume that you properly installed awesome through your distro's package manager or compiled it from source. You should now add exec awesome to your ~/.xinitrc. As already mentioned, awesome provides a default config file which will be our starting point. You will usually find this rc.lua file in /etc/xdg/awesome/. Copy it to ~/.config/awesome/, and then start X. /!\ You should copy the whole directory, copying only the rc.lua will probably cause it to be ignored!

Move your Mouse to the upper left corner and click on the awesome logo. A little menu opens. Browse through the menu, then click the logo again to close it. Next to the awesome menu you see numbers 1-9. These are your tags (or desktops if you want). You can click on these to change them but nothing will happen because we have not opened any programs. On the top right you see the time/date and a symbol showing the current layout. You can also click on the symbol to change the active layout.

One of awesome's big advantages over other tiling window managers is its good mouse support. Awesome can act as a full floating window manager (almost like openbox) if you want. For this basic tutorial we will mainly focus on keyboard control, so let's learn some key bindings now.

Let's open a terminal: press Mod4+Enter. Mod4 is your "Windows key", the key between Ctrl and Alt. You can change the modkey if you want, but we'll get to that later. An xterm window will pop up. You can of course use your favourite terminal if you like. Again, more on that later. Now press Mod4+Shift+c to close the terminal. This is the command which lets you close any application. Awesome has a very elegant way to launch programs: press Mod4+r. Now you will see a Run: prompt in the status bar. Start anything you like, it also features Tab-completion!

Open another application. And another (another...) to see the tiling features. You can now press Mod4+Space to cycle through all the possible tiling (and floating) modes. Note that the icon in the upper right changes.

Also try Mod4+h, Mod4+l, Mod4+Shift+h and Mod4+Shift+l to resize Windows. You can also resize with Mod4+Button3 (right click). Mod4+f will make your current window fullscreen.

With Mod4+Number (1-9) you can browse through your tags. With Mod4+Shift+Number (1-9) you can send a window to a specific tag. Mod4+Left and Mod4+Right moves to the next tag in the specified direction.

Use Mod4+k and Mod4+j to toggle your focused client - moving your mouse will also do that if you haven't figured that out yet.

Mod4+Shift+q quits awesome, but don't do that now.

Read the man page for all key bindings (type man awesome in console), you will find many more useful ones. The man page is accessible through the awesome menu as well - press Mod4+w to bring it up.

Change the theme[edit]

Awesome has three themes you can choose from: default, sky and zenburn. There are also many user contributed themes you can find in Beautiful_themes.

To change the theme, open your rc.lua and edit this line near the beginning of the file:

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

For this tutorial, I will stick with the default theme. Read the Beautiful wiki to find out more about theming.

Change the background image[edit]

Your desktop background image is handled in your theme file (theme.lua in your theme's directory). To change it, edit this line in your theme file:

 theme.wallpaper = "/usr/share/awesome/themes/default/background.png"

Personalize your tags[edit]

To optimize our workflow, we now want to give names to our tags and set the specific tiling or floating mode for each one. Open your rc.lua and find the layouts section. It should look like this:

 layouts =

These are all possible tiling and floating options awesome has. Personally, I don't find all of the layouts useful (for example the spiral layout). You can comment them out using "--" to begin the line.

This is my personal opinion and may be different from yours, so carefully test each layout first. I will leave them unchanged for now.

Next, we want to name our tags. This is the default tag screen with numbers from 1 to 9:

 -- {{{ Tags
 -- Define a tag table which will hold all screen tags.
 tags = {}
 for s = 1, screen.count() do
     -- Each screen has its own tag table.
     tags[s] = awful.tag({ 1, 2, 3, 4, 5, 6, 7, 8, 9 }, s)
 -- }}}

Now we want to change the tag names and assign a specific layout to each one of them. By default, each tag has a floating layout. To change this, we define a specific tiling or floating layout for each tag. Replace the above with this code:

 -- {{{ Tags
 -- Define a tag table which will hold all screen tags.
 tags = {
   names  = { "main", "www", "skype", "gimp", "office", "im", 7, 8, 9 },
   layout = { layouts[1], layouts[2], layouts[1], layouts[5], layouts[6],
              layouts[12], layouts[9], layouts[3], layouts[7]
 for s = 1, screen.count() do
     -- Each screen has its own tag table.
     tags[s] = awful.tag(tags.names, s, tags.layout)
 -- }}}
screenshot with personalized tags
default rc.lua with personalized tags.

We use layouts to set the layout for each tag. The Number in "[]" is the number of the layout. In this example we set main to the tile layout, www to tile.left, im to floating, etc. Edit this as you like.

While we're at it, we can also change the default terminal, editor and assign the modkey to a different key:

 terminal = "xterm"
 editor = os.getenv("EDITOR") or "nano"
 modkey = "Mod4"

Change these settings to your liking, it's pretty self-explanatory and well-documented in the comments.

Save your rc.lua and restart awesome. Now your screen should resemble the screenshot on the right. Note that awesome is very sensitive to mistakes in your rc.lua. Even minor errors can crash it. You can save yourself some of the trouble caused by a bad configuration by checking for syntax errors with awesome -k.

"Mod4+ctrl+r" will restart awesome once your syntax check above passes.

Add widgets[edit]

Now we want to add some useful information to our status bar. This is done through widgets. Such as widgets for displaying memory usage, CPU temperature, battery status, etc. You can learn all about widgets, and how to create them on the Widgets in awesome page.

Some users created widget libraries applying the above principles, they try to simplify widget creation for others. Another advantage of widget libraries is the big number of system monitors they are distributed with, so you don't have to write your own. Many different libraries exist, but for this guide we will stick to the Vicious widget library, since it provides everything we need. For more advanced widgets that do more complex tasks, explore the Obvious widget library. Read the wiki entry how to install Vicious (it's easy).

Then, add

 local vicious = require("vicious")

to the beginning of your rc.lua. We now want a widget indicating our current network download and upload rate. Vicious provides a netwidget which is perfect for us.

Add this code to your rc.lua right after "-- {{{ Wibox" and before the "textclock" widget which is already there:

 -- {{{ Wibox
 --  Network usage widget
 -- Initialize widget, use widget({ type = "textbox" }) for awesome < 3.5
 netwidget = wibox.widget.textbox()
 -- Register widget
 vicious.register(netwidget,, '<span color="#CC9393">${eth0 down_kb}</span> <span color="#7F9F7F">${eth0 up_kb}</span>', 3)

To actually see the widget, we have to add it to our wibox. Add netwidget as indicated below:

   -- Widgets that are aligned to the right
   local right_layout = wibox.layout.fixed.horizontal()
   if s == 1 then right_layout:add(wibox.widget.systray()) end
   right_layout:add(netwidget) --ADD THIS

Now restart awesome to see the changes. "Mod4+ctrl+r".

You can also add some nice widget icons to further enhance the status bar. You can choose among many different icons sets on the Nice Icons page. In this example I used icons that were already on my system. To display icons, we first have to set them in our theme file. Open your theme file (theme.lua) and add the following:

 theme.widget_net = "/usr/share/icons/Adwaita/16x16/actions/go-down.png"
 theme.widget_netup = "/usr/share/icons/Adwaita/16x16/actions/go-up.png"

Don't forget to change your path, usually it should be ~/.config/awesome/icons/.

Next, add the following to your rc.lua, right where you put the widget:

 dnicon = wibox.widget.imagebox()
 upicon = wibox.widget.imagebox()

These lines goes after the theme definition.

Then add the icons to your Wibox, right before and after the "netwidget":

 -- Widgets that are aligned to the right
 local right_layout = wibox.layout.fixed.horizontal()
 if s == 1 then right_layout:add(wibox.widget.systray()) end                        
 right_layout:add(upicon) --ADD THIS
 right_layout:add(netwidget) --we added this earlier
 right_layout:add(dnicon) --ADD THIS

Restart with Mod4-Ctrl-r to see the final result.

screenshot of the final desktop with tags vicious widget
our final desktop with a network widget and icons

That's it. You now learned how to add widgets to your status bar. Read the Vicious wiki and the Readme file to learn how to add other widgets. You might also want to have a look at the Obvious widget package, which is also pretty straightforward to use.