Setting up Awesome WM on Ubuntu

Ubuntu is a popular and easy-to-use Linux distro, but its default window manager can become frustrating and inefficient if you’re a keyboard-driven programmer or have a large monitor that you want to use effectively. Some people have heard of tiling window managers such as XMonad, but are intimidated by the arduous setup and configuration process. Admittedly, most window mangers have pretty poor documentation, and it took me many hours of effort to get Awesome (my tiling window manager of choice) working properly on my system. I’ve written this little guide to help new users copy my Awesome-on-Ubuntu setup, so you can take advantage of my learning process and start using a tiling window manager with minimal hassle.

This guide was written for Ubuntu 16.04 and awesome 3.5.6 (the version of awesome that ships in the Ubuntu 16.04 repositories). Suggestions and bugfixes are welcome.


  1. Install awesome with sudo apt-get install awesome
  2. Install the “delightful” widget pack by following the instructions on this website. These will also instruct you to install some other awesome modules, such as Vicious and freedesktop; you should do this.
  3. If you want to use the Weather widget (I do in my configuration, so if you copy my configuration exactly you should do this), you’ll need to patch a bug that ships with awesome’s METAR parser. Replace ~/.config/awesome/metar.lua with this file, which fixes a line that calls the convert_pressure function incorrectly.

Setting up a Gnome Session

Now that awesome is installed, we need to set up a “GNOME Session” that will launch awesome as its window manager. This is what allows you to still use Ubuntu utilities like GNOME keyring and the Unity system settings panel while running awesome. It also prevents GTK+ applications (like Firefox) from reverting to an ugly-as-hell “default theme;” they rely on the GNOME Settings Daemon to provide all their style information.

  1. Install gnome-settings-daemon if it isn’t already, with sudo apt-get install gnome-settings-daemon

  2. Put this file in /usr/share/xsessions/ as awesome-gnome.desktop. You’ll need root permissions to put it there, and it needs to be owned by root.

  3. Put this file in /usr/share/gnome-session/sessions/ as awesome.session. This is also a file owned by root.

  4. Put this file in /usr/share/applications/ as awesome.desktop. This is also a file owned by root.

  5. Copy the following files from /etc/xdg/autostart/ to ~/.config/autostart/:

    • gnome-settings-daemon.desktop
    • gnome-keyring-*.desktop (there are several files that match this pattern, all related to the GNOME keyring service)
    • gnome-screensaver.desktop, optionally, if you use GNOME screensaver rather than Xscreensaver

    In your home-directory version of each file, find the line


    and change it to

    OnlyShowIn=GNOME;Unity;Awesome GNOME;

    This will allow these services to run in the session named “Awesome GNOME,” which is the session we created with the file awesome-gnome.desktop. These services normally disable themselves when they find that the current GNOME session’s name is not in their “OnlyShowIn” list.

  6. Go to /usr/share/applications/ and edit gnome-control-center.desktop. You’ll find that it has the same “OnlyShowIn” line as the files from autostart. Once again, change



    OnlyShowIn=GNOME;Unity;Awesome GNOME;
  7. For every file in /usr/share/applications/ that matches the pattern gnome-*-panel.desktop (you can see them with ls | grep gnome.*panel.desktop), you also need to add Awesome GNOME; to the OnlyShowIn line. You can do this quickly by running the following sed script:

    sudo sed '/OnlyShowIn/ s/$/ Awesome GNOME;/' \

Configuring Awesome

Most of awesome’s configuration is done through the file rc.lua, but colors and wallpapers are set in a “theme” file. If you start with my config and theme file, everything should mostly work sensibly out of the box, with a few user-specific exceptions.

  1. Put this file in ~/.config/awesome/ and open it for editing.
  2. Find the section that starts with the comment “Delightful widget configuration” (should be on line 107), and change the user and password settings under [delightful.widgets.imap] to the username and password for your e-mail account. You can also change the command setting to specify a different mail program to launch when you click the widget, such as thunderbird if you use Thunderbird. (I use Evolution). Also, if you don’t live in Ithaca, change the city parameter under [] to the city you live in, and change the corresponding command to open a browser pointing to your local weather forecast.
  3. Download the “darklooks” theme by following the instructions on this page.
  4. Replace ~/.config/awesome/themes/Darklooks/theme.lua with this file to get my improvements to the theme; they make it more readable and make the “focus highlight” brighter (so it’s easier to see what window is active). Open the file and change line 50, theme.wallpaper, to specify the location of the wallpaper you’d like to use.
  5. If you want the clock in your status bar to display 12-hour time instead of 24-hour time, replace ~/.config/awesome/delightful/widgets/datetime.lua with this file, which changes line 37 to specify a 12-hour format instead of a 24-hour format. If you want, you can customize this to any date/time string you want; the textclock format string uses the same placeholders that strftime() understands.

At this point you should be done. Restart your computer, and when you reach the login prompt again, click the session chooser (the little white button next to the username/password box) and choose “Awesome GNOME” instead of “Unity.” Once awesome is loaded, you can press WinKey-Enter to open a terminal and type “man awesome” if you aren’t familiar with the keyboard shortcuts.