FAQ

General

Why call it Awesome?

The name Awesome comes from the English word awesome often used by the character Barney Stinson from the TV series HIMYM.

Common issues

My screens are not configured correctly

Awesome is a window manager, not a desktop environment. To configure your screens, the xrandr tool or various GUI applications exist. For more information, refer to the Arch Linux wiki.

There is a noticeable delay with inputs

There are two common causes for this:

The first is a display driver issue where painting on the screen takes long time. All input events (keyboard and mouse) are processed in the main thread. The drawing is also locking the main thread to avoid artifacts and race ccontiditions. If there is a delay with the painting, it will delay the inputs. The solution to this problem is using a compositing manager such as compton or the older xcompmgr. This will move painting to another process and fully mitigate the issue.

The second one is when using io.popen or other blocking functions in rc.lua and most commonly manifests itself as occasional freezes instead of a generic delay. Do not use such functions and prefer awful.spawn.easy_async, awful.widget.watch or the GIO async API. Even if you think a command is fast enough and won't impact the main event loop iteration time, you are wrong. Every calls to io.open are impacted by the system iowait queue and can spend hundreds of milliseconds blocked before being executed. Note that some common widget or probe libraries do not follow this advice currently and are known to cause input lag on some systems (but not all).

In both case, a warning like:

2018-01-23 09:58:48 W: awesome: a_glib_poll:432: Last main loop iteration took 14.416777 seconds! Increasing limit for this warning to that value

will be printed to warn you about the issue.

The applications look ugly

Awesome is a window manager, not a desktop environment. It does not provide a theme daemon. For more information about how to manage the look and feel of applications, refer to the Arch Linux Wiki.

Awesome doesn't show up on my login screen

There have been cases where Awesome wasn't correctly registered with the display manager, usually due to a missing .desktop file.

To fix such issues, copy awesome.desktop from the root of the repository to /usr/share/xsessions/.

curl https://raw.githubusercontent.com/awesomeWM/awesome/master/awesome.desktop | sudo tee /usr/share/xsessions/awesome.desktop

If you installed Awesome through a package manager, you might want to check if the package includes that file and, if not, notify the maintainer to add it as appropriate.

Configuration

How to change the default window management layout?

In the default configuration file one layout is set for all tags, it happens to be the floating layout. You can change that by editing your tag creation loop in the rc.lua:

-- Each screen has its own tag table.
awful.tag({ "1", "2", "3", "4", "5", "6", "7", "8", "9" }, s, awful.layout.layouts[1])

Notice that all tags will use the 1st layout from your layouts table, which is defined right before tags are created. Just change the layout number in order to use another window management layout.

How to change the name and layout per tag?

You can modify your tag section, there are many possible implementations, here is a simple one:

At the beginning of rc.lua:

layouts = awful.layout.layouts
tags = {
  names  = { "www", "editor", "mail", "im", "rss", 6, 7, "rss", "media"},
  layout = { layouts[2], layouts[1], layouts[1], layouts[4], layouts[1],
             layouts[6], layouts[6], layouts[5], layouts[6]
}}

Then later to create tags:

tags[s] = awful.tag(tags.names, s, tags.layout)

How to setup different tags and layouts per screen?

Another demonstration for your tag section:

At the beginning of rc.lua:

layouts = awful.layout.layouts
tags = {
  settings = {
    { names  = { "www", "editor", "mail", "im" },
      layout = { layouts[2], layouts[1], layouts[1], layouts[4] }
    },
    { names  = { "rss",  6, 7,  "media" },
      layout = { layouts[3], layouts[2], layouts[2], layouts[5] }
}}}

Then later to create tags:

tags[s] = awful.tag(tags.settings[s.index].names, s, tags.settings[s.index].layout)

How to show only non-empty tags?

You can use a filter when creating taglist.

Possible filters:

awful.widget.taglist.filter.all - default, show all tags in taglist
awful.widget.taglist.filter.noempty - show only non-empty tags in taglist (like dynamic tags)
awful.widget.taglist.filter.selected - show only selected tags in taglist

To show only non-empty tags on taglist:

mytaglist[s] = awful.widget.taglist(s, awful.widget.taglist.filter.noempty, mytaglist.buttons)

How to autostart applications?

The traditional way is to use the ~/.xinitrc file.

How to lock the screen when I am away?

You can use any screen locking utility: xlock, xscreensaver, slock, kscreenlocker...

Example key binding for your globalkeys:

awful.key({ modkey }, "F12", function () awful.spawn{ "xlock" } end)

How to execute a shell command?

If you want to execute a shell command or need to execute a command that uses redirection, pipes and so on, do not use the awful.spawn function but awful.spawn.with_shell. Here is an example:

awful.key({ modkey }, "F10", function () awful.spawn.with_shell("cal -m | xmessage -timeout 10 -file -") end)

On zsh, any changes to $PATH you do in ~/.zshrc will not be picked up (because this is only run for interactive shells). Use ~/.zshenv instead to make additions to the path you want to use in Awesome.

How to remove gaps between windows?

You can add size_hints_honor = false to the properties section in your ruled.client.rules table in your rc.lua. It will match and apply this rule to all clients.

See the mailing list archive for more info about what size hints are.

This might cause flickering with some non-ICCCM conforming applications (e.g. Lilyterm) which try to override the size that the window manager assigned them.

How to add an application switcher?

You can use the Clients Menu as an application switcher. By default it will open if you right-click on your taskbar, but you may also bind it to a key combination. Here is an example, toggled by "Alt + Esc", that you can add to your globalkeys:

awful.key({ "Mod1" }, "Escape", function ()
    -- If you want to always position the menu on the same place set coordinates
    awful.menu.menu_keys.down = { "Down", "Alt_L" }
    awful.menu.clients({theme = { width = 250 }}, { keygrabber=true, coords={x=525, y=330} })
end),

How to control titlebars?

To disable titlebars on all clients remove the titlebars_enabled=true from the ruled.client.rules table in your config. If you want a titlebar only on certain clients, you can use ruled.client to set this property only for certain clients.

How to toggle titlebar visibility?

You can use a clientkeys binding.:

awful.key({ modkey, "Shift" }, "t", awful.titlebar.toggle),

How to toggle wibox visibility?

Add the following key binding to your globalkeys:

awful.key({ modkey }, "b", function ()
    mouse.screen.mywibox.visible = not mouse.screen.mywibox.visible
end),

How to toggle clients floating state?

The default rc.lua already has a key binding for this, it is "Mod4 + Control + Space". You can easily change it to something easier like "Mod4 + f" or "Mod4 + Shift + f".

awful.key({ modkey, "Shift" }, "f",  awful.client.floating.toggle ),

Why some floating clients can not be tiled?

If some of your applications (i.e. Firefox, Opera...) are floating but you can't tile them, and they behave weird (can not be tagged, are always on top...) do not panic. They are merely maximized from your last window manager, or from their last invocation. The default key binding to toggle maximized state is "Mod4 + m".

You can ensure no application ever starts maximized in the first rule of your ruled.client.rules table, which applies to all clients, by adding:

-- Search for this rule,
keys = clientkeys,

-- add the following two:
maximized_vertical   = false,
maximized_horizontal = false,

How to move and resize floaters with the keyboard?

You can use the client:relative_move function. The following clientkeys example will move floaters with "Mod4 + Arrow keys" and resize them with "Mod4 + PgUP/DN" keys:

awful.key({ modkey }, "Next",  function (c) c:relative_move( 20,  20, -40, -40) end),
awful.key({ modkey }, "Prior", function (c) c:relative_move(-20, -20,  40,  40) end),
awful.key({ modkey }, "Down",  function (c) c:relative_move(  0,  20,   0,   0) end),
awful.key({ modkey }, "Up",    function (c) c:relative_move(  0, -20,   0,   0) end),
awful.key({ modkey }, "Left",  function (c) c:relative_move(-20,   0,   0,   0) end),
awful.key({ modkey }, "Right", function (c) c:relative_move( 20,   0,   0,   0) end),

How to resize tiled clients?

You can use the awful.tag.incmwfact function to resize master clients and awful.client.incwfact function to resize slave clients. The following globalkeys example demonstrates this:

awful.key({ modkey }, "l",          function () awful.tag.incmwfact( 0.05) end),
awful.key({ modkey }, "h",          function () awful.tag.incmwfact(-0.05) end),
awful.key({ modkey, "Shift" }, "l", function () awful.client.incwfact(-0.05) end),
awful.key({ modkey, "Shift" }, "h", function () awful.client.incwfact( 0.05) end),

How to change Awesome configuration while it's running?

You can modify rc.lua, but you have to restart Awesome for changes to take effect. The default keybinding for restarting Awesome is "Mod4 + Control + r".

How to find window's class and other identifiers?

You can use the xprop utility, you are interested in WM_CLASS and WM_NAME from its output:

$ xprop WMCLASS WMNAME

When the cursor changes to "+" click on the client of interest. From the terminal output you can use the following to match clients in Awesome:

WM_CLASS(STRING) = "smplayer", "Smplayer"
                    |           |
                    |           |--- class
                    |
                    |--- instance

WM_NAME(STRING) = "SMPlayer"
                   |
                   |--- name

You can use the above identifiers (instance, class and name) in your ruled.client.rules table to do matching, tagging and other client manipulation. See the next FAQ answer for some examples.

How to start clients on specific tags and others as floating?

You can add matching rules to your ruled.client.rules table. The default rc.lua already has several examples, but some more can be found in the documentation.

How to start clients as slave windows instead of master?

You can set windows to open as slave windows by setting rule to match all clients:

-- Start windows as slave
{ rule = { }, properties = { }, callback = awful.client.setslave }

How to use a keycode in a keybinding?

You can use the format #XYZ for keycodes in your bindings. The following example shows a mapped multimedia/extra key, that's why the modifier is not present (but it could be):

awful.key({}, "#160", function () awful.spawn("kscreenlocker --forcelock") end),

How to add a keyboard layout switcher?

The wibox.widget.keyboardlayout is a widget that shows the current keyboard layout and allows to change it by clicking on it.

How to make windows spawn under the mouse cursor?

In the default ruled.client-rule, the following placement is specified:

placement = awful.placement.no_overlap+awful.placement.no_offscreen

You can prepend awful.placement.under_mouse to this:

placement = awful.placement.under_mouse+awful.placement.no_overlap+awful.placement.no_offscreen

How to switch to a specific layout in a keybinding?

You can call the awful.layout.set() function, here's an example:

awful.key({ modkey }, "q", function () awful.layout.set(awful.layout.suit.tile) end),

Why are new clients urgent by default?

You can change this by redefining awful.permissions.activate(c) in your rc.lua. If you don't want new clients to be urgent by default put this in your rc.lua:

client.disconnect_signal("request::activate", awful.permissions.activate)
function awful.permissions.activate(c)
    if c:isvisible() then
        client.focus = c
        c:raise()
    end
end
client.connect_signal("request::activate", awful.permissions.activate)

Usage

How to use this thing?

Default binding to open a terminal is "Mod4 + Enter" (where Mod4 is usually the "Windows" key). You can also click on the desktop background with the right button, to open the Awesome menu.

From there you can proceed to open man awesome which has a good guide, including the list of default keybindings.

Layouts

With the default config, you can cycle through window layouts by pressing "mod4+space" ("mod4+shift+space" to go back) or clicking the layout button in the upper right corner of the screen.

How to restart or quit Awesome?

You can use the keybinding "Mod4+Ctrl+r" or by selecting restart in the menu. You could call awesome.restart either from the Lua prompt widget, or via awesome-client:

$ awesome-client 'awesome.restart()'

You can also send the SIGHUP signal to the Awesome process. Find the PID using ps, pgrep or use pkill:

$ pkill -HUP awesome

You can quit Awesome by using "Mod4+Shift+q" keybinding or by selecting quit in the menu. You could call awesome.quit either from the Lua prompt widget, or by passing it to awesome-client.

$ echo 'awesome.quit()' | awesome-client

You can also send the SIGINT signal to the Awesome process. Find the PID using ps, pgrep or use pkill:

$ pkill -INT awesome

Why Awesome doesn't use my own brand new config?

If Awesome cannot find $XDG_CONFIG_HOME/awesome/rc.lua, or fails to load it, it falls back to using /etc/xdg/awesome/rc.lua (you haven't edited it, I hope, have you?). Even if awesome --check hasn't reported any error, it only means that your rc.lua is syntactically correct, but absence of runtime errors is not guaranteed. Moreover, Awesome could apply half of your config then encounter an error and load stock one, and that could lead to bizarre result, like two sets of tags. See the next entry on how to find out where the problem lurks.

Where are logs, error messages or something?

When hacking your own configuration, something inevitably would go wrong. Awesome prints error messages to its stderr stream. When run with usual `$ startx`, it'd be printed right in tty. If you use something more complicated (some kind of DM, like kdm or gdm), stderr is usually redirected somewhere else. To see where, run the following command:

$ ls -l /proc/$(pidof awesome)/fd/2

There's handy way to run Awesome and redirect both its standard output and error streams to files:

exec /usr/bin/awesome >> ~/.cache/awesome/stdout 2>> ~/.cache/awesome/stderr

If you put it into .xinitrc (for startx) or ~/.xsession, you'll be able to watch (with tail -f) everything right from Awesome.

Why does Mod4 "swallow" succeeding key presses?

On some systems xkb by default maps the left windows key to "Multi_key" (at least in us and de layouts). Multikey is an xkb feature which may be used to access uncommon symbols by pressing Multikey and then (consecutively) two "normal" keys. The solution is to remap your windows key to mod4 and remove the Multikey mapping. This can be done by including "altwin(leftmetawin)" in the xkb keyboard description xkbsymbols line.

#!/bin/bash
xkbcomp - $DISPLAY<<EOF
xkb_keymap {
xkb_keycodes  { include "evdev+aliases(qwertz)"};
xkb_types     { include "complete"};
xkb_compat    { include "complete"};
xkb_symbols   { include "pc+de(nodeadkeys)+inet(evdev)+group(alt_shift_toggle)+level3(ralt_switch)+altwin(left_meta_win)+capslock(escape)"    };
xkb_geometry  { include "pc(pc104)"};
};
EOF

I upgraded from Awesome 3 to Awesome 4 and multiscreen broke. Why is that?

Awesome 4.0+ support dynamic screen plugging and unplugging without restarting.

This avoids losing your tags, layout and focus history. Olders rc.lua were not designed to support such changes and assumed Awesome would restart. To add multi-screen support to existing configs, see how awful.screen.connect_for_each_screen is used in the new rc.lua or rebuild your config on a newer revision of rc.lua.

Can I have a client or the system tray on multiple screens at once?

No. This is an X11 limitation and there is no sane way to work around it.

Can a client be tagged on different screens at once?

While it is not impossible to partially implement support for this, many Awesome components frequently query the client's screen. Since a client can only be in one screen at once, this will cause side effects. So by default Awesome avoids, but does not prevent, having clients in multiple tags that are not on the same screen.

Can a tag be on multiple screens?

No. See the previous two questions. However, it is possible to swap tags across screens using t:swap(t2) (assuming t and t2 are valid tag objects).

This can be used to emulate a tag being on multiple screens. Note that this will break support for multi-tagged clients. For this reason it isn't implemented by default.

Development

How to report bugs?

First, test the development version to check if your bug is still there. If the bug is an unexpected behavior, please explain what you expected instead. If the bug is a segmentation fault, please include a full backtrace (use gdb).

In any case, please try to explain how to reproduce it.

Please report any issues you may find on our bugtracker.

Do you accept patches and enhancements?

Yes, we do. You can submit pull requests on the github repository. Please read the contributing guide for any coding, documentation or patch guidelines.

awesome

Contents

Documentation

Core components

Input handling

Declarative rules

Widgets

Widget containers

Widget layouts

Popups and bars

Utility libraries

Theme related libraries

Client tiling

Libraries

Sample files

Classes

FAQ