This wiki will shut down!

Please note that this wiki will be made read-only and eventually be taken offline.

A replacement is being discussed at We'd be happy to have more input for that discussion and volunteers who help us migrate the content of this wiki to its replacement.

Main Page

From awesome
Jump to: navigation, search


The goal of this wiki is to provide a community-made documentation and especially help new users with the configuration of awesome. We cover developer information too, including information about how-to build awesome (several related distributions), how-to debug, and so on.

Note: Due to spammers, you must create an account in order to edit pages. While having to create an account to edit is annoying, so is spam.

Feel free to register as a user and contribute to our documentation effort.

Current awesome releases:



Configuration and control of awesome have changed between major versions and may continue to evolve in future ones. Some of the following documents may try to describe all the existing versions. Please fix them if a missing version needs special explanations. Other documents may be bound to only one version of awesome. Please fix them if version indication is missing.

Installation & Basics For Users[edit]

Development Basics[edit]

You might also want to join our IRC channel #awesome on OFTC.



Statusbars and widgets[edit]

Theming awesome[edit]

User configuration files[edit]

Other tips[edit]

Lua extensions[edit]

Lua extensions

Lua is a fast, light-weight, embeddable scripting language. Lua combines simple procedural syntax with powerful data description constructs based on associative arrays and extensible semantics. Lua is dynamically typed, runs by interpreting bytecode for a register-based virtual machine, and has automatic memory management with incremental garbage collection, making it ideal for configuration, scripting, and rapid prototyping.

Common uses of Lua are:

  • A configuration language for applications.
  • A standalone scripting language.
  • An embedded language in applications to modify runtime behaviour.

To get introduced into Lua, please read the briefest introduction to Lua. For deeper knowledge please read this tutorial for the newcomers to the language. As a suggestion, please consider to get this Lua Short Reference. The Awesome framework is built with Lua as the extension language. Some of all extensions can be seen below:

  • awful - the standard awesome Lua library.
  • - a popup menu library.
  • Radical - A powerful and extensible menu system
  • Beautiful - a theming library.
  • Obvious - a new implementation of a widget library made since Wicked.
  • Vicious - a modular widget library derived from Wicked.
  • Space Invaders - allows you to play Space Invaders with Awesome
  • Naughty - a popup notification library
  • Shifty - dynamic tagging library with advanced client matching and sane configuration
  • Tyrannical - A declarative tag and client configuration system for awful dynamic tags (Shifty spiritual successor)
  • Eminent - effortless wmii-style dynamic tagging library that does not require any rc.lua changes
  • Rodentbane - a library for rapid control of the mouse cursor using just the keyboard
  • Collision - A powerful keyboard based navigation and resizing module with visual feedback indicators
  • Flaw - an object oriented library to manage widgets.
  • Retrograde - A layout system identical the one from Awesome 3.2-3.4 for Awesome 3.5+
  • couth - yet another extension library -- includes visual popup notifications for alsa and mpd volume.
  • keychains - use of keychains in awesome
  • hints - window hints to focus windows
  • Vain - An alternative layout system
  • BlingBling - A beautiful Cairo based widget set
  • Lain - A widget library
  • ezconfig - Emacs-style keybindings for Awesome (eg. 'M-S-a' vs awful.key({modkey, 'Shift'}, 'a')
  • cheeky - A simple type-ahead window switcher (uses native clients menu)
  • dreary - Temporary/overwritable client keybinds
  • keyjoy - Change your mouse and keyboard properties on a per-client basis using rules.
  • Repetitive - Record and execute macros. Pin tags, clients and macros to F-keys at runtime
  • Revelation - Implementing Mac OS X Exposé in awesome.
  • Treetile - Treetile is binary tree-based and dynamical tiling layout for Awesome 3.5 and latter. you can split the screen in the way similarly to tmux or i3wm.



Most people these days are used to having a more complete desktop. This section includes links to various apps that are lightweight and useful from within awesome to fill the gaps between just a window manager and a full-blown desktop environment like KDE or GNOME.

  • Customizing GTK Apps - How to use themes without gnome-settings-daemon.
  • Terminals - Replacements for desktop environment terminals.
  • File Managers - Lightweight stand-alone File Managers.
  • Automounting - A replacement for "gnome-volume-manager", "thunar-volman", etc.
  • Xscreensaver - Locking the screen; replacement for gnome-screensaver, etc.
  • Calendars - calendars and agenda solutions (text, graphical, interactive, ...)
  • PowerManagement - A replacement for gnome-power-manager or kpowersave