bspwm for dummies

Joseph George edited this page Jan 2, 2018 · 61 revisions

Welcome to the BSPWM tutorial. This will hopefully get you all set up and running in bspwm in no time.

DISCLAIMER: BSPWM is in active development That means that syntax might have changed since I wrote this tutorial. For the most up-to-date syntax, please look at the example files in the repository at

If you run into trouble, you can get help in #bspwm at

Download source files and dependencies

First you'll want to cd into any folder of your choice and run the following commands:

git clone
git clone

This will clone the repositories needed to install bspwm.

Install any dependencies you may be missing (there might be more than needed on this list as I didn't explicitly check).

On Debian-based distros:

sudo apt-get install xcb libxcb-util0-dev libxcb-ewmh-dev libxcb-randr0-dev libxcb-icccm4-dev libxcb-keysyms1-dev libxcb-xinerama0-dev libasound2-dev libxcb-xtest0-dev

NOTE : libxcb-ewmh-dev may be named libxcb-ewmh1-dev on your system

NOTE: The package libxcb-ewmh1-dev which is available on ubuntu 12.04.4 repositories seems to be causing a segmentation fault.

The workaround is to install libxcb-ewmh-dev from 14.04 repositories.

On Arch-based distros:

sudo pacman -S libxcb xcb-util xcb-util-keysyms xcb-util-wm

On Fedora 22:

sudo dnf install xcb-util-devel xcb-util-keysyms-devel xcb-util-wm-devel alsa-lib-devel dmenu rxvt-unicode terminus-fonts


You'll need make and gcc, but you most likely already have these

On Debian-based distros:

sudo apt-get install gcc make

On Arch-based distros:

sudo pacman -S gcc make

On Fedora 22:

sudo dnf groupinstall "Development Tools"

cd into bspwm, and run the following command:

sudo make install

If the make fails, download any missing dependencies (and email me and tell me your distro / missing packages so I can update this guide for everyone)

Do the same in the sxhkd repository you cloned.


Use one of the following methods depending on your case.

Without any Display Manager

Now the fun begins...

Copy bspwm/examples/bspwmrc to ~/.config/bspwm/bspwmrc and run chmod +x ~/.config/bspwm/bspwmrc

Copy bspwm/examples/sxhkdrc to ~/.config/sxhkd/sxhkdrc. Look at this file and learn the key bindings. Change any bindings you don't like. For instance, I prefer using alt over super (windows key). Change the line at 84 to match your preferred terminal editor (urxvt or xterm HIGHLY recommended over gnome-terminal, terminator)

Open up ~/.xinitrc and add the following to the bottom:

exec bspwm

With a Display Manager

If you use a display manager (like Lightdm, kdm, gdm or mdm (this means you Ubuntu folks)) you'll probably want to copy the file provided in contrib/freedesktop to its standard locations ie copy bspwm.desktop to /usr/share/xsessions/. Attention: This replaces the loading via the ~/.xinitrc, don't use both.

On Fedora/Ubuntu/Mint/Others:

sudo cp contrib/freedesktop/bspwm.desktop /usr/share/xsessions/

You'll now need to restart your display manager or simply reboot your machine.

sudo service [lightdm|kdm|gdm|mdm] restart

Logging into your new bspwm session

Now for the moment of truth. Type startx in your tty. If all went according to plan, you should be presented with a blank screen. That's good. Open up your preferred terminal using whatever key combination / terminal name you chose in your .config/sxhkdrc. If nothing happens, start trouble shooting.

For Fedora 22: When you log back on, click the "gear" icon and select 'bspwm'

Adding a panel


Install the tools used in the sample panel by cloning the repositories, and running a make && sudo make install in each of the cloned repository directories

git clone
git clone
git clone
git clone


Add the following to /etc/profile or /etc/zsh/zprofile (/etc/zprofile on Fedora 22): export PANEL_FIFO="/tmp/panel-fifo"

Copy the scripts in bspwm/examples/panel/panel and bspwm/examples/panel/panel_bar to some directory. Add this directory to your $PATH using export PATH=$PATH:/path/to/panel/scripts. Make the scripts executable running chmod +x panel panel_bar

Testing and Troubleshooting

You can then add the line panel & to the end of your bspwmrc. Run a startx again and there should be a panel. If you don't see it, its most likely because you did not set up your PANEL_FIFO variable. If echo $PANEL_FIFO yields nothing, the variable is not getting set. Log out and log back in.

Help! I get a blank screen and my keybindings don't work!

Without any Display Manager

There are a few ways to debug this. First, a blank screen is good. That means bspwm is running (usually).

I would confirm that your xinitrc looks something like

sxhkd &
exec bspwm

The ampersand is important. Next, try spawning a terminal in your xinitrc to see if its getting positioned properly. It should appear somewhat "centered" on the screen. To do this, use this .xinitrc:

sxhkd &
urxvt &
exec bspwm

If nothing shows up, that means you probably forgot to install urxvt. If it shows up but isn't centered or taking up most of your screen, that means BSPWM isn't starting properly. Make sure that you've chmod +x ~/.config/bspwm/bspwmrc.

Next, type pidof sxhkd in that terminal you spawned. It should return a process number. If it doesn't, that means sxhd isn't running. Try to be explicit and run sxhkd -c ~/.config/sxhkd/sxhkdrc. You could also try changing the Super key to something like Alt in your sxhkdrc and see if that helps. Another common problem is copying the text from the example files instead of physically copying the file over. Copying / pasting code usually leads to indentation issues which sxhkd can be sensitive to.

Clone this wiki locally
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.