Written by Pete Corey on Dec 15, 2014.

Recently I decided to elevate my Linux Mint 17.1 development environment from its plebeian out-of-the-box Cinnamon origins to its rightful place among the glorious #TilingWMMasterRace. I thought I’d document the process of installing and configuring bspwm to help others looking to do something similar.

bspwm for dummies

For the initial setup and configuration of bspwm, I recommend you read and follow Bill Indelicato’s excellent guide, bspwm for dummies. It’s worth noting that in addition to the packages he lists, you should have build-essential installed when trying to build bspwm on Linux Mint. The steps in his guide can be distilled down to:

sudo apt-get install vim dmenu rxvt-unicode git build-essential xcb libxcb-util0-dev libxcb-ewmh-dev libxcb-randr0-dev libxcb-icccm4-dev libxcb-keysyms1-dev libxcb-xinerama0-dev
git clone https://github.com/baskerville/bspwm.git
git clone https://github.com/baskerville/sxhkd.git
cd ~/bspwm && make && sudo make install
cd ~/sxhkd && make && sudo make install
mkdir -p ~/.config/bspwm ~/.config/sxhkd
cp ~/bspwm/examples/bspwmrc ~/.config/bspwm/bspwmrc
cp ~/bspwm/examples/sxhkdrc ~/.config/sxhkd/sxhkdrc
chmod +x ~/.config/bspwm/bspwmrc
echo -e “sxhkd -f 100 & \nexec bspwm” > ~/.xinitrc

sxhkdrc changes

I run my linux dev environment as a virtual machine, which means that using super as my bspwm control key can cause issues. Thankfully it’s incredibly simple to remap these sxhkd hotkeys in ~/.config/sxhkd/sxhkdrc:

sed -i ‘s/super/alt/g’ ~/.config/sxhkd/sxhkdrc
sed -i ‘s/alt + alt/alt + ctrl/g’ ~/.config/sxhkd/sxhkdrc


~/.Xdefaults is where you configure the look and feel of urxvt. I started with a template ~/.Xdefaults I found online, switched to use Ubuntu Mono and borrowed a nice color scheme I found in this helpful article. You can see what the final result on my github.

.xinitrc and .xsession

On a system without a graphical login manager, you could simply log into your system and run startx to run ~/.xinitrc and run bspwm. However, Linux Mint uses the MDM Display Manager, which means that X is already running when we log in and we need to take an extra step to get bspwm running. Thankfully, all we need to do is make a symbolic link to ~/.xinitrc called ~/.xsession. When MDM logs us in, it will execute ~/.xsession, which will effectively execute our ~/.xinitrc and run bspwm.

ln -s ~/.xinitrc ~/.xsession

After making this link, log out, select “Run Xclient script” session and log back in. You should be greeted with a black screen. Hit alt + enter to open a terminal.

sxhkd -f 100

After initially following the steps in bspwm for dummies, I noticed that doing mouse based window resizes was incredibly slow. After a little research, I found this reddit thread that suggested a fix of limiting the maximum frequency for motion events to 100. You can check out sxhkd.c on github to see how this works. Look at max_freq and motion_interval. When a max_freq is specified and a motion_interval is calculated (> 0), the motion_notify method will return early, preventing sxhkd from spamming bspwm with commands.

Final Thoughts

This should leave you with a minimal, functional and clean bspwm setup. There’s definitely much more that can be done from here, but the road you take is up to you. Check out all of my dotfiles on github.

My current bspwm setup