AwesomeWM Customizations

This page focuses on AwesomeWM customizations specific to Qubes OS. For generic AwesomeWM customizations you might want to have a look at the AwesomeWM website.

Customizations for AwesomeWM are usually done at ~/.config/awesome/rc.lua. The default file can be found at /etc/xdg/awesome/rc.lua.

Application menu

Starting from Qubes 4.0 application menu entries specific to AwesomeWM can be put into ~/.config/awesome/xdg-menu/ following the freedesktop standard. The folder might have to be created.

Focus steal hardening

The default Qubes OS AwesomeWM installation comes with the defaults set by the AwesomeWM developers for focus changes. Some users may want more tight control over window focus changes - especially since focus changes can have security implications when sensitive data is provided to an incorrect application or even Qube.


For the below example we’ll define wanted focus changes as one of the below:

  • mouse move & click afterwards
  • workspace/tag change
  • pre-defined key combinations for focus changes (e.g. Mod-j & Mod-k)
  • focused window moved to other tag 1
  • focused window closed 1
  • new window created in a workspace with only unfocused windows or in an empty workspace

(1 These are allowed to cause a focus switch to another window according to a predefined algorithm as otherwise no window would be focused.)

Everything else is considered an unwanted focus steal.

In particular the following events are not meant to cause a focus change:

  • new window created in a workspace with a focused window
  • unfocused window closed
  • unfocused window moved to another tag/workspace
  • application request
  • mouse move without click (sloppy focus)

For the below example other requests from applications to the window manager are meant to be ignored in general as well, e.g.:

  • windows shouldn’t be able to maximize themselves without the user giving a respective command to the WM (simple test: Firefox F11 next to another window)
  • windows shouldn’t be able to change their size themselves
  • windows shouldn’t be able to modify their borders in any way

Users may want to adjust their definitions and respective implementations according to their needs.


The implementation may be specific to the AwesomeWM version you’re running. This guide refers to AwesomeWM version 4.3 which is available to Qubes 4.1 users.

Please keep in mind that this guide may not be conclusive. Your mileage may vary.

Remove unwanted focus changing key bindings

The mouse bindings

awful.button({ }, 4, awful.tag.viewnext),
awful.button({ }, 5, awful.tag.viewprev)

in the default rc.lua may cause tag and thus focus changes without keyboard interaction and tend to happen accidentally. This doesn’t suit our definition from above and should therefore be removed or commented out.

Adjust rules for new windows

The default window/client rule allows certain focus changes whenever new windows are created via focus = awful.client.focus.filter. These changes can be prevented entirely by setting focus = false.

Alternatively users may provide their own focus filter functions.

Never hide borders

By default AwesomeWM may hide window borders incl. the Qubes colors for fullscreen or maximized windows. In order to prevent that, put the following two lines at the bottom of your rc.lua:

beautiful.fullscreen_hide_border = false
beautiful.maximized_hide_border = false

Disable sloppy focus

In your rc.lua you’ll find a section such as

-- Enable sloppy focus, so that focus follows mouse.
client.connect_signal("mouse::enter", function(c)
    c:emit_signal("request::activate", "mouse_enter", {raise = false})

These enable sloppy focus aka focus changes on mouse movements (without clicking) and should be removed or commented out to disable that behaviour.

Enable right-click focus changes

In your rc.lua you should find a section which enables left-click focus changes such as

    awful.button({ }, 1, function (c) 
        c:emit_signal("request::activate", "mouse_click", {raise = true})

Add the following section below to enable focus changes on right mouse clicks:

    awful.button({ }, 3, function (c) 
        c:emit_signal("request::activate", "mouse_click", {raise = true})

If you want other mouse buttons to change the focus as well, feel free to add further entries (0 = all mouse buttons).

Ignore requests from applications to the window manager

Applications and running Qube windows may request from AwesomeWM to become focused.

Handling of such requests is currently mostly implemented by AwesomeWM in the file /usr/share/awesome/lib/awful/ewmh.lua. You can either comment out the respective client.connect_singal() lines in that file (it will change back after each AwesomeWM update though) or disconnect the signals in your rc.lua as well as use the built-in filter functionality.

To do the latter, add the following lines to the end of your rc.lua:

local ewmh = require("awful.ewmh")
ewmh.add_activate_filter(function(c, context, hints) return false end, "ewmh") --ignore client requests to become focused
client.disconnect_signal("request::urgent", ewmh.urgent) --ignore client requests to become an "urgent" window
client.disconnect_signal("request::geometry", ewmh.merge_maximization) --ignore client maximization requests
client.disconnect_signal("request::geometry", ewmh.client_geometry_requests) --ignore clients requesting to move themselves

Change the autofocus implementation

The line require("awful.autofocus") in your rc.lua loads a module that moves the focus to another window whenever a window is moved to another workspace or closed. In the AwesomeWM default implementation, this module keeps track of the order in which windows were focused and sets the focus to the last focused one whenever the currently focused window disappears.

Some users may want to modify that default behaviour.

In order to do that, you can copy the file /usr/share/awesome/lib/awful/autofocus.lua to e.g. ~/.config/awesome/autofocus_custom.lua and replace the line mentioned above with require("autofocus_custom").

Then you can customise the focus behavior.

For example, the following will make the focus move to the window under the mouse cursor whenever focus is lost and only use the history on tag switches:

--- Autofocus functions.
-- When loaded, this module makes sure that there's always a client that will
-- have focus on events such as tag switching, client unmanaging, etc.
-- @author Julien Danjou <>
-- @copyright 2009 Julien Danjou
-- @module awful.autofocus

local client = client
local aclient = require("awful.client")
local ascreen = require("awful.screen")
local timer = require("gears.timer")

local function filter_sticky(c)
    return not c.sticky and aclient.focus.filter(c)

--- Give focus when clients appear/disappear.
-- @param obj An object that should have a .screen property.
function check_focus(obj)
    if obj.screen == nil then return end
    if not obj.screen.valid then return end
    -- When no visible client has the focus...
    if not client.focus or not client.focus:isvisible() then
        local c = aclient.focus.history.get(screen[obj.screen], 0, filter_sticky)
        if not c then
            c = aclient.focus.history.get(screen[obj.screen], 0, aclient.focus.filter)
        if c then
            c:emit_signal("request::activate", "autofocus.check_focus",

--- Check client focus (delayed).
-- @param obj An object that should have a .screen property.
local function check_focus_delayed(obj)
    timer.delayed_call(check_focus, {screen = obj.screen})

--- Give focus on tag selection change.
-- @param tag A tag object
function check_focus_tag(t)
    local s = t.screen
    if (not s) or (not s.valid) then return end
    s = screen[s]
    check_focus({ screen = s })
    if client.focus and screen[client.focus.screen] ~= s then
        local c = aclient.focus.history.get(s, 0, filter_sticky)
        if not c then
            c = aclient.focus.history.get(s, 0, aclient.focus.filter)
        if c then
            c:emit_signal("request::activate", "autofocus.check_focus_tag",

-- Clear any focus.
function clear_focus()
    client.focus = nil

local pending = false
local glib = require("lgi").GLib

--focus the window under the mouse, if nothing is focused
--idea from
--fallback: true|false - fall back to the focus history, if the mouse points
--                       nowhere (recommended default: false)
function check_focus_mouse(fallback)
    if not pending then
        pending = true
        glib.idle_add(glib.PRIORITY_DEFAULT_IDLE, function()
            pending = false
            if not client.focus then
                local c = mouse.current_client
                if c then
                    client.focus = c
                    if fallback then
                        local t = ascreen.focused().selected_tag
                        if t then
            return false

--further delayed variant of check_focus_mouse(), required for just created windows
local function check_focus_mouse_delayed()

--make the focus follow the mouse on the below events, if nothing else is focused
client.connect_signal("manage",              check_focus_mouse_delayed) --for empty workspaces or workspace without focused window
client.connect_signal("unmanage",            check_focus_mouse_delayed)
client.connect_signal("tagged",              check_focus_mouse_delayed)
client.connect_signal("untagged",            check_focus_mouse_delayed)
client.connect_signal("property::hidden",    check_focus_mouse_delayed)
client.connect_signal("property::minimized", check_focus_mouse_delayed)
client.connect_signal("property::sticky",    check_focus_mouse_delayed)

--use history on tag switch:
tag.connect_signal("property::selected", function (t)
    timer.delayed_call(check_focus_tag, t)

You might also want to add the check_focus_mouse() function to your Mod-j and Mod-k implementations to be able to obtain a focused window even if no window happens to be focused.


Issues with e.g. your rc.lua configuration can be identified in dom0 from the ~/.xsession-errors log.

If AwesomeWM encounters an error, it’ll also either display a red notification or return you to the display manager (usually the login screen).

This document was migrated from the qubes-community project
  • Page archive
  • First commit: 20 Jan 2023. Last commit: 20 Jan 2023.
  • Applicable Qubes OS releases based on commit dates and supported releases: 4.1
  • Original author(s) (GitHub usernames): 3hhh
  • Original author(s) (forum usernames): N/A
  • Document license: CC BY 4.0