From awesome
Jump to: navigation, search


About awesome[edit]

Why awesome?[edit]

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


What are awesome dependencies?[edit]

See the README.


How to change the default window management layout?[edit]

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.
   tags[s] = awful.tag({ 1, 2, 3, 4, 5, 6, 7, 8, 9 }, s, 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?[edit]

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

 -- {{{ Tags
 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]
 for s = 1, screen.count() do
     tags[s] = awful.tag(tags.names, s, tags.layout)
 -- }}}

How to setup different tags and layouts per screen?[edit]

Another demonstration for your tag section:

 -- {{{ Tags
 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] }
 for s = 1, screen.count() do
     tags[s] = awful.tag(tags.settings[s].names, s, tags.settings[s].layout)
 -- }}}

How to show only non-empty tags?[edit]

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:

 for s = 1, screen.count() do
 =>	mytaglist[s] = awful.widget.taglist(s, awful.widget.taglist.filter.noempty, mytaglist.buttons)
 -- }}}

How to autostart applications?[edit]

The traditional way is to use the ~/.xinitrc file, you can read about that and some other solutions on the Autostart page.

How to use multiple monitors?[edit]

Awesome has real multihead support (XRandR, Xinerama or Zaphod mode) with per screen desktops (tags), and is distributed with a sample configuration file which is already setup for multiple displays (regarding wiboxes, taskbars and widgets but also has keybindings which allow you to move clients between multiple screens and switch focus between them). Read the full guide to "Using Multiple Screens" for further instructions.

How to lock the screen when I am away?[edit]

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

Example key binding for your globalkeys:

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

How to execute a shell command?[edit]

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.util.spawn function but awful.util.spawn_with_shell. Here is an example:

 awful.key({ modkey }, "F10", function () awful.util.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 fix and improve usability of Java applications?[edit]

Java applications which use the XToolkit/XAWT back-end may draw grey windows only. The XToolkit/XAWT back-end breaks ICCCM-compliance in recent JDK 1.5 and early JDK 1.6 versions, because it assumes a reparenting window manager. You can find solutions and workarounds on the Problems with Java wiki page.

How to remove gaps between windows?[edit]

In awesome 3.4 you can add size_hints_honor = false to the properties section in your awful.rules.rules table, it will match and apply this rule to all clients. As an alternative (or in older versions) you can do it by adding c.size_hints_honor = false in the manage signal function (or manage hook in older versions).

If you want to know what are size hints it has been debated many times on the mailing list, so you can read the explanation: http://www.mail-archive.com/awesome@naquadah.org/msg01767.html

This might cause flickering with the affected applications (e.g. Lilyterm), apparently when the whole window gets redrawn etc.

How to add an application switcher?[edit]

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} })

How to configure and use widgets?[edit]

You can learn all about widgets, and how to create them on the Widgets in awesome page.

Some users created widget libraries applying the above principles. They try to simplify widget creation for others, and have the advantage of being distributed with a big number of system monitors, so you don't have to write your own. Two popular projects are Vicious and Obvious.

How to setup horizontal widgets on a vertical wibox?[edit]

Left or right placement of the wibox is cool, but vertical text is hard to read. At the moment, in awesome v3.4, it is tricky to get a perfect result, but in the development branch of awesome the widget layouts have already been rewritten with this in mind. This code allows to easily setup complex vertical panels, like some desktop environments provide.

How to control titlebars?[edit]

To disable titlebars on all clients remove the line containing awful.titlebar.add(c, { modkey = modkey }) from your manage signal handler (or manage hook in older versions). If you want a titlebar only on certain clients you don't need to introduce that line back, you can do it in your awful.rules.rules table. Example rule:

 { rule = { class = "Gimp" }, callback = awful.titlebar.add  },

How to toggle titlebar visibility?[edit]

You can use a clientkeys binding.

With awesome 3.5.2:

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

Old version:

   awful.key({ modkey, "Shift" }, "t", function (c)
       if   c.titlebar then awful.titlebar.remove(c)
       else awful.titlebar.add(c, { modkey = modkey }) end

How to toggle wibox visibility?[edit]

Add the following key binding to your globalkeys:

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

How to toggle clients floating state?[edit]

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?[edit]

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 awful.rules.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 prevent floating clients opening offscreen?[edit]

Enable awful.placement calls in your manage signal handler:

   -- Floating clients don't overlap, cover 
   -- the titlebar or get placed offscreen

How to move and resize floaters with the keyboard?[edit]

You can use the awful.client.moveresize 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 () awful.client.moveresize( 20,  20, -40, -40) end),
   awful.key({ modkey }, "Prior", function () awful.client.moveresize(-20, -20,  40,  40) end),
   awful.key({ modkey }, "Down",  function () awful.client.moveresize(  0,  20,   0,   0) end),
   awful.key({ modkey }, "Up",    function () awful.client.moveresize(  0, -20,   0,   0) end),
   awful.key({ modkey }, "Left",  function () awful.client.moveresize(-20,   0,   0,   0) end),
   awful.key({ modkey }, "Right", function () awful.client.moveresize( 20,   0,   0,   0) end),

How to resize tiled clients?[edit]

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?[edit]

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 change the cursor theme?[edit]

The reason your cursor fall-backs to default, over a wibox or the background, is because XCB does not support Xcursor yet. It was discussed a few times on the mailing list.

There is a way to get your theme cursor at least over the background, with the xsetroot command:

 $ xsetroot -cursor_name left_ptr

You can include that command in your ~/.xinitrc file, read the Autostart article. Another common solution is using the Neutral Plus theme, which provides cursors similar to X defaults, but includes shadows and animation.

How to find window's class and other identifiers?[edit]

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

 $ xprop

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
                    |--- name

Alternatively you can use one of the following functions in your shell initialization file, to quickly query the current client (you could also use notify-send for Naughty):

 xpop() { zenity --info --text "$(xprop | grep --color=none "^WM_CLASS\|^WM_NAME")" }
 xpop() { xprop | grep --color=none "WM_CLASS\|^WM_NAME" | xmessage -file - }

You can use the above identifiers (instance, class and name) in your awful.rules.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?[edit]

You can add matching rules to your awful.rules.rules table. The default rc.lua already has several examples, but here are some more:

 -- Set Firefox to always map on tag number 2 of screen 1
 { rule = { class = "Firefox" },  properties = {tag = tags[1][2]}},
 -- Set Smplayer to tag 4 of screen 1
 { rule = { class = "Smplayer" }, properties = {tag = tags[1][4]}},
 -- Set Emacs to tag 5 of screen 2
 { rule = { class = "Emacs", instance = "emacs" }, properties = {tag = tags[2][5]}},
 -- Set Alpine to tag 6 of the last screen 
 { rule = { name = "Alpine" },    properties = {tag = tags[screen.count()][6]}},
 -- Set Akregator to tag 8 of the last screen and add a titlebar trough callback
 { rule = { class = "Akregator" },properties = {tag = tags[screen.count()][8]}, callback = awful.titlebar.add},
 -- Set Xterm to multiple tags on screen 1
 { rule = { class = "XTerm" }, callback = function(c) c:tags({tags[1][5], tags[1][6]}) end},
 -- Set ROX-Filer to tag 2 of the currently selected and active screen
 { rule = { class = "ROX-Filer" }, callback = function(c) awful.client.movetotag(tags[mouse.screen][2], c) end},
 -- Set ROX-Filer to tag 8 on screen 1 and switch to that tag imidiatelly
 { rule = { class = "ROX-Filer" }, properties = { tag = tags[1][8], switchtotag = true } } 
 -- Set Geeqie to the currently focused tag, as floating
 { rule = { instance = "geeqie" }, properties = {floating = true}},
 -- Set Xterm as floating with a fixed position
 { rule = { class = "XTerm" }, properties = {floating = true}, callback = function(c) c:geometry({x=0, y=0}) end},

How to start clients as slave windows instead of master?[edit]

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?[edit]

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.util.spawn("kscreenlocker --forcelock") end),

How to add a keyboard layout switcher ?[edit]

You can use the xxkb utility. It has a tray icon and supports settings layouts per client. As an alternative you can use an awesome widget, you can find some examples on the "Change keyboard maps" wiki page, or in the Obvious widget library.

Another way to go about it is using keybindings, without any visual feedback. First solution is using the X.org builtin layout switcher (see example below), another is to call setxkbmap <layout> from an awesome keybinding:

   Section "InputClass"
       Identifier      "keyboard"
       Driver          "evdev"
       MatchIsKeyboard "on"
       Option     "XkbModel"    "evdev"
       # Switch between layouts by pressing both shift keys
       Option     "XkbLayout"   "hr,us"
       Option     "XkbOptions"  "grp:shifts_toggle"

How to make windows spawn under the mouse cursor?[edit]

In your manage signal handler there is a placement section, you can append awful.placement.under_mouse(c) to the existing rules (or replace them).

NOTE: I have put it in this block, which caused problems with new Firefox windows (off-screen, and could not be moved):

   client.connect_signal("manage", function (c, startup)
       if not startup then
           -- Put windows in a smart way, only if they does not set an initial position.
           if not c.size_hints.user_position and not c.size_hints.program_position then
       ==>     awful.placement.under_mouse(c)

How to switch to a specific layout in a keybinding?[edit]

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 is my Wine applicaton tray icon missing when I connect my secondary monitor to my laptop?[edit]

Running KeePass is an example of this. Something has a bug somewhere. You can work around it by making sure your external monitor becomes the primary display. Do something like:

   xrandr --output VGA1 --auto --above LVDS1 --primary

Why are new clients urgent by default?[edit]

Since awesome 3.5.3 new clients are urgent by default. You can change this by redefining awful.ewmh.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.ewmh.activate)
   function awful.ewmh.activate(c)
       if c:isvisible() then
           client.focus = c
   client.connect_signal("request::activate", awful.ewmh.activate)


How to use this thing?[edit]

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.


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.

See the layout page for descriptions of what the different layouts do.

How to restart or quit awesome?[edit]

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 by passing it to awesome-client:

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

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?[edit]

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 bizzare 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?[edit]

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 (qingy uses it, for example), you'll be able to watch (with tail -f) everything right from awesome.

Why does Mod4 "swallow" succeeding key presses?[edit]

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

   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)"};


How to report bugs?[edit]

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).

You may post it here: http://awesome.naquadah.org/bugs/

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

Do you accept patches and enhancements?[edit]

Yes, we do. Please send them to Julien or the mailing-list for review. Also read the development page.

How to keep track with awesome-branches?[edit]

To clone the normal development (git) version:

 git clone git://git.naquadah.org/awesome.git/
 cd awesome/

To get a branch like 'awesome-3':

 git fetch origin awesome-3:awesome-3
 git checkout awesome-3

git-branch will tell you on what branch you are. On some distributions etc you will be able to <tab> complete branches (and more) to git commands.

To stay updated with the 'awesome-3' branch, run these from inside the awesome directory:

 git fetch origin
 git reset --hard origin/awesome-3

To create a patch:

 git clone git://git.naquadah.org/awesome.git/
 edit file
 git commit filename
 git format-patch origin

This yields a file name like