Main Page

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:

• Stable: awesome 3.5.1 (Ruby Tuesday).
• Development: Development versions of awesome can be downloaded as tarballs using git snapshots.
• Screenshots: Screenshots

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

• Awesome 3.x - Manpage and keyboard shortcuts.
• FAQ - Check here first if you're having problems!
• Building awesome - Instructions for building / installing awesome.
• awesome 3 configuration - Get help understanding awesome 3 configuration and API basics.
• awesome 3.0 to 3.1 config options that changed between the releases
• awesome 3.3 to 3.4 configuration changes to the 3.4 version
• awesome 3.4 to 3.5 configuration changes to the 3.5 version
• Quickly Setting up Awesome with Gnome - How to make awesome be used in your gnome session with a couple of commands.
• KDE and awesome
• My first awesome Tutorial for new users and beginners

Development Basics

• Using Xephyr
• Debugging
• Signals

Reviews & News

• awesome 3 review on penguinsightings

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

Statusbars and widgets

• Widgets in awesome - A brief guide on the implementation of widgets within awesome.
• Vicious - How to use the vicious widget library to add dynamic widgets.
• Obvious - How to use the Obvious repo (Widgets with community support).
• User Contributed Widgets
• Using Cairo within Awesome
• Titlebar and Statusbar height - Small how-to that helps you customize statusbar and titlebar height.
• Bashets - Small Lua library to empower you to use your existing shellscripts as content providers for widgets.
• Launcher auto-hiding - Hide a launcher when the application is running

Theming awesome

• Theming with Beautiful - How to theme your awesome-3 with the beautiful library.
• User Contributed Themes - Several awesome themes for use with beautiful.
• Customizing Fonts - How to add new fonts to your system.
• Nice Icons - Where to find nice icons to use in your widgets.
• Picturesque - Automatically fetch and change wallpapers

User configuration files

Examples of other users' configuration files.

Other tips

• Autostart - Small function providing autostart functionality for awesome.
• Autostop - Simple method to execute a program on quitting awesome.
• Understanding Rules - Describes Awesome's awful.rules facility for applying modifications to selected windows.
• NASA IOTD_Wallpaper - Use NASA's "Image of the day" as wallpaper using feh
• Run or raise - Run a client, or pop to it if it is already running.
• Revelation - Implementing Mac OS X Exposé in awesome.
• Global Keybindings - Create global keybindings in awesome.
• Document keybindings - Add documentation to each keybinding and display an "help" panel
• Keybindings and numeric pad - Use the numeric pad to go to tags and show menus associated to each tag
• Gradient - Visual feedback on numerical data (e.g. processor usage).
• Problems with Java - What to do if your java apps look grey.
• Symbolic tag names - How to make your tags have that mysterious symbolic look.
• XRandR Screen Table - If you don't like using numbers for screens.
• Move Mouse - Move the mouse from the centre of the screen for mouseless working.
• Dbus, naughty and logs - Display colorized notifications of your logs.
• Naughty log watcher - Native implementation (no shell scripts/dbus required).
• Using Xephyr - How to run nested X sessions - good for testing new builds of awesome or different config files.
• Using Multiple Screens - How to setup X with multiple screens/monitors for use with awesome.
• Fullscreens on Multiple Screens - How to span a client on multiple screens/monitors with a key
• nm-applet - How to setup nm-applet to start automatically in awesome.
• Mcabber notifications - Cool notifications for mcabber via naughty.
• Drop-down terminal - Toggle a video game-like console on the top of your screen like Yakuake/Tilda.
• Scratchpad manager - Basic scratchpad manager for the awesome window manager.
• WMII-like tag management - Mimic WMII's way of tag managment.
• Video wallpaper - Play a video for your wallpaper using mplayer.
• Transparency - Transparent windows using xcompmgr.
• Coverart display - Display Cover Art for current mpd song.
• Urxvt tips - Tips for using rxvt-unicode with awesome.
• Irssi tips - Tips for using Irssi with awesome.
• IM tips - Tips for using instant messaging clients with awesome.
• Remove icons - How to remove icons from the tasklist and show only current client.
• Custom Prompts - Customized prompts you can use with awful's prompt.
• Using dmenu - Altering the color scheme, integrating with beautiful, and Run or Raise.
• Run commands in background - Run shell-commands in background (without hanging awesome!) and returns it's output.

• Shutdown dialog - A simple dialog to shutdown/reboot/suspend/lock screen.
• Tree File Menu - Python script to generate a tree file menu.
• Cycling Random Wallpaper Or Xscreensaver - Cycle you background to a random picture or Xscreensaver after a random delay
• Blinking text - Blinking the text on textbox widget
• RPN Calculator - RPN calculator
• Modal Keybindings
• Shared tags share tagset for multiple screens
• Move Window to Workspace Left/Right - A function for moving a window one workspace to the left or right.
• Move Client to Monitor Left/Right - How to move client to a specific direction when using more than two monitors.
• Move Client to a specific Monitor - How to move a client to a specific monitor.
• Move Focus to a specific Monitor - How to move the curser/focus to a specific monitor.
• Better Font Rendering
• Disable startup-notification globally - If you are annoyed by the stopwatch/busy mouse cursor.
• Keeping multitags persistent - If you want to able to quickly jump back to a multitag configuration
• Conky bar - A statusbar-like Conky configuration which is not overlapped by windows
• Workaround plugins that steal the keyboard focus - This has been a known bug in Firefox for over 10 years.
• MPD information with mpdcron
• Autostart with consolekit - Using awesome menu to restart/shutdown/hibernate/suspend your computer
• Vmware - Awesome and vmware tools

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.
• awful.menu - a popup menu library.
• 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
• 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
• Flaw - an object oriented library to manage widgets.
• couth - yet another extension library -- includes visual popup notifications for alsa and mpd volume.
• keychains - use of keychains in awesome

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