- Lua 77.3%
- Shell 22.7%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
| awesome | ||
| screenshots | ||
| .gitignore | ||
| CONTRIBUTING.md | ||
| install.sh | ||
| LICENSE | ||
| QUICKSTART.md | ||
| README.md | ||
🪄 AwesomeWM Modular Configuration
A modular, organized AwesomeWM configuration with clean separation of components. Twelve color schemes with matching wallpapers, a self-updating app menu, and a bar that keeps itself current — ready to use out of the box.
Part of the JustAGuy Linux window manager collection — installable standalone or via butterknife, the installer for Butterbian.
🚀 Installation
Quick Install
git clone https://justaguy.dev/butter/awesome.git
cd awesome
chmod +x install.sh
./install.sh
⚠️ XLibre users: This script installs
xorgas part of its core packages, which will replace XLibre if you've installed it. RemovexorgfromPACKAGESininstall.shbefore running, or use--only-configto skip package installation entirely.
Installation Options
./install.sh [OPTIONS]
Options:
--only-config Only copy config files (skip packages and external tools)
--help Show usage information
After install, it's yours. This setup is a starting point, not a setup that updates itself: change anything in ~/.config/awesome as you like. Running ./install.sh again replaces that folder; answer y at the prompt to keep the old one as ~/.config/awesome.bak.<number>, then copy your changes back from it. Your wallpapers and your color scheme are kept either way.
Distribution-Agnostic Installation
⚠️ UNSUPPORTED: Instructions for other distributions (click to expand)
IMPORTANT: These instructions are provided as-is for advanced users. Non-Debian distributions are NOT officially supported. Package names and availability may vary. Use at your own risk.
Arch Linux:
# Install dependencies (package names may differ)
sudo pacman -S awesome rofi dunst picom thunar xorg-xbacklight \
pamixer pavucontrol feh flameshot firefox \
network-manager-applet xfce4-power-manager ttf-font-awesome
# Copy configuration files
./install.sh --only-config
Fedora:
# Install dependencies (package names may differ)
sudo dnf install awesome rofi dunst picom thunar xbacklight \
pamixer pavucontrol feh flameshot firefox \
network-manager-applet xfce4-power-manager fontawesome-fonts
# Copy configuration files
./install.sh --only-config
openSUSE:
# Install dependencies (package names may differ)
sudo zypper install awesome rofi dunst picom thunar xbacklight \
pamixer pavucontrol feh flameshot firefox \
NetworkManager-applet xfce4-power-manager fontawesome-fonts
# Copy configuration files
./install.sh --only-config
Advanced Usage Examples
# Update only configuration files (keeps packages as they are)
./install.sh --only-config
Testing Configuration
# Test AwesomeWM configuration syntax before applying
awesome -k ~/.config/awesome/rc.lua
# Restart AwesomeWM (from within AwesomeWM session)
awesome.restart()
📦 Module Overview
| Module | Purpose |
|---|---|
variables.lua |
Default apps, modkey, tags, layouts. Start here |
keybindings.lua |
Keyboard shortcuts and per-window keys/buttons |
mousebindings.lua |
Desktop right-click menu and scroll |
menu.lua |
Right-click menu, applications generated from .desktop files |
widgets.lua |
Bar widgets: launcher, tags, layout, title, media, volume, stats, date and time, tray, power |
tagpreview.lua |
The miniature shown when hovering a tag |
screens.lua |
Tags and the top bar on each screen |
rules.lua |
What floats, what goes to which tag |
signals.lua |
Focus, borders, new-window placement, titlebars |
scratchpad.lua |
Dropdown terminal and apps |
export.lua |
Writes the color scheme out for rofi, dunst, kitty and GTK |
error_handling.lua |
Config errors as notifications |
🔑 Keybindings
AwesomeWM ships its own hotkeys popup — press Super + / at any time to see every binding, searchable and grouped by category. No separate rofi script needed.
On first login, a welcome notification points to ~/QUICKSTART-awesome.md — a short cheat sheet you can delete when you're comfortable.
✨ Key Features
Menu that keeps itself current
- Right-click the desktop for a menu built from your installed
.desktopfiles - Watches the application directories, so anything you
apt installappears a few seconds later
Bar
A floating bar framed in the accent, every module in a soft rounded chip that lightens under the mouse:
- Left: the Debian swirl opens the app launcher (right-click: the color scheme picker). The tags: the current one an accent pill with its number, one with windows a shaded cell with its number, an empty one a dot. A tag with windows also shows its apps' icons (up to three);
tag_icons = falseinvariables.lualeaves just the numbers. Hover a tag for a miniature of it, its windows where they sit (a hidden tag's windows as they looked when you left it). Then the layout as a symbol: click for the layout menu, scroll to step through. - Middle: the focused window's title.
- Right: what's playing (only while something plays), volume (click to mute, right-click for the mixer, scroll to change), brightness and battery on laptops, and one glyph that unfolds CPU, memory and disk ("CPU 3% · RAM 12% · / 40%"). Then the date and time (click for a calendar), the tray (the network applet lives there) and the power menu.
Color schemes
- Twelve palettes in
themes/default/colors.lua, eleven of them shared with the qtile setup (the same wallpapers too), each with a matching wallpaper Super + Shift + t(or right-click menu, awesome, color scheme) opens a picker and reloads- Rofi, dunst, kitty and GTK apps follow the scheme. Kitty uses
~/.config/awesome/kitty/and GTK themes are applied through a session-local xsettingsd, so other desktops on the same machine keep their own settings - From a terminal:
~/.config/awesome/scripts/colorscheme nord - Schemes: catppuccin, doomone, dracula, everforest, github_dark, gruvbox, kanagawa, monokai, moonfly, nord, retro, rose_pine
Keybindings
- Everything is in
keybindings.lua; pressSuper + /to see the live list - Media keys (
XF86Audio*) andSuper + F10-F12for volume - Five scratchpads (
Super + Shift + Returnfor a terminal, and more) Super + xpower menu
Autostart
scripts/autorun.shstarts the compositor, notifications and applets- Safe to reload: anything already running is skipped
🎨 Layouts Available
The following layouts are included:
- Tile - Master and stacking clients (default)
- Tile Left - Master on right, stacking left
- Fair - Equal area distribution
- Fair Horizontal - Equal horizontal distribution
- Spiral - Fibonacci spiral layout
🔧 Configuration Files
~/.config/awesome/
├── rc.lua # Loads the modules, in order
├── modules/
│ ├── variables.lua # Default apps, modkey, tags, layouts
│ ├── keybindings.lua # Keyboard shortcuts
│ ├── mousebindings.lua # Mouse on the desktop
│ ├── menu.lua # Right-click menu
│ ├── widgets.lua # Bar widgets
│ ├── screens.lua # Tags and bar per screen
│ ├── rules.lua # Window rules
│ ├── signals.lua # Focus, borders, placement
│ ├── scratchpad.lua # Dropdown terminal and apps
│ ├── export.lua # Colors for rofi, dunst, kitty, GTK
│ └── error_handling.lua # Error notifications
├── themes/
│ └── default/
│ ├── theme.lua # Fonts, borders, taglist, menu
│ └── colors.lua # Twelve color schemes
├── scripts/
│ ├── autorun.sh # Startup applications
│ ├── changevolume # Volume keys with notification
│ ├── colorscheme # Rofi scheme picker
│ └── power # Rofi power menu
├── dunst/
│ └── dunstrc # Notification daemon config
├── rofi/
│ ├── shared.rasi # The look every menu shares
│ ├── scheme.rasi # Colors, generated from the color scheme
│ ├── strip.rasi # The launcher strip's gradient, generated
│ ├── pat.png # Pat, on the launcher's strip
│ ├── config.rasi # App launcher (Pat's strip: `enabled: false` hides it)
│ ├── themes.rasi # Color scheme picker
│ └── power.rasi # Power menu
├── kitty/
│ ├── kitty.conf # Terminal config (session-local)
│ └── current-theme.conf # Generated from the color scheme
├── xsettingsd/
│ └── xsettingsd.conf # Generated: GTK and icon theme
└── picom/
└── picom.conf # Compositor configuration
📋 Module Details
⚙️ variables.lua
The settings most people change: terminal, browser, file manager, editor, modkey, color scheme, tag names and the layout list. Everything else reads from here.
⌨️ keybindings.lua
All keyboard shortcuts, grouped for the Super + / popup. Also defines the per-window keys and mouse buttons that rules.lua attaches to every client. Tag keys are generated in a loop from the tag list, layout keys from the layout list.
🖱️ mousebindings.lua
Right-click on the desktop opens the menu; scroll switches tags.
📋 menu.lua
Builds the right-click menu. The applications submenu is generated from .desktop files using awesome's built-in menubar code, grouped by category, and regenerated automatically when a package is installed or removed. favorites holds the terminal, browser and file manager from variables.lua.
📊 widgets.lua
Every widget in the bar, each in its chip: the launcher, taglist, layout symbol, title, what's playing, volume, brightness, battery, the folding cpu/memory/disk, date with calendar, time, tray and power. Stats come from /proc and /sys or one async command each, on their own timers; what's playing comes from one playerctl that follows the players and ends with awesome. Colors are the semantic names from the theme.
🖥️ screens.lua
For each screen: create the tags and build the top bar from the widgets.
📏 rules.lua
Default properties for every window, which classes float, scratchpad properties, and which apps are pinned to which tag.
📡 signals.lua
New windows open as slave, focus follows the mouse, border color on focus, and the titlebar layout if you enable titlebars for a client.
🗂️ scratchpad.lua
Dropdown windows toggled from the keyboard and kept alive when hidden. Matched by X instance name (kitty --name ...).
| Key | Scratchpad |
|---|---|
Super + Shift + Return |
Terminal (top of screen) |
Super + Shift + f |
ranger |
Super + Shift + v |
pulsemixer |
Super + Shift + m |
ncmpcpp |
Super + Shift + p |
pavucontrol |
🎨 export.lua
Writes the current scheme out for the other programs: rofi/scheme.rasi (imported by every rofi menu) and rofi/strip.rasi (the gradient of the launcher strip Pat stands on, from the background halfway to the scheme's second color), the color keys in dunst/dunstrc, kitty/current-theme.conf, and xsettingsd/xsettingsd.conf for the GTK and icon theme. Each program is told to reload, so open terminals and GTK windows recolor on the spot. Runs on every awesome start, only touching files whose content would change.
🚨 error_handling.lua
Startup and runtime errors go to stderr and to a critical dunst notification.
📑 Usage Example
rc.lua is just the load order. Each module exposes an init():
local variables = require("modules.variables")
beautiful.init(variables.theme)
require("modules.export").init()
awful.layout.layouts = variables.layouts
require("modules.menu").init()
require("modules.widgets").init()
require("modules.screens").init()
require("modules.rules").init()
require("modules.signals").init()
require("modules.keybindings").init()
require("modules.mousebindings").init()
awful.spawn.with_shell(variables.scripts_dir .. "autorun.sh")
Drop a module by deleting its line. Add one by writing a file in modules/ that returns a table with init().
🔍 HiDPI / 4K Displays
On a 4K screen, type can come up tiny. There's no single fix — AwesomeWM itself
doesn't scale, and it launches apps directly (awful.spawn), so the scaling has
to be set before awesome starts, where the whole session inherits it. The
installer drops a commented HiDPI block into ~/.xsessionrc for exactly this.
Open ~/.xsessionrc, uncomment the block, and log out / back in. It sets
Xft.dpi (X apps, fonts, cursor), GDK_SCALE/GDK_DPI_SCALE (GTK apps), and
QT_AUTO_SCREEN_SCALE_FACTOR (Qt apps) together; the defaults are ~200% and the
comments show how to dial it to ~150%. (Installed before this was added? Just add
the same lines to ~/.xsessionrc yourself.)
🔧 Customization
The most common customizations:
- variables.lua: preferred applications, tags, layouts
- keybindings.lua: keyboard shortcuts
- color scheme:
Super + Shift + t, orcolorschemeinvariables.lua - wallpaper per scheme:
wallpaperinthemes/default/colors.lua - themes/default/theme.lua: fonts, gaps, borders
- scripts/autorun.sh: startup programs
- widgets.lua: add or remove bar widgets
- rules.lua: how specific apps behave
Support
Connect
- YouTube — tutorials and guides
- Butterforge — source code and projects
- Butter desktops — ready-to-use window manager desktops for Debian
- The Butter Lab — Discourse forum
- The Churn — community chat (Fluxer)
- Wiki — documentation and guides
- Mastodon — @justaguylinux@fosstodon.org
- Butterbian — a maintained Debian derivative built on Debian stable
License
GPL-2.0 - See LICENSE for details.
Made with 🧈 by JustAGuyLinux

