🌿 bspwm-setup

A minimal but functional BSPWM rice script for Debian-based systems.
Installs all core packages, window manager configs, and themes — ready to go out of the box.

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

📖 Deep dive: the wiki. New to bspwm? Start with Bspwm Concepts. Want to understand the pieces, the tab tool, the scratchpad system, the theme switcher? Pages exist for each.

---

🚀 Installation

Quick Install

git clone https://justaguy.dev/drew/bspwm-setup.git
cd bspwm-setup
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_CORE in install.sh before running, or use --only-config to skip package installation entirely.

Installation Options

The installer supports the following options:

./install.sh [OPTIONS]

Options:
  --only-config      Only copy config files (skip packages and external tools)
  --help             Show help message

Features:

• Streamlined installation: Simpler, more reliable installation process
• Better error handling: Installation fails fast on errors to prevent partial setups

Package Installation: Packages are installed in logical groups (core, UI, file manager, audio, utilities, terminal, fonts) for better organization.

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 bspwm sxhkd polybar 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 bspwm sxhkd polybar 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 bspwm sxhkd polybar 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 (useful for non-Debian systems)
./install.sh --only-config

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

---

📦 What It Installs

Component	Purpose
bspwm	Tiling window manager
sxhkd	Hotkey daemon
picom (yshui)	Compositor for transparency
polybar	Status bar
rofi	Application launcher
dunst	Notifications
kitty	Terminal emulator (main)
tabbed	Embedded tabbing for X apps
firefox-esr	Default web browser
thunar + plugins	File manager
pipewire	Audio handling
flameshot	Screenshot tool
qimgv	Lightweight image viewer
eza, fd-find, etc.	Utilities & enhancements

---

🤔 Why These Pieces?

The full rationale for each component (and why this stack over alternatives like mako/i3blocks/dmenu-only) lives in the wiki's Architecture page.

---

🎨 Appearance & Theming

• Minimal theme with custom wallpapers
• Polybar with optimized layout: system info (left), workspaces (center), controls (right)
• Enhanced polybar with multiple font support (Roboto Mono, FontAwesome, Hack Nerd Font)
• Dunst, rofi, and GTK themes preconfigured
• Wallpapers stored in ~/.config/bspwm/wallpaper
• GTK Theme: Orchis
• Icon Theme: Colloid

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

---

🔑 Keybindings Overview

Key Combo	Action
Super + Enter	Launch terminal (kitty)
Super + Shift + Enter	Toggle scratchpad terminal
Super + Space	Launch rofi
Super + Q	Close focused window
Super + /	Help via keybind viewer
Super + T	Cycle desktop layout
Super + B	Launch Firefox
Super + Shift + B	Launch Firefox (private window)
Super + F	Launch file manager (Thunar)
Super + E	Launch text editor (Geany)
Super + G	Launch GIMP
Super + D	Launch Discord
Super + O	Launch OBS
Super + Shift + R	Restart bspwm
Super + Shift + T	Theme switcher (rofi)
Super + 1-0, -, =	Switch to workspace 1-12
Super + Shift + 1-0, -, =	Move window to workspace 1-12
Super + Alt + 1-3	Toggle scratchpad slot 1-3 (see below)
Super + Alt + A	Toggle "audio" named scratchpad
Super + Alt + N	Toggle "notes" named scratchpad

Keybindings are configured via:

• ~/.config/bspwm/sxhkd/sxhkdrc
• ~/.config/bspwm/scripts/help (run manually or with Super + /)

On first login, a welcome notification points to ~/QUICKSTART-bspwm.md — a short cheat sheet you can delete when you're comfortable.

Note: sxhkd only reliably binds keys in the a-z / standard ASCII range. If you use a non-US keyboard layout (German, French, Russian, Japanese, etc.), bindings that involve characters outside that range may not fire. You'll need to rework the relevant sxhkdrc entries to use keysyms that exist on your layout, or remove them.

---

📑 Tab Management

Super + W puts the focused window into a tab container; Super + Shift + W detaches. Inside a container, Alt + Tab cycles tabs, Alt + 1..0 jumps to a specific tab.

Built on the suckless tabbed tool with a small C reparenting helper (bspwm-tabs). Deep dive — including the libX11 internals, theming, and troubleshooting — on the Tabs wiki page.

---

📥 Scratchpad Promotion

Promote any focused window into a numbered or named "scratchpad slot" you can summon and dismiss with a keybinding — inspired by dwm's scratchtagwins patch and i3's move scratchpad.

Key Combo	Action
Super + Alt + {1,2,3}	Slot 1/2/3: add focused window if empty, else toggle
Super + Alt + Shift + {1,2,3}	Release slot 1/2/3
Super + Alt + A	Named slot "audio"
Super + Alt + N	Named slot "notes"

---

🎨 Theme Switcher

Super + Shift + T opens a rofi menu of available themes. Each theme swaps the bspwm border colors, polybar palette, rofi palette, dunst notification colors, kitty color scheme, GTK theme + icons, and wallpaper.

Shipped themes: Catppuccin, Doom One, Dracula, Everforest, GitHub Dark (default), Gruvbox, Kanagawa, Monokai, Moonfly, Nord, Retro, Rose Pine Moon.

See the Themes wiki page for how it works, how to add a theme, or how to extend what the switcher touches.

---

📂 Configuration Files

~/.config/bspwm/
├── bspwmrc                # Main bspwm config
├── sxhkd/
│   └── sxhkdrc            # Keybinding configuration
├── colors.sh              # Active bspwm border colors (sourced by bspwmrc; theme-managed)
├── polybar/
│   ├── config.ini
│   └── colors.ini         # Active polybar palette (theme-managed)
├── dunst/
│   └── dunstrc            # Color values theme-managed via sed
├── rofi/
│   ├── config.rasi
│   ├── power.rasi
│   ├── keybinds.rasi
│   └── colors.rasi        # Active rofi palette (@imported by the above; theme-managed)
├── scripts/
│   ├── changevolume
│   ├── help
│   ├── power
│   ├── scratchpad
│   ├── scratchpad-promote
│   └── thememenu          # Theme switcher (rofi)
├── themes/
│   └── <name>/            # Per-theme colors.{sh,ini,rasi} + theme.conf manifest
├── bspwm-tabs/
│   └── (tab manager source, built during install)
├── tabbed/
│   └── (tabbed source and config)
├── wallpaper/
│   └── (wallpaper images)

Terminal Configuration

Both roles use kitty:

• Main terminal (Super + Enter): kitty
• Scratchpad terminal (Super + Shift + Enter): a class-tagged kitty window

---

🔍 HiDPI / 4K Displays

Tiny type on a 4K screen? There's no single scaling knob — each toolkit (X fonts, GTK, Qt, the cursor) has to be told separately. bspwmrc ships a commented HiDPI block at the top; uncomment it and restart bspwm (Super + Shift + R). Full walkthrough — 200% vs 150%, GTK/Qt/cursor, the bar — on the Troubleshooting wiki page under HiDPI / 4K displays.

---

🎨 Customization

Colors are handled by the theme switcher (Super + Shift + T). For layout, fonts, gaps, keybindings, and other non-color tweaks, see the Customization wiki page — it walks through each config file with examples.

---

Credits

This project is a config on top of other people's software. The window manager and keybinding daemon are the work of baskerville — bspwm and sxhkd. Both have been stable and minimal for years; this setup adds nothing to them, only composes them with other pieces.

Other upstream projects this setup relies on: tabbed from suckless; picom (yshui fork); polybar; rofi; dunst; feh; kitty. GTK + icon themes by vinceliuice — Orchis and Colloid.

---

License

GPL-2.0 - See LICENSE for details.

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