bspwm Documentation

bspwm is a tiling window manager that represents windows as leaves of a full binary tree. It operates by responding to X events via a dedicated socket.

Key Components:

• bspwm: The window manager core.
• bspc: The client program used to send messages to the bspwm socket.
• sxhkd: A recommended third-party tool to map keyboard/pointer events to bspc commands.

Hierarchy:

• Monitors: Rectangular areas containing desktops.
• Desktops: Pointers to a window tree.
• Trees: A partition of a monitor's rectangle into rectangular regions via internal nodes (splits) and leaf nodes (windows).

The configuration for bspwm is defined in a shell script located at $XDG_CONFIG_HOME/bspwm/bspwmrc. This script should contain bspc commands to set up your environment.

When bspwm executes this script, it passes an argument to indicate the execution context:

• $1 -gt 0: The script is being executed after a restart.
• $1 -eq 0: The script is being executed for the first time (initial startup).

Note: bspwm does not handle keyboard or pointer inputs directly. You must use a third-party program like sxhkd to translate input events into bspc invocations.

To install bspwm from source, ensure you have the required dependencies installed first. Then, compile and install using make and make install.

$ make
# make install

To remove bspwm that was installed from source, run the following command in the source directory:

# make uninstall

The bspc utility is the primary interface for controlling bspwm. The general syntax for commands is:

bspc 'DOMAIN' ['SELECTOR'] 'COMMANDS'

Domains include node, desktop, monitor, wm, rule, and config.

Official packages for bspwm are available for several Linux distributions and BSD:

• Arch Linux: bspwm-git (AUR) or bspwm (community)
• Debian: bspwm package
• Gentoo Linux: bspwm or bspwm-git (via ebuilds)
• FreeBSD: Available via Ports
• Void Linux: Available via documentation/wiki
• Manjaro Linux: Available via community forums
• BunsenLabs: Available via community forums
• Chakra: Available via CCR
• Exherbo: Available via git

Before building bspwm from source, you must install the following dependencies:

• libxcb
• xcb-util
• xcb-util-wm

Use bspc config <setting> [<value>] to get or set global, monitor, desktop, or node settings.

Example Global Settings:

• normal_border_color: Color of the border of an unfocused window (#RRGGBB).
• active_border_color: Color of the border of a focused window of an unfocused monitor.
• focused_border_color: Color of the border of a focused window of a focused monitor.
• window_gap: Size of the gap that separates windows.
• border_width: Window border width.
• focus_follows_pointer: Whether focus follows the pointer.

Use bspc rule --add to define rules for how windows are managed when they appear.

Syntax: bspc rule --add [class_name][:instance_name[:name]] [options]

Available Options:

• monitor=MONITOR_SEL / desktop=DESKTOP_SEL / node=NODE_SEL
• state=STATE (tiled, floating, etc.)
• layer=LAYER (below, normal, above)
• split_dir=DIR (north, west, south, east)
• (hidden|sticky|private|locked|marked|center|follow|manage|focus|border)=on|off

Use bspc desktop to manipulate desktops. If no selector is provided, the focused desktop is targeted.

Common Commands:

• focus [DESKTOP_SEL]: Focus a desktop.
• activate [DESKTOP_SEL]: Activate a desktop.
• to-monitor MONITOR_SEL [--follow]: Send desktop to a monitor.
• layout CYCLE_DIR|monocle|tiled: Set or cycle desktop layout.
• rename <new_name>: Rename the desktop.
• remove: Remove the selected desktop.