🪟 oxwm-setup

Made for Debian OXWM Version Themes Stars Forks Last Commit

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.1

1 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.

OXWM Setup Screenshot

🚀 Installation

Quick Install

git clone https://codeberg.org/justaguylinux/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

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:
   • WezTerm (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

UI & System Tools

External Tools (via butterscripts)

💡 st is also bundled in this repo (oxwm/st/) if you prefer it — set oxwm.set_terminal("st") in config.lua.

🎨 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 + /.

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:

🎭 Theme System

6 themes ship under oxwm/themes/ — github_dark (default), gruvbox, catppuccin, dracula, everforest, retro. 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, WezTerm scheme, 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. Sets the WezTerm color scheme (auto-reloads) 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
├── st/ # Bundled st terminal (optional alternative to WezTerm)
├── 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/wezterm/
└── wezterm.lua # Terminal configuration (color scheme set by theme switch)

License

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

Support

Buy me a coffee

Connect

• YouTube — tutorials and guides
• Codeberg — 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