🪟 oxwm-setup

A dynamic X11 window manager setup for Debian-based systems. oxwm is dwm-like, but configured in Lua with instant hot-reload — edit config.lua, press Mod+Shift+R, no recompile. This setup ships dwm-style keybinds, a GitHub-Dark-styled bar, and a 6-theme switcher.

Part of the JustAGuy Linux window manager collection — installable standalone or via butterknife, the installer for Butterbian.

---

🎩 Built by Tony Banters

oxwm is the work of Tony Banters — go watch and subscribe to his channel: ▶ YouTube. Hands down one of the most devoted, card-carrying, dyed-in-the-wool Debian fans you'll ever meet.¹

¹ He is not. He recently dropped a whole video rating Debian a resounding "meh." We kid — it's all banter. 🧈

---

⚡ Lua-Configured, Hot-Reloaded

Unlike suckless WMs, there's nothing to patch or compile:

• One file — ~/.config/oxwm/config.lua holds everything (keybinds, bar, rules, layouts).
• Instant reload — Mod+Shift+R re-reads the config live; tags and windows are preserved.
• Validate before you commit — oxwm --validate checks the config without launching.

---

🚀 Installation

Quick Install

git clone https://justaguy.dev/drew/oxwm-setup.git
cd oxwm-setup
chmod +x install.sh
./install.sh

The installer adds butterrepo and installs oxwm with apt — no building required.

⚠️ 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_CORE 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

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.

oxwm is distributed as a .deb via butterrepo, so on non-Debian systems you build it yourself:

1. Build and install oxwm from source: github.com/tonybanters/oxwm
2. Install the equivalent runtime packages with your distro's package manager (see the tables below).
3. Run ./install.sh --only-config to copy the configuration into ~/.config/oxwm.
4. Install Nerd Fonts (RobotoMono + JetBrainsMono) and, optionally, the Orchis GTK / Colloid icon themes for the theme switcher.

Note: The script can be run from any location — it auto-detects its directory.

What Gets Installed

1. System Update — updates package lists and upgrades existing packages
2. butterrepo — adds the APT repo that provides oxwm, picom, and rofi
3. oxwm — the window manager itself (apt install oxwm)
4. Core / UI / System packages — X11, file manager, audio, power management
5. External Tools — via butterscripts:
   • kitty (terminal emulator)
   • Nerd Fonts collection
   • Orchis theme & Colloid icons
   • LightDM display manager
6. Wallpapers — cloned from drewgrif/wallpapers
7. Optional Tools — additional browsers, editors, and utilities (prompted)

---

📦 What It Installs

Core Components

Component	Purpose
oxwm	Lua-scriptable X11 window manager (from butterrepo)
xdotool	Drives the theme-switch reload
xorg & tools	Display server and utilities
dbus-x11 libnotify-bin	Session bus + notifications
build-essential	Compilation tools

UI & System Tools

Component	Purpose
rofi	App launcher + theme/power menus
dunst	Lightweight notifications
feh	Wallpaper setter
picom	Compositor with transparency
nwg-look	GTK theme manager
xsettingsd	Applies GTK theme/icons live
network-manager-gnome	Network applet
lxpolkit	PolicyKit authentication agent
thunar	File manager (+plugins)
pavucontrol pamixer	Audio control + CLI volume
xfce4-power-manager	Power management
flameshot	Screenshot tool
qimgv	Lightweight image viewer
firefox-esr	Default web browser

External Tools (via butterscripts)

Component	Purpose
kitty	Default terminal emulator
Nerd Fonts	Icon-enabled fonts (RobotoMono, JetBrainsMono)
Orchis & Colloid	GTK theme and icons
LightDM	Display manager

---

🎨 Appearance & Theming

• GTK Theme: Orchis
• Icon Theme: Colloid

💡 Special thanks to vinceliuice for the excellent GTK and icon themes.

---

🔑 Keybindings Overview

All keybinds live in ~/.config/oxwm/config.lua and are hot-reloadable with Mod+Shift+R — no recompile, no separate hotkey daemon. Open the built-in cheatsheet anytime with Super + Shift + /.

Shortcut	Action
Super + Return	Launch terminal (kitty)
Super + Space	Launch rofi (drun)
Super + b	Firefox
Super + f	Thunar
Super + Shift + t	Theme switcher (rofi)
Super + Shift + e	Power menu (rofi)
Super + Shift + /	Keybind overlay
Super + q	Close focused window
Super + j / k	Focus next / previous window
Super + Shift + j / k	Move window down / up in stack
Super + h / l	Shrink / grow master area
Super + Alt + Tab	Fewer / more master windows (+Shift)
Super + Shift + Space	Toggle floating (opens centered)
Super + Shift + f	Toggle fullscreen
Super + Ctrl + b	Toggle bar
Super + n	Cycle layout
Shift + Ctrl + 1..7	Pick layout: dwindle / tiling / scrolling / grid / monocle / tabbed / floating
Super + [ / ]	Scroll left / right (scrolling layout)
Super + 1..9	View tag 1..9
Super + Shift + 1..9	Send focused window to tag
Super + Ctrl + 1..9	Toggle tag visibility
Super + Tab	Next tag (Shift = previous)
Super + , / .	Previous / next tag
Ctrl + Shift + ← / →	Focus previous / next monitor
Super + Shift + , / .	Send window to prev / next monitor
Super + Shift + s / s	Flameshot region / fullscreen
Super + F10 / F11 / F12	Mute / volume down / volume up
Super + Shift + r	Reload oxwm (preserves tags/windows)
Super + Shift + q	Quit oxwm

On first login, a quickstart cheat sheet lands at ~/QUICKSTART-oxwm.md (if present) — delete it once you're comfortable.

---

🧱 Layouts

Cycle with Super + n, or pick directly with Shift + Ctrl + 1..7:

#	Layout	Description
1	Dwindle	Fibonacci spiral (default)
2	Tiling	Master + stack
3	Scrolling	PaperWM-style horizontal strip — pan with Super + [ / ]
4	Grid	Even grid
5	Monocle	One full-screen window at a time
6	Tabbed	Stacked/tabbed
7	Floating	Free-floating ("normie")

---

🎭 Theme System

12 themes ship under oxwm/themes/ — github_dark (default), amber, catppuccin, doomone, dracula, everforest, gruvbox, kanagawa, monokai, moonfly, nord, rose_pine. Each theme is a directory of:

• colors.lua — the oxwm bar + border palette (dofiled by config.lua)
• colors.rasi — @imported by the rofi configs
• theme.conf — wallpaper, kitty theme name, GTK/icon theme names, dunst colors

Super + Shift + t opens thememenu (rofi). Picking a theme:

1. Copies colors.lua → active palette and colors.rasi → active rofi colors
2. Applies the kitty theme (via kitty +kitten themes) and GTK theme/icons (via xsettingsd)
3. Rewrites the # THEME:-tagged dunst colors and restarts dunst
4. Sets the wallpaper with feh
5. Presses Mod+Shift+R (via xdotool) so oxwm re-reads the new palette

The active theme is tracked in ~/.cache/oxwm/current_theme. Add a theme by creating themes/<name>/ with colors.lua, colors.rasi, and theme.conf.

---

📂 Configuration Files

~/.config/oxwm/
├── config.lua          # Everything: keybinds, bar, rules, layouts (edit this)
├── colors.lua          # Active palette (generated; seeded from themes/github_dark)
├── themes/             # Per-theme colors.lua + colors.rasi + theme.conf
│   └── <name>/
├── rofi/
│   ├── config.rasi     # Launcher / theme-menu theme
│   ├── power.rasi      # Power-menu theme
│   └── colors.rasi     # Active palette (@imported; replaced on theme switch)
├── dunst/
│   └── dunstrc         # Notifications (# THEME: lines rewritten on theme switch)
├── picom/
│   └── picom.conf      # Compositor configuration
├── scripts/
│   ├── thememenu       # Theme switcher (Super + Shift + t)
│   ├── changevolume    # Volume up/down/mute with notification
│   └── power           # Power-menu actions
└── wallpaper/          # Cloned from drewgrif/wallpapers at install time

~/.config/kitty/
├── kitty.conf          # Terminal configuration
├── current-theme.conf  # Active theme palette (swapped on theme switch)
└── themes/             # Custom themes (e.g. Trapped in Amber)

---

🔍 HiDPI / 4K Displays

On a 4K screen, type can come up tiny. There's no single fix — oxwm itself doesn't scale, and it launches apps directly (oxwm.spawn), so the scaling has to be set before oxwm 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.)

---

License

GPL-3.0 — See the GNU GPL v3 for details, matching upstream oxwm.

Support

Connect

• YouTube — tutorials and guides
• Butterforge — source code and projects
• The Butter Lab — Discourse forum
• The Churn — community chat (Fluxer)
• Wiki — documentation and guides
• Mastodon — @justaguylinux@fosstodon.org
• Butterbian — a Debian-based distro

---

Made with butter by JustAGuyLinux