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

---

🚀 Installation

Quick Install

git clone https://github.com/drewgrif/bspwm-setup.git
cd bspwm-setup
chmod +x install.sh
./install.sh

Installation Options

The installer now supports various options for different use cases:

./install.sh [OPTIONS]

Options:
  --only-config       Only copy config files (perfect for non-Debian distros)
  --skip-packages     Skip apt package installation
  --skip-themes       Skip theme, icon, and font installations
  --skip-butterscripts Skip all external script installations
  --dry-run          Show what would be done without making changes
  --help             Show usage information

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

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

# Preview what will be installed
./install.sh --dry-run

# Update only configuration files
./install.sh --only-config

# Skip package installation if already installed
./install.sh --skip-packages

# Install without themes and fonts
./install.sh --skip-themes

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 (FT-Labs)	Compositor for transparency
polybar	Status bar
rofi	Application launcher
dunst	Notifications
wezterm	Terminal emulator (main)
st	Simple terminal (scratchpad)
firefox-esr	Default web browser
thunar + plugins	File manager
nala	Better apt frontend
pipewire	Audio handling
flameshot,	Screenshot tools
micro	Terminal text editor
redshift	Night light
qimgv	Lightweight image viewer
fzf, etc.	Utilities & enhancements

Optional during install:

• geany + plugins - Lightweight IDE (installer will prompt)

📄 Need help with Geany? See the full guide at justaguylinux.com/documentation/software/geany

---

🎨 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 (wezterm)
Super + Shift + Enter	Toggle scratchpad terminal
Super + Space	Launch rofi
Super + Q	Close focused window
Super + H	Help via keybind viewer
Super + V	Audio mixer (pulsemixer) in scratchpad
Super + Shift + R	Restart bspwm
Super + 1-9,0,-,=	Switch to workspace 1-12
Super + Shift + 1-9,0,-,=	Move window to workspace 1-12

Keybindings are configured via:

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

---

📂 Configuration Files

~/.config/bspwm/
├── bspwmrc                # Main bspwm config
├── sxhkd/
│   └── sxhkdrc            # Keybinding configuration
├── polybar/
│   ├── config.ini
│   └── launch.sh
├── dunst/
│   └── dunstrc
├── rofi/
│   ├── config.rasi
│   └── theme.rasi
├── scripts/
│   ├── changevolume
│   ├── autoresize.sh
│   ├── power
│   ├── scratchpad
│   └── help
├── wallpaper/
│   └── (wallpaper images)

Terminal Configuration

The setup uses two terminals for different purposes:

• Main terminal (Super + Enter): Uses wezterm by default
• Scratchpad terminal (Super + Shift + Enter): Enhanced auto-detection with comprehensive fallback support

Scratchpad Terminal Support

The scratchpad system now supports multiple terminal emulators with intelligent fallback:

Supported terminals: st, ghostty, alacritty, kitty, wezterm, xfce4-terminal, gnome-terminal, konsole, urxvt

Priority order:

1. User-defined via BSPWM_SCRATCHPAD_TERMINAL environment variable
2. st (preferred for speed and minimal resource usage)
3. Automatic fallback through available terminals

To customize the scratchpad terminal, set the environment variable in your shell config:

export BSPWM_SCRATCHPAD_TERMINAL=ghostty  # or any terminal you prefer

Advanced scratchpad usage:

# Launch custom applications in scratchpad mode
Super + Shift + Enter    # Default terminal scratchpad
# Or via script: scratchpad pulsemixer, scratchpad htop htop, etc.

---

📺 Watch on YouTube

Want to see how it looks and works?
🎥 Check out JustAGuy Linux on YouTube