Awesome WM carefully configured by JustAGuy Linux. Built with Debian in mind.
  • Lua 77.3%
  • Shell 22.7%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
2026-11-08 08:53:07 -05:00
awesome says prefer-dark at startup, firefox's system theme goes light without it 2026-11-08 08:53:07 -05:00
screenshots updating awesomewm with color theme switching and reduced config files 2026-09-23 20:36:31 -04:00
.gitignore adding gitignore 2025-09-04 10:56:41 -04:00
CONTRIBUTING.md lives at butter/awesome now, and the name drops -setup 2026-10-30 18:15:15 -04:00
install.sh dropped xvkbd, nothing uses it 2026-11-08 08:18:49 -05:00
LICENSE update license 2026-02-01 17:56:48 -05:00
QUICKSTART.md quickstart: right-click the swirl for the color schemes 2026-11-04 17:08:04 -05:00
README.md README says what running the installer again does 2026-11-07 16:59:01 -05:00

🪄 AwesomeWM Modular Configuration

Made for Debian

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.

AwesomeWM Setup Screenshot


🚀 Installation

Quick Install

git clone https://justaguy.dev/butter/awesome.git
cd awesome
chmod +x install.sh
./install.sh

⚠️ XLibre users: This script installs xorg as part of its core packages, which will replace XLibre if you've installed it. Remove xorg from PACKAGES in install.sh before running, or use --only-config to 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 .desktop files
  • Watches the application directories, so anything you apt install appears 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 = false in variables.lua leaves 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; press Super + / to see the live list
  • Media keys (XF86Audio*) and Super + F10-F12 for volume
  • Five scratchpads (Super + Shift + Return for a terminal, and more)
  • Super + x power menu

Autostart

  • scripts/autorun.sh starts 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, or colorscheme in variables.lua
  • wallpaper per scheme: wallpaper in themes/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

Buy me a coffee

Connect

License

GPL-2.0 - See LICENSE for details.


Made with 🧈 by JustAGuyLinux