bspwm Tiling Window Manager

bspwm organizes windows as leaves in a binary tree. This tiling window manager runs on X11 systems and handles multiple displays. It partially follows EWMH standards and requires separate programs for keyboard input.

The software uses a client-server model. The bspc program sends messages to the window manager through a socket. A hotkey daemon like sxhkd translates key presses into bspc commands.

Features

bspwm represents windows as nodes in a binary tree structure. Each monitor contains desktops, and each desktop points to a tree. The window manager supports EWMH and Xinerama protocols.

Configuration happens through shell scripts that call bspc. No special syntax exists – just standard bash commands. This design lets you use any shell tool in your configuration.

Getting Started

Install both bspwm and sxhkd packages. Most distributions include them in their repositories:

$ sudo apt install bspwm sxhkd

Add this line to ~/.xinitrc:

exec bspwm

Run startx to launch the window manager. You’ll see a blank screen – this is normal.

Setting Up Your Environment

Copy example configs from /usr/share/doc/bspwm/examples/. Create the config directories first:

$ mkdir -p ~/.config/bspwm ~/.config/sxhkd
$ cp /usr/share/doc/bspwm/examples/bspwmrc ~/.config/bspwm/
$ cp /usr/share/doc/bspwm/examples/sxhkdrc ~/.config/sxhkd/
$ chmod +x ~/.config/bspwm/bspwmrc

Adding a Key Binding Daemon

sxhkd handles keyboard shortcuts. Create ~/.config/sxhkd/sxhkdrc with these bindings:

# Terminal
alt + Return
  terminator

# Reload sxhkd
alt + Escape
  pkill -USR1 -x sxhkd

# Application launcher
alt + d
  dmenu_run

# Quit/restart bspwm
alt + shift + {q,r}
  bspc {quit,wm -r}

Start the daemon in bspwmrc:

sxhkd &

Drawing a Wallpaper

Install nitrogen for wallpaper management:

$ sudo apt install nitrogen
$ nitrogen --set-scaled /path/to/image.png

Add this command to bspwmrc to set the wallpaper at startup.

Setting Up a Compositor

Install picom for transparency and shadows:

$ sudo apt install picom

Launch it in bspwmrc:

picom &

Adding a Status Bar

Polybar provides system information and workspace indicators. Install it through your package manager or compile from source.

Copy a config to ~/.config/polybar/config. Launch it in bspwmrc:

pkill polybar
~/.config/polybar/launch.sh &

The bspwm Client

The bspc command controls all window manager functions. It sends socket messages to modify layouts, windows, and settings.

Node Actions

Nodes represent windows in the binary tree. Control them with bspc node commands:

Command	Action
bspc node -c	Close window
bspc node -k	Kill window
bspc node -d 7	Send to desktop 7
bspc node -p north	Preselect north

Add these to sxhkdrc:

# Send window to desktop
alt + shift + {1-9}
  bspc node -d '^{1-9}'

# Close and kill
alt + {_,shift + }c
  bspc node -{c,k}

# Preselect direction
super + ctrl + {h,j,k,l}
  bspc node -p {west,south,north,east}

Window State Actions

Windows exist in four states:

State	Description
Tiled	Size determined by window tree
Floating	Moves and resizes freely
Pseudo-tiled	Tiled but constrained to floating size
Fullscreen	Fills monitor with no borders

Switch states with keybindings:

alt + {t,shift + t,s,f}
  bspc node -t {tiled,pseudo_tiled,floating,fullscreen}

Window Rules

Configure per-application behavior in bspwmrc. Find window classes with xprop:

$ xprop | grep WM_CLASS

Click the target window. Use the class name in rules:

bspc rule -a Firefox desktop='^2' follow=on
bspc rule -a Gimp desktop='^8' state=floating

Layouts

bspwm offers multiple layout modes that determine how windows split and arrange.

Automatic Layout

The default mode splits windows into a binary tree. Each spawn creates two child nodes from the focused window.

Manual Layout

Preselect where the next window appears. Use bspc node -p to choose a direction:

$ bspc node -p north

The next window spawns in that location.

Longest Side Layout

Windows split along their longest dimension. Wide windows split vertically, tall ones split horizontally.

Configure in bspwmrc:

bspc config automatic_scheme longest_side

Spiral Layout

Windows arrange in a spiral pattern. Each new window takes the space of the insertion point and rotates the tree.

bspc config automatic_scheme spiral

Polarity

Polarity determines which child node gets split for new windows.

First Child Polarity

Splits the first child node. This is the default behavior.

bspc config initial_polarity first_child

Second Child Polarity

Splits the second child instead:

bspc config initial_polarity second_child

Configuring Layout Keybindings

Create a script to switch layouts with notifications. Save to ~/.config/bspwm/layout.sh:

#!/bin/bash
bspc config automatic_scheme $1
notify-send "Layout: $1"

Make it executable and add to sxhkdrc:

alt + ctrl + {1,2,3}
  ~/.config/bspwm/layout.sh {longest_side,spiral,first_child}

Working with Multiple Displays

List connected displays:

$ xrandr -q
$ bspc query -M --names

Assign workspaces to monitors in bspwmrc:

bspc monitor DVI-I-1 -d I II III IV
bspc monitor DVI-I-2 -d V VI VII
bspc monitor DP-1 -d VIII IX X

Set display order explicitly:

bspc wm -O DVI-I-1 DVI-I-2 DP-1

Common Issues

Configuration requires time and experimentation. Documentation exists but remains scattered across wikis and forums.

sxhkd breaks with fish shell due to the ^ character. Set a different shell:

$ export SXHKD_SHELL=/bin/sh

Java applications sometimes misbehave. Add this to bspwmrc:

wmname LG3D

GTK3 windows may display incorrectly. Edit ~/.config/gtk-3.0/gtk.css:

.window-frame {
  box-shadow: 0 0 0 black;
  border-style: none;
  margin: 0;
  border-radius: 0;
}

Getting Help

Check the manual pages for detailed options:

$ man bspwm
$ man bspc
$ man sxhkd

The GitHub repository contains examples and documentation. IRC and Matrix channels provide community support.