bspwm is a lightweight tiling window manager for X11 that organizes windows as the leaves of a full binary tree. Control your desktop through bspc, configure shortcuts with sxhkd, and build a fast, minimal Linux workflow.
bspwm, short for Binary Space Partitioning Window Manager, is a lightweight tiling window manager for X11. Instead of placing windows freely on the desktop, bspwm represents them as the leaves of a full binary tree and automatically divides available screen space between them.
Its design separates window management from keyboard input. The bspwm process manages windows and desktops, while bspc sends commands to bspwm through its socket. Keyboard and pointer shortcuts are commonly handled by sxhkd, giving users precise control over how their desktop behaves.
bspwm focuses on fast window management, predictable tiling and complete configuration control. Its binary-tree layout, command-based architecture and modular workflow make it especially useful for users who prefer a minimal and keyboard-driven Linux desktop.
bspwm represents windows as leaves of a full binary tree. Each new window becomes part of a split structure, allowing the available screen area to be divided in a predictable and organized way.
The bspc command-line client communicates with bspwm and can be used to manage nodes, desktops, monitors and configuration settings from scripts or terminal commands.
bspc config window_gap 10
✓
bspwm is commonly paired with sxhkd for keyboard shortcuts. This keeps hotkey handling separate from the window manager and gives users freedom to define their own workflow.
Manage different monitors and desktops independently. bspwm can assign desktops to displays and lets you move or focus windows across monitors using simple bspc commands.
Windows are not limited to one layout style. bspwm supports tiled, pseudo-tiled, floating and fullscreen states, allowing individual windows to behave differently when needed.
Settings such as border width, window gaps, split ratio, focus behavior and desktop rules can be controlled through the bspwmrc configuration file and bspc commands.
bspwm organizes the desktop around a tree of nodes. Each managed window occupies a node, while internal nodes define how the available screen space is split between windows.
This structure allows windows to be focused, moved, resized and rearranged without relying on traditional overlapping placement. Desktops belong to monitors, and each desktop can maintain its own independent binary tree.
When a new managed window appears, bspwm inserts it into the current desktop's tree according to the active insertion point.
The selected node is divided and screen space is shared between the existing window and the newly inserted window.
Commands can focus nodes, move them between desktops, change states, adjust split ratios and modify layout behavior.
Install bspwm together with sxhkd, add the example configuration files, and make the bspwm startup script executable. Choose your Linux distribution below to view the appropriate setup commands.
sudo pacman -S bspwm sxhkd
install -Dm755 /usr/share/doc/bspwm/examples/bspwmrc ~/.config/bspwm/bspwmrc
install -Dm644 /usr/share/doc/bspwm/examples/sxhkdrc ~/.config/sxhkd/sxhkdrc
The example bspwmrc file is installed with executable permission, while sxhkdrc contains the keyboard shortcut configuration.
sudo apt update
sudo apt install bspwm
mkdir -p ~/.config/bspwm ~/.config/sxhkd
Debian's bspwm package depends on sxhkd, so the hotkey daemon is normally installed automatically with bspwm.
git clone https://github.com/baskerville/bspwm.git
cd bspwm
make
sudo make install
Building from source requires the development dependencies listed by the bspwm project, including libxcb and the relevant xcb utility libraries.
bspwm is configured mainly through the bspwmrc startup script. You can define desktops, window gaps, border sizes, split behavior, focus settings and application rules with simple bspc commands.
bspc monitor -d I II III IV V VI VII VIII IX X
bspc config border_width 2
bspc config window_gap 10
bspc config split_ratio 0.52
bspc config borderless_monocle true
bspc config gapless_monocle true
bspc rule -a Firefox desktop=^2
bspc rule -a Gimp state=floating
sxhkd &
bspwm does not handle keyboard shortcuts itself. A separate hotkey daemon such as sxhkd is commonly used to map key combinations to terminal commands and bspc actions. This keeps the window manager simple while giving you full control over your keyboard workflow.
Launch your preferred terminal instantly with a simple Super-key combination.
Send a command to the focused node and close the selected application quickly.
Move focus between neighboring windows without touching the mouse.
Jump between numbered desktops and keep different tasks organized in separate workspaces.
Send the focused window to another desktop while keeping your current workspace organized.
Change a selected window from tiled behavior to a floating state when free placement is more useful.
These combinations are examples of a keyboard-driven setup.
Edit your ~/.config/sxhkd/sxhkdrc file to choose
the shortcuts and commands that match your own workflow.
Most bspwm issues come from session startup, configuration files, sxhkd, window rules or monitor setup. Use these quick checks to find common problems and understand where to look when your bspwm setup does not behave as expected.
If the bspwm session fails immediately, check that the main configuration file exists and has executable permission. bspwmrc is a shell script, so permission or syntax problems can prevent the session from starting correctly.
chmod +x ~/.config/bspwm/bspwmrc
A minimal bspwm session may look almost empty because bspwm does not provide a desktop panel, launcher or wallpaper by itself. If no shortcuts work either, check whether sxhkd started successfully.
pgrep -a sxhkd
bspwm does not process keyboard shortcuts itself. If your keybindings stop working, the issue is usually related to sxhkd, its configuration, a conflicting shortcut or an invalid command.
pkill -USR1 -x sxhkd
Editing bspwmrc does not automatically guarantee that every new command has already been applied to the running session. Test the command directly with bspc or rerun the configuration script.
~/.config/bspwm/bspwmrc
bspwm rules depend on the application properties used by your rule. If a program does not match the expected class or name, the rule may never be applied.
xprop WM_CLASS
bspwm keeps a list of monitors, and desktops belong to monitors. If your monitor order changes, review the monitor names and then assign desktops to the intended display.
bspc query -M --names
Many startup and layout problems can be traced back to a command, path or syntax issue inside your bspwmrc script.
If bspwm is running but shortcuts do nothing, troubleshoot the hotkey daemon before changing the window manager itself.
Multi-monitor problems are easier to diagnose when you first confirm which displays bspwm currently recognizes.
bspwm is designed for lightweight X11-based Linux desktop environments. It does not require a full desktop environment and can be combined with the tools you prefer for hotkeys, panels, notifications and application launching.
bspwm is an X11 window manager. It manages windows through the X Window System and is intended for sessions running on X rather than acting as a native Wayland compositor.
The command-line client used to send messages and commands to bspwm.
Core ComponentCommonly used to map keyboard and pointer shortcuts to bspc commands.
RecommendedYour bspwmrc and sxhkdrc files define startup behavior and shortcut mappings.
User Configurablebspwm can manage desktops across multiple monitors and allows monitor-specific workspace layouts.
SupportedAll four are popular choices for users who want more control than a traditional desktop environment provides, but they approach window management and configuration differently. Here is a practical comparison to help you understand where bspwm fits.
bspwm represents windows as leaves of a binary tree and exposes control through the bspc command-line client. Keyboard and pointer bindings are normally handled separately by a tool such as sxhkd.
A tiling window manager built around binary space partitioning and controlled through messages sent by bspc.
A tiling X11 window manager with a dedicated configuration format, extensive documentation and an IPC interface for external control.
A highly configurable framework window manager for X with dynamic layouts, tags, widgets and extensive customization through Lua.
A compact dynamic window manager from suckless that is customized primarily by editing its C configuration and rebuilding the program.
| Feature | bspwm | i3 | awesome | dwm |
|---|---|---|---|---|
| Primary Approach | Binary tree tiling | Tiling containers | Framework + layouts | Dynamic tiling |
| Main Configuration | Shell / bspc | Config file | Lua | C source |
| Keyboard Handling | External daemon | WM configuration | Lua configuration | Compiled configuration |
| Command / IPC Control | bspc socket messages | IPC interface | Lua API / client tools | Limited by default |
| Customization Style | Modular | Config driven | Programming oriented | Source oriented |
| Best Fit | Users who like scripting and modular tools | Users wanting a straightforward tiling setup | Users wanting deep Lua-based customization | Users comfortable modifying source code |
Its separation between window management, command control and keyboard handling makes it easy to combine bspwm with other Unix tools and build a desktop around your own scripts and preferences.
Find quick answers to common questions about bspwm, including how it works, its configuration files, sxhkd integration, X11 support and whether it is the right tiling window manager for your Linux setup.
bspwm is a tiling window manager for X11 that represents windows as the leaves of a full binary tree. Instead of manually positioning every tiled window, bspwm organizes screen space through tree-based splits and can be controlled using messages sent through the bspc command-line client.
bspwm stands for Binary Space Partitioning Window Manager. The name describes its approach to arranging windows using a binary tree that repeatedly divides the available screen area.
bspwm has a focused and modular design. It concentrates on window management rather than providing a complete desktop environment, allowing users to choose separate utilities for hotkeys, panels, launchers, notifications and other desktop functions.
bspwm is an X11 window manager, not a native Wayland compositor. If you want a Wayland-native environment, you will need a window manager or compositor designed specifically for Wayland.
bspwm does not handle keyboard or pointer input itself. sxhkd is commonly paired with bspwm to translate hotkeys into commands, including bspc commands. Other compatible input or hotkey tools can also be used.
bspc is the command-line client used to communicate with bspwm. It can send commands for managing nodes, desktops and monitors, as well as changing configuration settings and window rules.
A common user configuration location is
~/.config/bspwm/bspwmrc. The bspwmrc file is an
executable startup script where users can run bspc commands,
configure desktops, define window behavior and launch other
programs needed for the session.
Yes. bspwm supports multiple monitors. Monitors and their desktops can be addressed through bspc, allowing users to organize workspaces and move or focus windows across a multi-monitor setup.
Beginners can use bspwm, but it generally requires more manual setup than a complete desktop environment. Learning basic shell configuration, bspc commands and sxhkd shortcuts makes the setup process much easier.
bspwm can be used on Linux distributions that provide the required X11 environment and dependencies. Package availability and installation commands vary by distribution, so users should check their distribution's repositories or build bspwm from source when appropriate.