bspwm

bspwm is a tiling window manager that represents windows as the leaves of a full binary tree. It is lightweight, highly configurable, and follows the UNIX philosophy of "do one thing well."

Key Features

  • Tiling windows using a binary tree structure
  • Multiple monitors and desktops support
  • EWMH compliance for compatibility with panels and pagers
  • Flexible window rules system
  • Keyboard and mouse driven (via external tools like sxhkd)
  • Scriptable via shell commands using bspc
  • Multiple automatic insertion schemes: spiral, alternate, longest_side
  • Hot restart without losing window state

Architecture

bspwm only responds to X events and messages received on a dedicated socket.

bspc is the command-line tool that writes messages to bspwm's socket.

bspwm doesn't handle any keyboard or pointer inputs: a third party program (e.g. sxhkd) is needed to translate keyboard and pointer events to bspc invocations.

        PROCESS          SOCKET
sxhkd  -------->  bspc  <------>  bspwm

Quick Start

After installing bspwm, create your configuration:

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

Add to your ~/.xinitrc:

sxhkd &
exec bspwm

Documentation

Configuration

The default configuration file is $XDG_CONFIG_HOME/bspwm/bspwmrc (usually ~/.config/bspwm/bspwmrc).

The configuration file is a shell script that gets executed on startup. It typically:

  1. Starts the hotkey daemon (sxhkd)
  2. Configures monitors and desktops
  3. Sets appearance options (borders, gaps, colors)
  4. Defines window rules
  5. Starts autostart applications

See the Settings Reference for all available options.

Monitors, Desktops and Windows

  • Monitor: A physical display
  • Desktop: A virtual workspace on a monitor
  • Node: A container in the binary tree (can hold a window or be empty)
  • Window: An actual X11 window

Each monitor contains one or more desktops. Each desktop contains a binary tree of nodes. Windows are attached to leaf nodes.

Window States

  • tiled: Size and position determined by the window tree
  • pseudo_tiled: Shrinks but doesn't stretch beyond floating size
  • floating: Can be moved/resized freely, still part of the tree
  • fullscreen: Fills monitor rectangle, no borders

Stacking Layers

There are three stacking layers: BELOW, NORMAL, and ABOVE.

In each layer, windows are ordered: tiled & pseudo-tiled < floating < fullscreen.

Community