DEV Community

Cover image for Awesome: A Versatile Window Manager
Angad Sharma
Angad Sharma

Posted on

Awesome: A Versatile Window Manager

Awesome, or awesomewm, is a window manager which comes with a lot of features, right out of the box. It is written in the Lua programming language (almost), but configuring it does not require a lot of knowledge about the same. It is ideal for people starting out with window managers due to the fact that it is shipped with a lot of useful functionality which you would otherwise have to configure separately.


  • Awesomewm is very stable, fast and with a small codebase and footprint.
  • It uses tags instead of workspaces: windows can be placed on several tags and displayed at the same time.
  • It can be configured during runtime. Which means that any customization made does not require the service to be restarted.
  • It uses the asynchronous XCB library instead of the old, synchronous XLIB.
  • It comes with a very comprehensive application menu as well as a run menu.

Setting Up

Awesomewm is available on most source repositories. In addition, you can download the release and build it from source.

GitHub logo awesomeWM / awesome

awesome window manager


About Awesome

Awesome is a highly configurable, next generation framework window manager for X.

Building and installation

After extracting the dist tarball or cloning the repository, run:

sudo make install
Enter fullscreen mode Exit fullscreen mode

This will

  1. create a build directory at ./build,
  2. run cmake,
  3. build Awesome and
  4. install it to the default prefix path /usr/local.

Alternatively to the above, you can generate a .deb or .rpm package, for easy installation management:

make package
sudo dpkg -i awesome-x.y.z.deb
# or
sudo rpm -Uvh awesome-x.y.z.rpm
Enter fullscreen mode Exit fullscreen mode

Advanced options and testing

A full list of dependencies, more advanced build options, as well as instructions on how to use the test suite can be found here.

Installing current git master as a package receipts

Arch Linux AUR

sudo pacman -S --needed base-devel git
git clone
cd awesome-git
makepkg -fsri
Enter fullscreen mode Exit fullscreen mode


sudo apt build-dep awesome
git clone
cd awesome
make package
Enter fullscreen mode Exit fullscreen mode

The easiest way to get started (on debian based systems) is this:

sudo apt install awesome
Enter fullscreen mode Exit fullscreen mode

To run it, simple add the following line in your ~/.xsession file:

exec awesome
Enter fullscreen mode Exit fullscreen mode

Logout and log back in again, and boom! You are good to go.

Getting Started

When you login, awesomewm already has a default wallpaper set. Along with 9 tags on the menubar.

Alt Text

The default modifier in awesomewm is <Win>. To spawn a terminal, press <Win> + <Enter>. To get a list of all shortcuts, awesomewm provides a comprehensive cheat-sheet. Just press <Win> + s to view it.

Alt Text

To activate the application menu simply click on the top left corner of the menu bar, or right click anywhere. You will be greeted with something like this:

Alt Text

This menu can be used as a quick launcher, and even be configured to hold items which you want. In addition, <Win> + r can be used for spawning a run menu on the menubar. But I prefer dmenu instead.


In awesomewm, the status bar shows the number of active tags. Awesome gives you 9 tags that we can switch between. To do so, simply hit <Win> + [1-9]. For example <Win> + 6 will take you to the 6th workspace. Note that whatever was running on the previous workspace keeps on running there as usual.

To shift a currently running window to another tag, simply press <Win> + <Shift> + [1-9].


In awesomewm, movement between windows is done using <Win> + j|k and window resizing is done using <Win> + h|l.

Awesome offers different layouts per tag, which can be viewed on the left top corner of the menu bar and can be changed by clicking on the same:

Cornernew: Alt Text

Cornetnww: Alt Text

Cornerser: Alt Text

Cornersww: Alt Text

Dwindlew: Alt Text

Fairhw: Alt Text

Fairvw: Alt Text

Floatingw: Alt Text

Fullscreenw: Alt Text

Magnifierw: Alt Text

Maxw: Alt Text

Spiralw: Alt Text

Tilebottomw: Alt Text

Tileleftw: Alt Text

Tiletopw: Alt Text
Tilww: Alt Text


The awesome configuration lies in $XDG_CONFIG_HOME/awesome/rc.lua file. For example: /etc/xdg/awesome/rc.lua. By default awesomewm looks at the ~/.config/awesome/rc.lua file if it can find it. If it can't then it defaults to the aforementioned configuration.

To edit it, simply run the following command for getting started:

cp /etc/xdg/awesome/rc.lua ~/.config/awesome/
vim ~/.config/awesome/rc.lua
Enter fullscreen mode Exit fullscreen mode

After making any changes in rc.lua, awesomewm can be reloaded by pressing <Win> + <Ctrl> + r. In addition, the awesome-client can also be used for the same:

echo 'awesome.restart()' | awesome-client
Enter fullscreen mode Exit fullscreen mode

In this blog, we will be configuring the following things:

Changing Default Keybindings

The configuration file, rc.lua, contains a globalkeys option which is a table that stores keybindings.

Alt Text

The first section stores the modifier keys, eg: {modkey,}, {modkey, "Shift"} or {modkey, "Control"}. The second part can be used to add keys to be pressed along with the modifier, and the third part is the function to be performed when the particular binding is pressed.

Each keybinding is a part of a group and a description can be provided to go along with them. Adding a keybinding is as simple as copy-pasting the above binding and changing it with respect to what action you want to perform. For example, the following binding spawns firefox whenever I press modkey + b:

awful.key({modkey, }, "b", awful.spawn("firefox"))
Enter fullscreen mode Exit fullscreen mode

Adding Startup Processes

You can spawn processes or applications easily by using the following commands in rc.lua. To open these applications on startup, simply add the commands at the bottom of the configuration:

-- spawning a program

-- running a script inside a shell

-- setting wallpaper using nitrogen
awful.spawn.with_shell("nitrogen --set-scaled /usr/share/backgrounds/crysis.jpg")
Enter fullscreen mode Exit fullscreen mode

Adding and Removing Layouts

Lain is a library which provides a lot of useful commands for configuring widgets, adding layouts and other useful tweaks. Follow the repository to see how to use lain to its fullest:

GitHub logo lcpz / lain

Awesome WM complements


Layouts, widgets and utilities for Awesome WM 4.x

Author: Luca CPZ
Version: git
License: GNU-GPL2


Successor of awesome-vain, this module provides alternative layouts, asynchronous widgets and utility functions for Awesome.


Constructive criticism and suggestions are welcome.

If you want to create a pull request, make sure that:

  • Your code fits with the general style of the module. In particular, you should use the same indentation pattern that the code uses, and also avoid adding space at the ends of lines.
  • Your code its easy to understand, maintainable, and modularized. You should also avoid code duplication wherever possible by adding functions to or using lain.helpers. If something is unclear, or you can not write it in such a way that it will be clear, explain it with a comment.
  • You test your changes before submitting to make sure that your code works and…

Let us get started by importing lain in our rc.lua:

local lain = require("lain")
Enter fullscreen mode Exit fullscreen mode

To add a layout, namely centerwork, defined by lain, simply go to the awful.layout.layouts section and add lain.layout.centerwork. Other layouts can be removed from here, if you want to. The order of the layouts matter!

Alt Text

Adding Useless Gaps

Useless gaps refers to the space between windows that can be added for aesthetic purposes. For example:

Alt Text

These gaps can be configured at runtime by adding the following keybindings to globalkeys:

awful.key({ modkey, "Control" }, "=", function () lain.util.useless_gaps_resize(1) end),

awful.key({ modkey, "Control" }, "-", function () lain.util.useless_gaps_resize(-1) end),
Enter fullscreen mode Exit fullscreen mode

These commands will resize the gaps by a factor of 1 pixel every time we press modkey + Control + =|-.


Even though configuring awesomewm is not as easy as i3, it offers a lot of things right out of the box and is easy to get started with. Lua configuration is slightly challenging when it comes to adding additional libraries and trying to keep the code modular but there is a very supportive community and third party libraries for the same.

Awesome is a solid window manager for both beginners and experts, and I highly recommend it for both.

Judgement Rubric Rating
Simplicity of use ❤️ ❤️ ❤️ ❤️
Simplicity of Configuration ❤️ ❤️
Learning curve (lesser is better) ❤️ ❤️ ❤️
Productivity ❤️ ❤️ ❤️ ❤️
Fun ❤️ ❤️


Top comments (10)

averyfreeman profile image
Avery Freeman • Edited

@l04db4l4nc3rzoman So after testing all these window managers, which one do you use? Also, I've noticed many of the projects are stale, have not had any updates for several years - are they still surviving OK despite having little to no recent maintenance?

l04db4l4nc3r profile image
Angad Sharma

I have settled on instantWM for my personal computer for now. I love the animation features and out of the box click support (sometimes you need it). I'm waiting for kronkite to support Wayland so that I can use tiling on KDE Plasma. On my work computer (which is a MacBook ☹️), I use a tiling application called amethyst. But that's content for another blog. Even after not receiving an update for several years, most of them are going strong due to the fact that X11 hasn't got a major update either. The only downside is that likely none of these WMs will make it to Wayland, and that's a sad thing.

averyfreeman profile image
Avery Freeman

Cool, thanks for letting me know, I'll definitely check all that stuff out (!) I'm a plasma fan, but had issues getting settings sync to work on QT platforms as of late, so fell back to gnome for sheer compatibility reasons (guh, I wish it wasn't their default). If instantWM uses GTK+ it might be close enough not to cause any issues.

pbkarlsson profile image
Philip Karlsson

Nice series, any plans on a post about bspwm?

l04db4l4nc3r profile image
Angad Sharma

Thanks Philip, bspwm looks interesting. I might do a blog on it soon :)

l04db4l4nc3r profile image
Angad Sharma
pbkarlsson profile image
Philip Karlsson

Great :D

r4vll profile image

Loving all the series Angad!

l04db4l4nc3r profile image
Angad Sharma

Thanks raul 😄

vivekascoder profile image

Hey BTW, why do you are using polybar in it?