A new window manager can make it hard to tell how application windows are arranged and controlled. Awesome is an X11 window manager that uses layouts to arrange windows and tags to group them.
This guide shows how to install and start Awesome on Arch Linux, then use its default controls and find its configuration file.
TL;DR: What Awesome Does
Awesome is a keyboard-friendly, Lua-configurable window manager for X11 that arranges application windows using layouts and tags. On Arch Linux, install the awesome package, choose its session at login, and begin with the supplied configuration before adding custom widgets or themes.
- Awesome manages windows, while a desktop environment usually bundles other desktop services and applications.
- Tags group windows, and layouts decide how the visible windows occupy the screen.
- The main user configuration is typically ~/.config/awesome/rc.lua.
What Is the Awesome Window Manager?
Awesome provides keyboard-driven control over application windows through a Lua configuration.
A desktop environment such as GNOME or KDE Plasma normally combines a window manager with a panel, settings tools, launchers, and other desktop services. Awesome leaves those companion applications to you, rather than bundling a complete desktop suite.
In Awesome terminology, a client is an application window, a tag is a named group, and a layout is the rule used to arrange visible clients.
Select a different tag to change the visible group. Change the layout to rearrange it. The default setup includes tiled and floating arrangements, which can be changed without restarting an application.
The project targets X11, so choose its session when your graphical stack uses Xorg. If Wayland is a requirement, compare a Wayland option such as Sway instead.
Starting with the default session exposes tags, key bindings, and layouts before theme changes obscure those defaults.
How to Install and Start Awesome on Arch Linux
The Arch package repository provides Awesome as a normal package, so use the distribution package route rather than an AUR development build unless you specifically need unreleased code.
The commands below change the computer where you run them. Review the package manager’s proposed transaction before confirming it.
- An Arch Linux installation with an existing graphical login path.
- A working display manager, or an X session started through xinit.
- Access to install packages with your normal administrator authorization.
Step 1: Install the Awesome package
Install the repository package with pacman. This gives you the distribution-built Awesome package and its packaged session files. Review the transaction summary and accept it only if the listed changes are what you expect.
sudo pacman -S awesome
Package names and availability vary across Linux distributions, so do not copy this Arch command into Debian or Fedora. Check your distribution’s current package documentation before using its package manager.
Step 2: Select the Awesome session
After installation, log out of the current graphical session. At the login screen, open the session selector and choose Awesome, then sign in. A display manager is the graphical login program that can offer installed desktop and window-manager sessions.
If you start X with xinit instead, the Awesome project documents adding this command to ~/.xinitrc, then starting X with startx:
exec awesome
Use one session path at a time. A display-manager session and an xinit session both start the window manager, but they are configured through different entry points.
Step 3: Learn the default controls
Once the session opens, use the Mod4 key, usually the Windows key, with the default shortcuts. Mod4+s opens the key-binding help popup, Mod4+r opens the run prompt, and Mod4+Return starts the configured terminal when one is available.
Mod4+1 through Mod4+9 select tags, while Mod4+Space changes the active layout. These defaults are useful for a first session because they let you explore without editing Lua. The official key list is documented in the Awesome manual page.
Step 4: Locate and back up the configuration
Awesome reads a user configuration from ~/.config/awesome/rc.lua by default. The project includes a sample configuration, and the Arch package commonly places its system-wide copy under /etc/xdg/awesome/rc.lua. Confirm that source file exists on your installation before copying it.
mkdir -p ~/.config/awesome
cp /etc/xdg/awesome/rc.lua ~/.config/awesome/rc.lua
If you already have a user configuration, do not overwrite it. Make a copy first, then edit the user file in a text editor. Keep the backup outside the way of Awesome’s default rc.lua lookup so you do not accidentally load an older copy.
Step 5: Check a configuration before reloading
Lua edits can stop the window manager from loading if they contain a syntax error or refer to a missing module. Awesome’s check option validates a configuration file without replacing the running session. Run it against the exact file you changed:
awesome --check ~/.config/awesome/rc.lua
Fix any reported issue before restarting or logging out. The manual documents Mod4+Control+r as the default restart shortcut, but keeping a separate terminal or recovery login path available is prudent while editing session configuration.
Using Awesome After the First Login
Start by treating tags as workspaces and layouts as window-arrangement rules, then change one configuration setting at a time. This separates a navigation issue from a layout issue and helps identify which Lua edit caused a change.
For example, keep a browser on one tag and a terminal on another, then switch tags with Mod4 plus the tag number. If you want both windows visible together, move or tag the relevant client into the same view and choose a tiled layout. The master and stacking areas determine which client receives the main area in common tiled arrangements.
Awesome’s default configuration also includes a panel, tag list, layout indicator, and key bindings. These are parts of the configuration rather than a requirement to install a particular theme. Try the included behavior first, then change the relevant Lua objects only when you can name the result you want.
The configuration is Lua code, and Awesome exposes documented APIs for layouts, clients, tags, keys, widgets, and spawning applications. A theme can change visual details such as fonts and colors, while rc.lua controls session behavior and widget setup.
Back up the configuration before editing and restart Awesome to check the result.
Use Awesome spawn functions for session applications that should start with the window manager. For a process managed across sessions, use the desktop’s user-service mechanism instead. Check whether the program already starts before adding another launch command.
These programs are separate from the window manager. A panel, launcher, compositor, notification daemon, or network applet can accompany the session. Follow each program’s startup instructions, and add only the components you need.
The error log can show why a session returned to the login screen. The Awesome project README notes that messages are commonly written to ~/.xsession-errors, though the exact path depends on how X starts. Switch to a text console or another working session to inspect the log.
A package update does not automatically update your custom configuration. When an API or default changes, compare rc.lua with the current documentation and porting notes. Keep a known-good copy before making compatibility edits.
If you are still deciding between tiling window managers, our guides to installing i3 and using Sway cover two other approaches.
If the session does not start, use the matching recovery path rather than reinstalling immediately. Check whether the package installed the session entry and whether the selected session can read your configuration. The following checks point to the likely layer:
| Symptom | Check | Next step |
|---|---|---|
| Awesome is absent from the login session list | Confirm the package installed its session entry and log out fully | Check your distribution package files and display-manager session documentation |
| Login returns to the greeter after choosing Awesome | Read the session error log, commonly ~/.xsession-errors | Resolve the first Lua or missing-program error shown there |
| Configuration edits stop the session loading | Run awesome --check against the user rc.lua | Restore the backup or correct the reported syntax issue |
| Wayland session is required | Check whether the selected compositor targets Wayland | Use a Wayland-focused window manager such as Sway |
A missing session entry is different from a Lua error: the first points to package or display-manager integration, while the second points to configuration. I would check the session path first because it avoids changing an otherwise valid user configuration.
A third-party configuration can bundle scripts, themes, and external applications. Read its installation instructions and inspect the files before copying them into ~/.config. The older walkthrough’s dotfiles repository is not a generic Awesome requirement, so a fresh user should first learn the stock session and add only specific components they need.
Conclusion: Start with the Default Configuration
Install the package for your distribution, learn the default controls, and keep a backup before customizing rc.lua. The project documentation describes its Lua configuration and X11 session model.
Use the official Awesome documentation for its configuration API and current concepts. For the package and session details, check the project README and your distribution’s current documentation.
FAQ
These answers cover common first-use questions about Awesome’s role and its configuration.
Is Awesome a desktop environment?
Awesome is a window manager and configuration framework. You can combine it with other desktop applications, but it does not bundle the full set of services and tools found in a desktop environment by default.
How do I start Awesome after installing it?
Choose the Awesome session in your display manager and sign in. With an xinit-based setup, the project documents adding exec awesome to ~/.xinitrc and starting the X session.
Where is the Awesome configuration file?
The usual user configuration path is ~/.config/awesome/rc.lua. The system package may provide a sample configuration under /etc/xdg/awesome/rc.lua.
Does Awesome support Wayland?
Awesome is an X11 window manager, not a Wayland compositor. Choose a Wayland-focused option such as Sway if Wayland support is required.