Translation(s): English - Français

Awesome is a tiling Window Manager that can replace or live together with other desktop environments like Gnome and KDE Plasma.

Usage is optimized for shortcuts. It may take some time to get used to it. Access to some programs may afford configuring or using command prompt and exact program name. Information about battery usage, wifi, etc. needs configuration.

On the other hand Awesome is small and therefore fast opening especially compared with Plasma. It allows to place clients on several tags, and display several tags at the same time.

On the Awesome home page is stated that "it is primarly targeted at power users, developers and any people dealing with every day computing tasks and who want to have fine-grained control on theirs graphical environment."

Awesome works at least with Debian Jessie (Awesome 3.4) and Debian Stretch (Awesome 4).


# apt-get install awesome

Optional (adds extra widgets as usage of battery, wifi, cpu memory, etc.):-

# apt-get install awesome-extra

Now, if you are using GDM or KDM, it should appear in the login window, so you can select Awesome instead of Gnome or KDE Plasma.

For Debian with KDM have a look in the left bottom corner of the login screen for the place to change the window manager. Depending on the background image it might draw no immediate attention.

Using KDM be aware that the login window only appears if automatic login isn't activated in the KDE-settings, starting, login window. Here you can also decide which window manager will be used for automatic login. It is recommended not to use automatic login while configuring awesome. Mistakes in the configuring file can in extreme case prevent Awesome from starting. In this case it is convenient to use the other window manager to reset the configuring file.

If it doesn't show up in the window manager list on the login screen edit /usr/share/xsessions/awesome.desktop, change NoDisplay=true to NoDisplay=false.

Hint: You can also write your own Xsession startup script and choose "System Default" in GDM or KDM.

This is a sample Xsession file, working at least on Debian Wheezy and Jessie (the file must be saved as $HOME/.Xsession):

gnome-screensaver &
gnome-settings-daemon &

export $(/usr/bin/gnome-keyring-daemon --start --components=pkcs11,secrets,ssh,gpg)

xrdb -cpp /usr/bin/cpp-4.7 -merge ~/.Xresources
xrandr --output HDMI2 --right-of HDMI1

exec awesome

If you are not using a login manager you should configure .xinitrc as usual, running awesome at the end of the script. In order to obtain certain privileges for your user (like being able to make the computer sleep and things like that), use ck-launch-session like this:

xrdb -merge ~/.Xresources #if you have Xresources
xmodmap ~/.Xmodmap #if you use xmodmap
nm-applet& #if you want to use network-manager
bluetooth-app`let& #if you have bluetooth
volti& #this is a program to control audio volume ("apt-get install volti")
ck-launch-session awesome

If you want to use Awesome at the same time than Gnome or Plasma of XFCE, there is good news: it is possible. All this information is on the Awesome official wiki (for example: Awesome with Gnome).


Most programs can be started through the Debian menu which "hides" behind the Awesome icon, a very stylistic "a" in the upper left corner. Press it as button and you will find a menu hierarchy also containing "edit config" in the Awesome submenu.

Awesome is mostly managed using the keyboard.

It first run in "normal" mode, but pressing win+space repeatedly goes through different tiling modes.

Learn more key commands by pressing win+s or running:

man awesome


Unlike Gnome or Plasma type desktops environments, Awesome is configured editing a "lua" source file located either in /etc/xdg/awesome/rc.lua or ~/.config/awesome/rc.lua.

It is highly recommended that you edit the file in your personal folder. So your changes do not affect other users. Furthermore in the case of a severe mistake in your personal configuring file Awesome will use the original "rc.lua" as fallback. You do so by coping the general file first:

$ mkdir ~/.config/awesome
$ cp /etc/xdg/awesome/rc.lua ~/.config/awesome/rc.lua

It could make sense to copy the default theme from /usr/share/awesome/themes/default to ~/.config/awesome/themes/default and change theme_path in rc.lua from beautiful.init(awful.util.get_themes_dir() .. "default/theme.lua") to beautiful.init("~/.config/awesome/themes/default/theme.lua"), too.

Now edit the configuration file:

$ nano ~/.config/awesome/rc.lua

Further configuration (highly recommended)

To get an idea of what you can do with awesome, it is recommended that you dedicate some time to fully configure it to your taste. It is recommended to investigate The official Awesome wiki.

Before starting be aware that the configuring file "rc.lua" of Awesome 3.4 is very different from that of Awesome 4. Only some examples and code snippets work with both versions. In addition only some websites state explicitly which Awesome version will work with their examples.

Awesome 3.4 is documented well, code snippets are available for many cases on different websites.

The vicious library contained in the awesome-extra package contains several useful widgets. ~/.config/awesome/vicious/README contains a detailled description of the widgets and their use. Not all of these work for Awesome 4.

Configuration example for Debian Stretch and Awesome 4

Theming, transparency and wallpaper

Beautiful is a lua library that allows you to theme Awesome using an external file, it becomes easy to dynamically change your whole Awesome colours and wallpaper without changing your rc.lua.

The default theme is at /usr/share/awesome/themes/default. Copy it to ~/.config/awesome/themes/default and change theme_path in rc.lua from beautiful.init(awful.util.get_themes_dir() .. "default/theme.lua") to beautiful.init("~/.config/awesome/themes/default/theme.lua").

Use theme.menu_bg_normal for transparency e.g. change theme.bg_normal = "#222222" to theme.menu_bg_normal = "#aaaaaa32" and add theme.taglist_bg_focus = "#ffff0064".

To set your personal wallpaper name it background.png, put it in ~/.config/awesome/themes/default and change theme.wallpaper = /usr/share/awesome/themes/default/background.png to theme.wallpaper = ~/.config/awesome/themes/default/background.png.

Default terminal

Change os.getenv("EDITOR") or "editor" to an editor of your choice e.g. editor = "kate"

Tiling modes

In the section -- Table of layouts to cover with, order matters. you may want to reduce the possibilites, comment the lines out you don't need.

If you like to create your personal menu because the Debian menu doesn't contain all programs or the sorting doesn't satisfy you, you can start with the following example.

mymainmenu ={ items = { 
--                                  { "Menü", ts_menu,"/usr/share/icons/oxygen/base/22x22/places/start-here-kde.png" },
                                    { "",""}, 
--                                  { "Shutdown", 'kshutdown',"/usr/share/icons/oxygen/base/22x22/actions/system-shutdown.png"},
                                    { "Quit", function() awesome.quit() end,"/usr/share/icons/oxygen/base/22x22/actions/system-log-out.png" };
                                    { "",""}, 
--                                  { "Notizzettel","/usr/bin/knotes","/usr/share/icons/oxygen/base/22x22/apps/knotes.png"},  
--                                  { "File Manager", "dolphin","/usr/share/icons/oxygen/base/22x22/apps/system-file-manager.png" }, 
--                                  { "Search","kfind","/usr/share/icons/hicolor/22x22/apps/kfind.png" },
                                    { "",""}, 
                                    { "Browser", "firefox", "/usr/share/pixmaps/firefox-esr.png" },
--                                  { "E-mail", "icedove","/usr/share/pixmaps/icedove.xpm" },  
                                    { "",""}, 
                                    { "Terminal", konsole, "/usr/share/icons/oxygen/base/22x22/categories/applications-utilities.png" },
--                                  { "Synaptic","kdesudo synaptic-pkexec","/usr/share/synaptic/pixmaps/synaptic_32x32.xpm"},
                                    { "",""},
--                                  { "System-settings","kdesudo systemsettings5","/usr/share/icons/oxygen/base/22x22/categories/preferences-system.png"},
--                                  { "Bluetooth","blueman-applet","/usr/share/icons/hicolor/32x32/apps/blueman.png"},
                                    { "Network-Manager", "nm-applet","/usr/share/icons/gnome/base/22x22/places/network_local.png" },
                                    { "",""}, 
--                                  { "gtkam","/usr/bin/gtkam","/usr/share/gtkam/pixmaps/camera.xpm"},
                                    { "",""}, 
                                    { "awesome", myawesomemenu, beautiful.awesome_icon },
                                    { "Debian",, "/usr/share/icons/gnome/22x22/places/debian-swirl.png" },

Many lines are commented out because missing programs or icons lead to errors. Since the search for actual paths of programs and their icons takes some time the lines are included in spite of this.

And here is the submenu ts_menu mentioned in the menu.

audio = {
--      {"Spotify","/usr/bin/spotify","/usr/share/icons/hicolor/32x32/apps/spotify-client.png"}, 
--      {"Audacity","/usr/bin/audacity","/usr/share/pixmaps/audacity32.xpm"},
--      {"Clementine","/usr/bin/clementine","/usr/share/pixmaps/clementine.xpm"},
--      {"",""},
--      {"Ex Falso","/usr/bin/exfalso","/usr/share/pixmaps/exfalso.png"},
--      {"Puddletag","/usr/bin/puddletag","/usr/share/pixmaps/puddletag.png"},
--      {"TuxGuitar","tuxguitar","/usr/share/pixmaps/tuxguitar.xpm"},
--      {"Timidity","timidity -ig","/usr/share/pixmaps/timidity.xpm"},

office = {
        {"writer","/usr/bin/libreoffice --writer","/usr/share/icons/hicolor/32x32/apps/libreoffice-writer.png"},
        {"calculation","/usr/bin/libreoffice --calc","/usr/share/icons/hicolor/32x32/apps/libreoffice-calc.png"},
        {"impress","/usr/bin/libreoffice --impress","/usr/share/icons/hicolor/32x32/apps/libreoffice-impress.png"},
        {"base","/usr/bin/libreoffice --base","/usr/share/icons/hicolor/32x32/apps/libreoffice-base.png"},

development = {
        {"Link Status prüfen","/usr/bin/klinkstatus","/usr/share/icons/hicolor/32x32/apps/klinkstatus.png"},

photo = {
--      {"SQLiteBrowser","/usr/bin/sqlitebrowser"},
        {"GIMP","/usr/bin/gimp -n","/usr/share/pixmaps/gimp.xpm"},
photo_2 = {
--      {"FotoWall","/usr/bin/fotowall","/usr/share/pixmaps/fotowall.xpm"},
--      {"PhotoPrint","/usr/bin/photoprint","/usr/share/icons/hicolor/48x48/apps/fotoprint.png"},
--      {"DNG-Koverter","/usr/bin/dngconverter","/usr/share/icons/hicolor/48x48/apps/kipi-dngconverter.png"},

graphics = {
--      {"Scribus","/usr/bin/scribus","/usr/share/pixmaps/scribus.xpm"},
        {"Office Draw","/usr/bin/libreoffice --draw","/usr/share/icons/hicolor/32x32/apps/libreoffice-draw.png"},
--      {"PTBatcherGUI","/usr/bin/PTBatcherGUI"},

internet = {
        {"Firefox", "firefox", "/usr/share/pixmaps/firefox-esr.png" },
        {"Icedove E-mail","icedove","/usr/share/pixmaps/icedove.xpm"},
        {"dropbox","/usr/bin/dropbox start -i","/usr/share/icons/hicolor/32x32/apps/dropbox.png"},

games = {
--      {"MegaGlest","/usr/games/megaglest","/usr/share/pixmaps/megaglest.xpm"},
--      {"widelands","/usr/games/widelands","/usr/share/icons/hicolor/32x32/apps/widelands.xpm"},

system = {
        {"Synaptic","kdesudo synaptic-pkexec","/usr/share/synaptic/pixmaps/synaptic_32x32.xpm"},
        {"Apper","kdesudo apper","/usr/share/icons/oxygen/base/22x22/categories/applications-other.png"},
        {"Systems ettings","kdesudo systemsettings","/usr/share/icons/oxygen/base/22x22/categories/preferences-system.png"},
        {"Krusader-root","kdesudo krusader","/usr/share/icons/hicolor/32x32/apps/krusader_root.png"},
--      {"luckybackup-root","su-to-root -X -c /usr/bin/luckybackup","/usr/share/pixmaps/luckybackup.xpm"},
        {"Partition Manager","kdesudo partitionmanager","/usr/share/icons/oxygen/base/22x22/apps/partitionmanager.png"},
        {"Gparted","kdesudo gparted","/usr/share/icons/hicolor/32x32/apps/gparted.png"},
        {"System Information","kinfocenter","/usr/share/icons/oxygen/base/22x22/apps/hwinfo.png"},
        {"System Monitor","/usr/bin/ksysguard","/usr/share/icons/gnome/32x32/apps/ksysguard.png"},

video = {
        {"VLC media player","/usr/bin/qvlc","/usr/share/icons/hicolor/32x32/apps/vlc.xpm"},
        {"Dragon Player","/usr/bin/dragon","/usr/share/icons/hicolor/32x32/apps/dragonplayer.png"},
--      {"WinFF","/usr/bin/winff","/usr/share/pixmaps/winff.xpm"},

tools = {
    {"File Manager", "dolphin","/usr/share/icons/oxygen/base/22x22/apps/system-file-manager.png" }, 
        {"Krusader-root","kdesudo krusader","/usr/share/icons/hicolor/32x32/apps/krusader_root.png"},
        {"Terminal", "konsole", "/usr/share/icons/oxygen/base/22x22/categories/applications-utilities.png"},
        {"Editor-root","kdesudo kate","/usr/share/icons/hicolor/32x32/apps/kate.png"},
--      {"Komparator","/usr/bin/komparator4","/usr/share/icons/hicolor/32x32/apps/komparator4.png"},

ts_menu = {
        { "audio", audio, "/usr/share/icons/oxygen/base/22x22/mimetypes/audio-ac3.png" },
        { "office", office, "/usr/share/icons/oxygen/base/22x22/categories/applications-office.png" },
        { "development", development, "/usr/share/icons/oxygen/base/22x22/categories/applications-development.png" },
        { "photo", photo,"/usr/share/icons/oxygen/base/22x22/apps/showfoto.png" },
        { "photo_2", photo_2 },
        { "graphics", graphics, "/usr/share/icons/oxygen/base/22x22/categories/applications-graphics.png" },
        { "internet", internet, "/usr/share/icons/oxygen/base/22x22/categories/applications-internet.png" },
        { "games", games, "/usr/share/icons/oxygen/base/22x22/categories/applications-games.png" },
        { "system", system, "/usr/share/icons/oxygen/base/22x22/categories/applications-system.png" },
        { "video", video, "/usr/share/icons/gnome/32x32/mimetypes/video.png" },
        { "tools", tools, "/usr/share/icons/oxygen/base/22x22/categories/applications-utilities.png" },

It has to be added as ts_menu.lua in ~/.config/awesome and

-- Load ts_menu

has to be added in the first lines of rc.lua. Perhaps the many lines help to save time for searching of program and icon paths.

Random Wallpapers


local function set_wallpaper(s)
    -- Wallpaper
    if beautiful.wallpaper then
        local wallpaper = beautiful.wallpaper
        -- If wallpaper is a function, call it with the screen
        if type(wallpaper) == "function" then
            wallpaper = wallpaper(s)
        gears.wallpaper.maximized(wallpaper, s, true)

-- Re-set wallpaper when a screen's geometry changes (e.g. different resolution)
screen.connect_signal("property::geometry", set_wallpaper)


-- {{ Function definitions

-- scan directory, and optionally filter outputs
function scandir(directory, filter)
    local i, t, popen = 0, {}, io.popen
    if not filter then
        filter = function(s) return true end
    for filename in popen('ls -a "''"'):lines() do
        if filter(filename) then
            i = i + 1
            t[i] = filename
    return t

-- }}

-- configuration 
wp_index = 1
wp_filter = function(s) return string.match(s,"%.png$") or string.match(s,"%.jpg$") end
wp_files = scandir(wp_path, wp_filter) 
gears.timer.start_new (10, function() 
  for s = 1, screen.count() do
    gears.wallpaper.maximized(wp_path .. wp_files[wp_index], s, true)
  math.randomseed( os.time() )
  wp_index = math.random( 1, #wp_files)
    return true

Change PATH_TO_YOUR_WALLPAPER_DIRECTORY to the actual directory.


Programs can be opened in dedicated tags. These tags can contain an icon. While for Awesome 3.4 tags need no text to be contained, in Awesome 4 the tag text is it's name. So it makes sense to keep the figures 1,..9 as text for the tags.

Change awful.tag({ "1", "2", "3", "4", "5", "6", "7", "8", "9" }, s, awful.layout.layouts[1]) against

    awful.tag.add("1", {
        icon               = "/usr/share/icons/oxygen/base/22x22/places/user-desktop.png",
        layout             = awful.layout.suit.tile,
        --        master_fill_policy = "master_width_factor",
        --        gap_single_client  = true,
        --        gap                = 1,
        screen             = s,
        selected           = true,
    awful.tag.add("2", {
        icon = "/usr/share/icons/oxygen/base/22x22/places/user-desktop.png",
        layout = awful.layout.suit.max,
        screen = s,
    awful.tag.add("3", {
        icon = "/usr/share/icons/oxygen/base/22x22/places/user-desktop.png",
        layout = awful.layout.suit.max,
        screen = s,
    awful.tag.add("4", {
        icon = "/usr/share/pixmaps/firefox-esr.png",
        layout = awful.layout.suit.max,
        screen = s,

and add further 5 tags if you like.


for each widget add the code shown in the respective widget section below after the following section of rc.lua

 -- Create a tasklist widget
    s.mytasklist = awful.widget.tasklist(s, awful.widget.tasklist.filter.currenttags, tasklist_buttons)


If "vicious.register" appears in the widget, local vicious = require("vicious") must be added in the first lines of rc.lua (and the extra package of Awesome installed).

Widgets which use may freeze the screen shortly while executing. So improvement would be welcome.

Additional information can be found in the Awesome api


    cpuicon = wibox.widget {
        image  = "/usr/share/icons/oxygen/base/22x22/devices/cpu.png",
        resize = false,
        widget = wibox.widget.imagebox
    cpuwidget = wibox.widget.graph()
        cpuwidget.opacity = "1"
        vicious.register(cpuwidget, vicious.widgets.cpu, "$1", 5)


    memwidget  = wibox.widget.graph()
        memwidget.opacity = "1"
        vicious.register(memwidget, vicious.widgets.mem, "$1", 11)
    beautiful.graph_bg = "#00000000"

File system

fswidgettxt = ""
    -- root, can easily be adapted for home
    function fsroot()
        fstext ="fp3")
        fsnumber = fstext:read(2)
        if fsnumber+1-1 < 80 then           -- +1-1 to get number
            rootwidget.widget.markup = ""
            if fsnumber+1-1 < 90 then       -- +1-1 to get number
                rootwidget.widget.markup = " / " .. fsnumber .. "% " 
       = '#ffff0064'
                if fsnumber > 95 then                
           = '#ff0000'
    rootwidget  = wibox.widget {     
            markup        = fswidgettxt,
            widget        = wibox.widget.textbox
        bg     = '#ffffff00',
        layout = wibox.container.background
    gears.timer.start_new (67, function() 
        return true

For this widget the following script has to be saved as root in /bin as Then the file must be made executable and readable for the user. For home / has to be changed to /home. The script creates files in the home directory which can be used for root and home.

    df / > fp1
    cut -c46-47 fp1 > fp2
    rm fp1
    tr -d ' ',[A-z],'\n' < fp2 > fp3
    rm fp2

Note that the widget is not visible if the used part of the partition is below 80% of it's size.


    local function battery_state()
        batchar ="batchar")
        batchartxt = batchar:read()
        if batchartxt == "Dis" then
            batpctxt ="batpc") 
            batpczahl = batpctxt:read()
            lengthbat = string.len(batpczahl) +1 -1  -- only to secure that lengthbat is of type number
            if lengthbat == 1 then
                os.execute("/bin/") -- percent is only 1 digit
            battime ="battime")
            battimetxt = " " .. battime:read() .. " "
            bath ="bath")
            bathtxt = bath:read(1)
            batm ="batm")  
            batmtxt = batm:read(1) 
    local function get_battery_state()
        -- show remaining timme if discharging
        if batchartxt == "Dis" then
            -- change backgroundcolor if only twenty minutes left
            if bathtxt == "0" and (batmtxt == "0" or batmtxt == "1") then
                battxtwidget.widget.markup = "<b> Remaining: " .. battimetxt .. "</b>"
                battxtwidget.widget.font = "\"Liberation Serif\", 16"
       = '#ff0000'
                battxtwidget.widget.markup =  ' Remaining: ' .. battimetxt 
                battxtwidget.widget.markup = ""  
    batwidget  = wibox.widget {
            max_value     = 100,
            value         = batpczahl,
            widget        = wibox.widget.progressbar,
        forced_width  = 15,
        direction     = 'east',
        layout        = wibox.container.rotate,
    battxtwidget = wibox.widget{
            markup = markuptxt,
            widget = wibox.widget.textbox
        bg     = '#ffffff00',
        layout = wibox.container.background
    gears.timer.start_new (61, 
            return true

This widget requires the following scripts to be installed with reading rights for the user and execution rights in /bin as

    acpi > bat1
    cut -c12-14 bat1 > batchar
    cut -c25-26 bat1 > bat2
    # if load percentage < 10, 26 is "%"
    tr -d '%' < bat2 > batpc

    cut -c31-37 bat1 > battime
    cut -c31-31 bat1 > bath
    cut -c33-33 bat1 > batm

    cut -c30-36 bat1 > battime
    cut -c30-30 bat1 > bath
    cut -c31-31 bat1 > batm

The widget appears when battery state is low and discharging.

Upgradable packages

    upgradable = os.execute("")
    upgrtext ="upgr")
    upgrnumber = upgrtext:read(2) -1  -- headline doesn't count
    if upgrnumber > 0 then
        upgrtext = " " .. upgrnumber .. " updates "
        upgrtext = ""
    upgrwidget  = wibox.widget {     
            markup        = upgrtext,
            widget        = wibox.widget.textbox
        bg     = '#ffff0064',
        layout = wibox.container.background

This widget requires the following script to be installed with reading rights for the user and execution rights in /bin as

    apt list --upgradable > upgradable
    wc -l <  upgradable > upgr

Network traffic

neticon = wibox.widget {
        image  = "/usr/share/icons/oxygen/base/22x22/actions/go-down.png",
        resize = false,
        widget = wibox.widget.imagebox
    netwidget  = wibox.widget {     
            markup        = " ",
            widget        = wibox.widget.textbox
        bg     = '#ffffff00',
        layout = wibox.container.background

    netnumber = 0
    gears.timer.start_new (1, 
            lastnetnumber = netnumber
            nettext ="/sys/class/net/INTERFACE/statistics/rx_bytes")
            netnumber = nettext:read()  +1 -- secure to be number
            netrecent = math.floor((netnumber - lastnetnumber)/1000)
            netwidget.widget.markup = netrecent .. " "
            return true

For this widget /sys/class/net/INTERFACE/statistics/rx_bytes must be readable,


Add the following in the -- {{{ Key bindings-section:

    awful.key({ }, "XF86MonBrightnessUp",
        function ()
        os.execute("") end,
        {description = "lighter", group = "ts"}),
    awful.key({ }, "XF86MonBrightnessDown", function ()  
        os.execute("/bin/") end,
        {description = "darker", group = "ts"}),

This requires the following scripts to be installed with reading rights for the user and execution rights in /bin as

    read < "/sys/class/backlight/intel_backlight/brightness" brightness
    brightness=`expr $brightness + $var1`
    echo $brightness > /sys/class/backlight/intel_backlight/brightness

    read < "/sys/class/backlight/intel_backlight/brightness" brightness
    brightness=`expr $brightness - $var1`
    echo $brightness > /sys/class/backlight/intel_backlight/brightness

/sys/class/backlight/intel_backlight/brightness must have write access for the user.

The shortcut for a brighter window is then Fn+CURSOR_LEFT.

Audio Volume

Shortcuts are made available by the program Kmix.

Screen snapshot

Add the following in the -- {{{ Key bindings-section:

awful.key({ }, "Print", function () awful.util.spawn("ksnapshot") end,
        {description = "Screen snapshot", group = "user"})

Floating clients

Consider to add additional clients in the section -- Floating clients., e.g Gimp, knotes or Kmix.

No titlebars

If you prefer the shortcuts for closing and maximizing the windows, titlebars are obsolete. "titlebars_enabled = true" can be changed to open new windows without titlebars.

Set Program to open on a special tag

The rule for Firefox exists already in original rc.lua but is commented out in section Set Firefox to always map on the tag named "2" on screen 1

Autostart and Numlock

Add at the end the programs you want, e.g.

    awful.spawn.easy_async("numlockx on")