bspwm: a binary space partitioning window manager driven by bspc messages
A tiling window manager based on binary space partitioning
At a glance
- What is it?
- bspwm represents every window as a leaf of a full binary tree and exposes all control through a socket that bspc writes to. Here is how the tree, the insertion modes and the bspwmrc config fit together, and where the design stops being the right choice.
- Who is it for?
- Adopt bspwm if you want the window layout to be an explicit tree you can address with bspc messages, and you are willing to run a separate hotkey daemon such as sxhkd and to write bspwmrc as a shell script. Do not adopt it if you need Wayland, or if you expect the compositor and key handling to ship in the same binary.
- Can I use it commercially?
- Yes. BSD-2-Clause is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 149 days ago.
- What is it written in?
- Mainly C, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- baskerville/bspwm8,334 ★ · +17
| Repository | 2026-09-22 | 2026-11-15 |
|---|---|---|
| baskerville/bspwm | 8.3k | 8.3k |
17 Stars in the last 54 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
The problem bspwm solves: layout as a tree you can address
Most tiling window managers give you a layout algorithm and a set of keybindings that drive it. bspwm separates the two. The window manager itself, according to the README, "only responds to X events, and the messages it receives on a dedicated socket." Everything you do to the layout is a message. The bspc program is the client that writes those messages.
That split is the whole point. Because bspwm holds no opinion about keyboards or pointers, a third party program such as sxhkd translates key presses into bspc invocations. The README outlines the flow as sxhkd to bspc to bspwm over a socket. You can therefore drive the same layout from a shell script, a panel, a status bar hook or a test, without a plugin API. The examples/ directory includes panel and external_rules, which is consistent with that design.
Who it is for: people who want to reason about their screen as a data structure. A monitor is a rectangle, a desktop is a pointer to a tree, and the tree is a partition of that rectangle into smaller rectangles. Any split in that tree is a node with exactly two children, a type (horizontal or vertical) and a ratio r with 0 < r < 1. If that model sounds natural to you, the rest of the interface follows from it.
How the binary tree and insertion modes actually work
Every internal node splits a rectangle in half. Every leaf holds exactly one window. There is no third case: a node has zero or two children, never one. When a new window arrives, bspwm inserts it at an insertion point, which is a leaf, using the insertion mode attached to that point. By default the insertion point is the focused window and its mode is automatic.
Manual mode is the explicit path. You send node -p or --presel-dir with a direction, and the insertion point is split in that direction. The direction also decides whether the new window becomes the first or the second child of the new internal node, with the old insertion point becoming its brother. The README walks through exactly this with windows 1, 2, 3, then node -p north, then a new window 4, then node -p west and window 5. The ratio of that preselection, which becomes the ratio of the new split, is set with node -o or --presel-ratio.
Automatic mode removes the choice. The README documents three schemes. With longest_side, the split direction follows the dimensions of the tiling rectangle and the initial polarity: a wide window is split vertically, a tall one horizontally. With alternate, the direction is the opposite of the insertion point's parent split, so a horizontally split parent yields a vertical split. With spiral, the new window takes the space of the insertion point. The initial polarity setting decides which side the new window lands on, and the README's example sets it to second_child.
This is where bspwm differs from managers that expose a fixed set of layouts. You are not choosing between a master-stack and a grid; you are choosing a rule for rewriting a tree, and you can override it per insertion point.
Installing bspwm and writing a first bspwmrc
The repository ships doc/INSTALL.md, and the Makefile builds two binaries, bspwm and bspc, from src with a C99 toolchain. The link line names the X libraries the build expects: xcb, xcb-util, xcb-keysyms, xcb-icccm, xcb-ewmh, xcb-randr, xcb-xinerama and xcb-shape, plus libm. If your distribution packages bspwm, that is the shorter route; if you build from source, the Makefile's own targets are make and make install.
make
make installThe install target copies bspwm and bspc into BINPREFIX, which defaults to /usr/local/bin, along with man pages, shell completions for bash, fish and zsh, and the Markdown docs. PREFIX, BINPREFIX and MANPREFIX are all overridable, so a staged install into DESTDIR is supported by the same target.
Configuration is a shell script, not a declarative file. The default path is $XDG_CONFIG_HOME/bspwm/bspwmrc, and the README states that it "is simply a shell script that calls bspc." An argument is passed to it: $1 -gt 0 means it ran after a restart, $1 -eq 0 means it did not. That argument is how you avoid re-running one-time setup on every reload. The examples directory contains a bspwmrc and an sxhkdrc to compare against.
For a first real use, pick the manual insertion path so the tree model becomes visible. Focus a window, preselect a direction, then open a terminal.
bspc node -p north
bspc node -o 0.7The first command splits the focused leaf toward the north and puts the insertion point into manual mode; the next window you open appears there. The second changes the preselection ratio to 0.7, which becomes the ratio of the new split.
What bspwm deliberately does not do
The README is blunt: bspwm "doesn't handle any keyboard or pointer inputs." Out of the box, that means a fresh session with no sxhkd running has no keybindings at all. You can still drive it, but only through bspc from a terminal or a script. This is not a bug to work around; it is the boundary of the program. If you want a window manager that owns its own hotkey configuration, bspwm is the wrong tool and the README says so by pointing at sxhkd.
The second boundary is X. The README describes bspwm as responding to X events, and the Makefile links against XCB libraries. Nothing in the repository suggests a Wayland backend. If your session is Wayland, bspwm does not apply, and no amount of bspc scripting changes that.
A third constraint is subtler. The tree is a partition of the monitor rectangle, and each leaf holds exactly one window. That is what makes the model predictable, and it is also why floating and overlapping layouts are not the natural case. The repository does carry an examples/overlapping_borders directory, but the README's own description of the data structure is a partition, so overlapping windows sit outside the model rather than inside it. If your workflow is mostly stacked, overlapping windows with occasional tiling, the binary tree is overhead you will spend effort working around.
Finally, the README documents the protocol and the tree, not operational concerns. There is no rollback procedure described, and doc/TODO.md exists in the repository, which tells you the maintainers keep an open list. Treat the README as a specification of behaviour rather than a runbook.
bspwm compared with i3 and dwm
The closest comparison people reach for is i3, and the difference is architectural rather than cosmetic. i3 ships its own keybinding configuration and its own layout containers; you configure it in a text file and it handles the input path itself. bspwm splits that into two programs, with sxhkd owning the keys and bspc owning every layout change. In practice that means an i3 configuration is one file describing both keys and layout, while a bspwm setup is at least a bspwmrc plus an sxhkdrc, and the layout logic can live in shell. The tree is also stricter: bspwm's nodes have zero or two children, and splits are defined by a type and a ratio r with 0 < r < 1, where i3's containers are a more general nesting model.
dwm takes the opposite approach again. It is configured by editing and recompiling source, so there is no runtime configuration file at all. bspwm keeps the runtime configuration as a shell script and the layout as messages, which means you can change the desktop layout of a running session without rebuilding anything. If you want a window manager you configure once in C and never touch again, dwm fits that; if you want to script layout changes from outside the window manager, bspwm's socket does.
Neither comparison is a verdict. The useful question is whether you want the input layer and the layout layer to be one program or two.
Maintenance, build cost and the BSD-2-Clause licence
The repository is not archived, and the last push was on 2026-06-19. The repository has no published GitHub releases, so versioning comes from the build: the Makefile derives the version with git describe --tags and falls back to the VERSION file when that fails. If you build from a source tarball without git history, expect the VERSION file's value rather than a tag.
Upgrade cost is low by construction. There is no package manager, no runtime dependency tree and no plugin ecosystem to track. The build is a C99 compile of a fixed source list, and the link line is the list of XCB libraries above. The practical upgrade risk is therefore in the X libraries and in your own bspwmrc, not in bspwm's internals. Since bspwmrc is a shell script that calls bspc, a change to a bspc message name is a change you would notice at session start, not at compile time. The man pages for bspwm and bspc are installed alongside the binaries, so the authoritative message list travels with the install.
The licence is BSD-2-Clause, per the LICENSE file at the repository root. That is a permissive licence, and the usual consequence is that you can redistribute modified binaries without publishing your changes, provided you keep the copyright notice and the licence text. It is not a copyleft licence, so it does not force derived work open. This is a description of what the licence family generally means, not legal advice; read LICENSE in the repository and, if the distinction matters to your organisation, get it reviewed.
One cost the repository does not hide: doc/TODO.md is part of the installed documentation, and the README is a specification of the tree and the message protocol rather than a tutorial. Budget time for reading bspc's man page.
Editorial conclusion
Adopt bspwm if you want the window layout to be an explicit tree you can address with bspc messages, and you are willing to run a separate hotkey daemon such as sxhkd and to write bspwmrc as a shell script. Do not adopt it if you need Wayland, or if you expect the compositor and key handling to ship in the same binary. Before committing, verify that your distribution packages both bspwm and bspc, that the X libraries named in the Makefile (xcb, xcb-util, xcb-keysyms, xcb-icccm, xcb-ewmh, xcb-randr, xcb-xinerama, xcb-shape) are available, and read doc/INSTALL.md rather than assuming the README covers the build.
Frequently asked questions
Is bspwm a tiling window manager?
Yes. The README describes bspwm as a tiling window manager that represents windows as the leaves of a full binary tree, where each internal node splits a rectangle in half.
How to configure bspwm?
The default configuration file is $XDG_CONFIG_HOME/bspwm/bspwmrc, which the README says is simply a shell script that calls bspc. It receives an argument indicating whether it ran after a restart ($1 -gt 0) or not ($1 -eq 0). Keyboard and pointer bindings are defined separately with sxhkd.
how to use bspwm
You control the layout by sending messages to bspwm's socket with bspc, for example node -p north to preselect a split direction or node -o to set the preselection ratio. Since bspwm handles no keyboard or pointer input, a program such as sxhkd is needed to turn key presses into bspc invocations.
how to install bspwm
The repository ships doc/INSTALL.md, and the Makefile builds bspwm and bspc with make followed by make install. The install target places the binaries in BINPREFIX, which defaults to /usr/local/bin, along with man pages and shell completions.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/baskerville-bspwm)Star history chart for your README
[](https://hysenlabs.com/projects/baskerville-bspwm)Was this useful?