bspwm: A Tiling Window Manager Built on Binary Space Partitioning

What bspwm Is and the Problem It Solves

Manual window placement on a desktop is repetitive work. A tiling window manager automates it by dividing the screen into non-overlapping regions and assigning each window to a region automatically. bspwm implements this using a binary space partitioning tree: every split of the screen produces two regions, each of which can be split further, forming a tree where the leaves are the windows themselves.

The project targets Linux users on X11 who want full control over window layout through configuration files and scripts rather than through a graphical settings panel. It is designed for people who are comfortable editing configuration in a text editor and running commands from a terminal. Users who want a window manager that works without any configuration will find bspwm unsuitable. Its defaults do nothing until a bspwmrc file is present and sxhkd is running.

bspwm does not handle keyboard or pointer inputs directly. Its design delegates that responsibility entirely to a separate program. The README states: "bspwm doesn't handle any keyboard or pointer inputs: a third party program (e.g. sxhkd) is needed in order to translate keyboard and pointer events to bspc invocations."

The Socket-Based Control Architecture

bspwm's architecture is built around a dedicated Unix socket. The window manager itself responds to X events and to messages it receives on that socket. `bspc` is the program that writes messages to the socket. Every window management action, from moving a window to changing a split ratio to querying the desktop layout, is accomplished by running `bspc` with the appropriate arguments.

The README illustrates the architecture:

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

sxhkd monitors keyboard and pointer events and, when a bound key is pressed, invokes `bspc` with a specific command. bspc sends that command over the socket to bspwm, which applies the change to the window tree. The two programs communicate only through the socket.

This separation has a practical consequence: any program that can invoke a shell command can send instructions to bspwm. Status bars, scripts, and session managers can all call `bspc` directly. The cost is that nothing happens if sxhkd is not running and no keybindings have been set. A minimal working setup requires at minimum a bspwmrc file that calls `bspc` to configure desktops, a sxhkdrc file that defines keybindings, and both bspwm and sxhkd launched at session start.

Configuration via bspwmrc and sxhkd

The default configuration file is `$XDG_CONFIG_HOME/bspwm/bspwmrc`. The README describes it as a shell script that calls `bspc`. A path argument is passed to the script to indicate whether it was executed after a restart (`$1 -gt 0`) or as the initial launch (`$1 -eq 0`), which allows different initialization logic for each case.

Keyboard and pointer bindings are defined separately in a file read by sxhkd, typically placed at `$XDG_CONFIG_HOME/sxhkd/sxhkdrc`. The repository includes example configurations in its `examples/` directory: `examples/bspwmrc` and `examples/sxhkdrc` show a working starting point.

bspwm supports multiple monitors, each holding a list of desktops, each desktop pointing to a binary tree of windows. The user navigates between desktops and windows through bspc commands that sxhkd translates from keypresses. The Makefile defines the binary prefix as `/usr/local/bin` by default, controllable via the `BINPREFIX` variable at build time.

The README notes that the source depends on several XCB libraries: `libxcb`, `libxcb-util`, `libxcb-keysyms`, `libxcb-icccm`, `libxcb-ewmh`, `libxcb-randr`, `libxcb-xinerama`, and `libxcb-shape`. All must be present before building from source. Distribution packages handle these dependencies automatically; building from source requires installing them manually.

How Windows Are Placed: Insertion Modes

When bspwm receives a new window, it inserts it at the current insertion point using the current insertion mode. The default mode is automatic, but users can switch to manual mode for fine-grained control.

In manual mode the user sends a `node -p` message to specify where the next window should appear: north, south, east, or west of the current window. The insertion point enters manual mode, and the next new window is placed according to that direction. After insertion the mode resets.

Automatic mode has three schemes. The `longest_side` scheme looks at the dimensions of the target rectangle and splits along its longest axis. The `alternate` scheme alternates the split direction each time, based on the parent's split type. The `spiral` scheme inserts the new window so that it takes the space of the insertion point while the existing tree rotates 90 degrees, producing a clockwise or counter-clockwise spiral of windows depending on which child position the insertion point occupies.

The split ratio, which controls how evenly the rectangle is divided between the two resulting regions, defaults to half but can be changed per node with `node -o|--presel-ratio`. This allows unequal splits, for example a 30/70 division for a narrow sidebar alongside a main editor view.

What bspwm Does Not Provide

bspwm is an X11-only window manager. The README lists support for the RandR and Xinerama protocols and a subset of EWMH and ICCCM standards, but Wayland is not supported. Developers moving to Wayland compositors must use a different tool. Hyprland and sway are two commonly mentioned Wayland tiling compositors with their own configuration systems.

bspwm provides no built-in status bar, application launcher, notification daemon, or compositor. Each of these must be installed and configured separately. The README references `examples/panel/` for a panel script example, but the panel itself is not part of bspwm.

The BSD-2-Clause licence does not restrict commercial use, modification, or redistribution, but it does require preserving the copyright notice and the disclaimer. The two conditions are minimal compared to copyleft licences.

The Makefile defines install targets for bash, fish, and zsh completions for bspc alongside the binaries themselves, which simplifies tab completion setup once the build is complete.

Installing bspwm and Getting Started

Major Linux distributions package bspwm in their official repositories. On Arch Linux, `sudo pacman -S bspwm sxhkd` installs both the window manager and the key binding daemon. On Debian and Ubuntu, `sudo apt install bspwm sxhkd` is the equivalent. For distributions without a package or for users who need the latest version from source, the Makefile in the repository supports building with standard tools.

The Makefile builds two binaries: `bspwm` (the window manager) and `bspc` (the controller). The `install` target copies them to `$(DESTDIR)$(BINPREFIX)`, which defaults to `/usr/local/bin`, and installs the manual pages under `$(MANPREFIX)/share/man`. Shell completions for bash, fish, and zsh are installed from the `contrib/` directory.

Once the binaries are installed, the next step is creating a bspwmrc and sxhkdrc. The repository's `examples/` directory contains starting configurations that demonstrate desktop setup, window rules, and common bspc calls. Without at least a minimal bspwmrc that calls `bspc config` to set up desktops, bspwm starts but displays nothing.

Comparing bspwm to i3 and Other Tiling Window Managers

i3 is one of the most widely used tiling window managers for X11. It uses a different tree model: i3's tree has explicit container types (horizontal, vertical, tabbed, stacked), and the user directs splits explicitly. bspwm's binary tree is simpler in structure: every split produces exactly two children, and the automatic schemes determine placement without requiring explicit container-type decisions. The bspc socket interface gives bspwm finer programmatic control at the cost of a steeper initial configuration.

i3 includes its own keybinding configuration in its main config file; bspwm requires sxhkd as a separate program. This is a meaningful difference in setup complexity. On the other hand, the socket-based control architecture means that any script can query and modify bspwm state directly, without parsing a config file or simulating key events.

For tiling on Wayland, neither bspwm nor i3 is a realistic option. The README makes no claims about Wayland compatibility.

Editorial conclusion

bspwm is the right choice for a developer who wants precise, scriptable control over window layout on X11 and who is willing to configure sxhkd and write a bspwmrc from scratch. Users who want a window manager that works without manual configuration, or who are moving to Wayland, should look elsewhere. The last push was on 2026-06-19, and the BSD-2-Clause licence permits free use and redistribution with minimal conditions.

Frequently asked questions

Official sources

1. baskerville/bspwm on GitHub
2. Issues
3. License: BSD-2-Clause
4. README