Awesome Window Manager — Highly Configurable Tiling WM for X11

Introduction

Awesome is a highly configurable, next-generation tiling window manager for X11. It provides a framework for managing windows, tags (virtual desktops), and layouts via a Lua configuration file. Unlike static tiling managers, Awesome ships with sensible defaults and can be extended into a full desktop environment.

What Awesome WM Does

• Tiles, floats, and maximizes windows with multiple built-in layout algorithms
• Uses tags instead of workspaces, letting one window appear on multiple tags simultaneously
• Exposes a complete Lua API for widgets, keybindings, signals, and rules
• Renders a fully scriptable status bar (wibar) with system info, tasklist, and custom widgets
• Supports multi-monitor setups with per-screen tag lists and independent layouts

Architecture Overview

Awesome is written in C and embeds a Lua interpreter (LuaJIT-compatible). The X11 connection is managed via XCB, and drawing uses Cairo. The Lua API wraps every core concept (clients, tags, screens, signals) so the entire window-management policy lives in the user's rc.lua configuration file rather than compiled code.

Self-Hosting & Configuration

• Config lives at ~/.config/awesome/rc.lua; a default is generated on first run
• Themes control colors, fonts, wallpaper, and icon paths via theme.lua
• Install community widgets from awesome-copycats or streetturtle/awesome-wm-widgets
• Use naughty library for desktop notifications directly from the WM
• Test config changes with Xephyr before applying to a live session

Key Features

• Full Lua scripting: every aspect of behavior is programmable
• Dynamic layouts: switch between tiling, floating, magnifier, and spiral per tag
• Tag system: more flexible than fixed-number workspaces
• D-Bus integration for external scripts and notifications
• Extremely lightweight: idles at under 10 MB of RAM

Comparison with Similar Tools

• i3 — manual tiling with a simpler config language; less programmable
• Hyprland — Wayland compositor with animations; not X11
• bspwm — binary-space tiling controlled entirely via bspc commands
• dwm — minimal suckless WM configured by editing C source and recompiling
• xmonad — Haskell-based tiling WM with strong type-safe configuration

FAQ

Q: Does Awesome work on Wayland? A: No. Awesome targets X11 via XCB. For Wayland, consider Hyprland or Sway.

Q: Can I use Awesome as a full desktop environment? A: Yes. With a compositor, notification daemon, and Lua widgets, Awesome can replace a traditional DE.

Q: How do I add gaps between tiled windows? A: Set beautiful.useless_gap in your theme or use the awful.layout gap property.

Q: Is it hard to learn Lua for the config? A: The default rc.lua is well-commented. Basic Lua is straightforward and the Awesome API docs cover every object.

Sources

• https://github.com/awesomeWM/awesome
• https://awesomewm.org/apidoc/