bspwm

Related articles
Window manager
river
Comparison of tiling window managers
bspwm
is a tiling window manager that represents windows as the leaves of a full binary tree. bspwm supports multiple monitors and is configured and controlled through messages.
EWMH
is partially supported.
Installation
Install
bspwm
for the window manager itself and
sxhkd
for the X hotkey daemon.
Starting
Run
bspwm
using
xinit
.
Configuration
The example configuration is located in
/usr/share/doc/bspwm/examples/
.
Copy/install
bspwmrc
from there into
~/.config/bspwm/
and
sxhkdrc
into
~/.config/sxhkd/
.
The file
bspwmrc
needs to be executable since the default example is simply a shell script that in turn
configures bspwm via the
bspc
command.
$ install -Dm755 /usr/share/doc/bspwm/examples/bspwmrc ~/.config/bspwm/bspwmrc
$ install -Dm644 /usr/share/doc/bspwm/examples/sxhkdrc ~/.config/sxhkd/sxhkdrc
These two files are where you will be setting wm settings and keybindings, respectively.
See the
bspwm(1)
and
sxhkd(1)
manuals for detailed documentation.
Note for multi-monitor setups
The example bspwmrc configures ten desktops on one monitor like this:
bspc monitor -d I II III IV V VI VII VIII IX X
You will need to change this line and add one for each monitor, similar to this:
bspc monitor DVI-I-1 -d I II III IV
bspc monitor DVI-I-2 -d V VI VII
bspc monitor DP-1 -d VIII IX X
You can use
xrandr -q
or
bspc query -M --names
to find the monitor names.
Note that if monitor names contain special characters, the entire name needs to be escaped by a percentage sign
bspc monitor %DVI-I-1.5 -d I II III IV
to get identified correctly.
The total number of desktops were maintained at ten in the above example. To address each desktop, you should refer to the exact desktop names (defined by the
bspc monitor
command above) in your
sxhkdrc
like this:
# focus or send to the given desktop
alt + {_,shift + }{1-9,0}
    bspc {desktop --focus,node --to-desktop} '{I,II,III,IV,V,VI,VII,VIII,IX,X}'
Note
: In default config, sxhkd refers to desktops by number. But those change each time the monitor setup is changed.
Desktops in bspwm are activated by their index. Unless explicitly set, bspwm will automatically choose the display order, which determines the desktop index. If you encounter issues with desktops being on the wrong display, you should explicitly set the display order. similar to this:
bspc wm -O DVI-I-1 DVI-I-2 DP-1

bspc monitor DVI-I-1 -d I II III IV
bspc monitor DVI-I-2 -d V VI VII
bspc monitor DP-1 -d VIII IX X
If you want to automate your monitor-screens setup in case you periodically change monitor layouts, you need to use a conditional structure to check if a specific monitor is connected and configure it appropriately; you can place the following script in place of the standard
bspc monitor -d I II III IV V VI VII VIII IX X
command:
if [[ $(xrandr -q | grep "DP-1 connected") ]];
   then
      xrandr --output DP-1  --primary --mode 1920x1080 --pos 0x0  --rotate normal \
             --output DVI-I-1 --off \
             --output DVI-I-2 --off 
      bspc monitor DP-1 -d I II III IV V VI VII VIII IX
   fi
The previous script uses
xrandr
to set the virtual display configuration and bspc to assign the appropriate desktops layout.
Note that you should first set your preferred monitor layout with
arandr
, then export the xrandr configuration script and then copy the contents inside the script in place of the xrandr command.
Rules
bspwm can apply rules to windows based on the class name, which is the second string within the
WM_CLASS
property specified by
ICCM
. To determine the class name, you can:
Install
xorg-xprop
.
Run
xprop | grep WM_CLASS
.
Click on the window of interest to indicate it to
xprop
.
Record the
second
string from the output of the command.
There are two ways to configure window rules (as of
cd97a32
).
The first is by using the built in rule command, as shown in the example bspwmrc:
bspc rule -a Gimp desktop=^8 follow=on state=floating
bspc rule -a Chromium desktop=^2
bspc rule -a mplayer2 state=floating
bspc rule -a Kupfer.py focus=on
bspc rule -a Screenkey manage=off
The second option is to use an external rule command. This is more complex, but can allow you to craft more complex window rules.  See
these examples
for a sample rule command.
Panels
Using lemonbar
An example panel for
lemonbar
AUR
is provided in the examples folder on the GitHub page. You might also get some insights from the
lemonbar
wiki page. The panel will be executed by placing
panel &
in your bspwmrc. Check the
optdepends
in the
bspwm
package for dependencies that may be required.
To display system information on your status bar you can use various system calls.  This example will show you how to edit your
panel
to get the volume status on your BAR:
panel_volume()
{
        volStatus=$(amixer get Master | tail -n 1 | cut -d '[' -f 4 | sed 's/].*//g')
        volLevel=$(amixer get Master | tail -n 1 | cut -d '[' -f 2 | sed 's/%.*//g')
        # is alsa muted or not muted?
        if [ "$volStatus" == "on" ]
        then
                echo "%{Fyellowgreen} $volLevel %{F-}"
        else
                # If it is muted, make the font red
                echo "%{Findianred} $volLevel %{F-}"
        fi
}
Next, we will have to make sure it is called and redirected to
$PANEL_FIFO
:
while true; do
echo "S" "$(panel_volume) $(panel_clock)" > "$PANEL_FIFO"
        sleep 1s
done &
Using polybar
Polybar
can be used by adding
polybar
example
&
to your bspwmrc configuration file, where
example
is the name of the bar.
Scratchpad
Using pid
You can emulate a dropdown terminal.
First create a file called
/usr/local/bin/scratch
:
/usr/local/bin/scratch
#!/bin/bash

name="$1"
filename=/tmp/"$1"

bspc_write_nodeid() {
    while true
    do
        flag=false
        for id in $(bspc query -d focused -N -n .floating.sticky.hidden)
        do
            bspc query --node $id -T | grep -q $name && { echo $id > $filename; flag=true; break; }
        done
        [[ "$flag" == "true" ]] && break
        sleep 0.1s
    done
}

hide_all_except_current(){
    for id in $(bspc query -d focused -N -n .floating.sticky.!hidden)
    do
        bspc query --node $id -T | grep -qv $name && bspc node $id --flag hidden=on
    done
}

toggle_hidden() {
    [ -e "$filename" ] || exit 1
    hide_all_except_current
    id=$(<$filename)
    bspc node $id --flag hidden -f
}

create_terminal(){
    alacritty --class="$name","$name" -e $1 &
}

if ! ps -ef | grep -q "[c]lass=$name"
then
    bspc rule -a "$name" --one-shot state=floating sticky=on hidden=on
    case "$name" in
        "htop")
            create_terminal htop
            ;;
        "neomutt")
            create_terminal neomutt
            ;;
        "newsboat")
            create_terminal newsboat
            ;;
        "ranger")
            create_terminal ranger
            ;;
        "terminal")
            create_terminal $SHELL
            ;;
        *)
            exit 1
    esac
    dunstify "Scratch: starting $name"
    bspc_write_nodeid
    toggle_hidden
else
    toggle_hidden
fi
The
terminal
application is alacritty. Modify the following class specification and command execution in above script for other terminals.
alacritty --class="$name","$name" -e $1 &
For toggling the scratchpad, modify
~/.config/sxhkd/sxhkdrc
:
~/.config/sxhkd/sxhkdrc
# scratchpads
super + alt + {b,g,i,space,t}
    scratch {newsboat,neomutt,ranger,terminal,htop}
(source:
[1]
)
Scratchpad status using Polybar
Modify polybar config with:
modules-left = scratchpad

[module/scratchpad]
type = custom/script
interval = 0.1
exec = ~/.config/polybar/scratchpads_status.sh
And create a file
~/.config/polybar/scratchpads_status.sh
with:
~/.config/polybar/scratchpads_status.sh
#!/bin/bash

names="
htop H
neomutt M
newsboat N
ranger R
terminal T
"
status=""
cmd=$(ps -ef)

check_scratchpad() {
    grep -q "[c]lass=$1" <<< "$cmd"
}

IFS=$'\n'
for name in $names
do
    status+=$(check_scratchpad ${name% *} && echo ${name#* })
done

if [ -n "$status" ]
then
    echo "[$status]"
else
    echo ""
fi
(source:
[2]
)
Using class name
In this example we are going to use
termite
with a custom class name as our dropdown terminal. It does not have to be
termite
.
First create a file in your path with the following content and make it executable. In this example let us call it
scratchpad.sh
:
#!/usr/bin/bash

if [ -z $1 ]; then
	echo "Usage: $0 <name of hidden scratchpad window>"
	exit 1
fi

pids=$(xdotool search --class ${1})
for pid in $pids; do
	echo "Toggle $pid"
	bspc node $pid --flag hidden -f
done
Then add this to your bspwm config.
...
bspc rule -a dropdown sticky=on state=floating hidden=on
termite --class dropdown -e "zsh -i" &
...
To toggle the window a custom rule in
sxhkd
is necessary. Give as parameter the custom class name.
super + u
        scratchpad.sh dropdown
Other
For a scratch-pad which can use any window type without pre-defined rules, see:
[3]
For a more sophisticated scratchpad script that supports many terminals out of the box and has flags for doing things like optionally starting a tmuxinator/tmux session, turning any window into a scratchpad on the fly, and automatically resizing a scratchpad to fit the current monitor see
tdrop-git
AUR
.
Different monitor configurations for different machines
Since the
bspwmrc
is a shell script, it allows you to do things like these:
#!/bin/bash -

 if [[ $HOSTNAME == myhost ]]; then
     bspc monitor eDP1 -d I II III IV V VI VII VIII IX X
 elif [[ $HOSTNAME == otherhost ]]; then
     bspc wm -O VGA-0 VGA-1
     bspc monitor VGA-0 -d I II III IV V
     bspc monitor VGA-1 -d VI VII VIII IX X
 elif [[ $HOSTNAME == yetanotherhost ]]; then
     bspc wm -O DVI-I-2 DVI-I-3
     bspc monitor DVI-I-3 -d VI VII VIII IX X
     bspc monitor DVI-I-2 -d I II III IV V
 fi
Set up a desktop where all windows are floating
Here is how to setup the desktop 3 to have only floating windows. It can be useful for GIMP or other applications with multiple windows.
Put this script somewhere in your
$PATH
and call it from
.xinitrc
or similar (with a
&
at the end):
#!/bin/bash

 # change the desktop number here
 FLOATING_DESKTOP_ID=$(bspc query -D -d '^3')

 bspc subscribe node_add | while read -a msg ; do
    desk_id=${msg[2]}
    wid=${msg[4]}
    [ "$FLOATING_DESKTOP_ID" = "$desk_id" ] && bspc node "$wid" -t floating
 done
(
source
)
Keyboard
Bspwm does not handle any keyboard input and instead provides the
bspc
program as its interface.
For keyboard shortcuts you will have to setup a hotkey daemon like
sxhkd
(
sxhkd-git
AUR
for the development version).
Troubleshooting
Blank screen and keybindings do not work
Make sure
sxhkd
is installed.
Make sure you are starting
sxhkd
(in the background as it is blocking).
Make sure
~/.config/bspwm/bspwmrc
is executable.
The example configuration file for
sxhkd
specifies
urxvt
as the terminal emulator. If you do not have this installed, edit
~/.config/sxhkd/sxhkdrc
to point to the terminal emulator of your choosing.
Cursor themes do not apply to the desktop
See
Cursor themes#Change X shaped default cursor
Window box larger than the actual application
This can happen if you are using GTK3 applications and usually for dialog windows. Create or add the following:
~/.config/gtk-3.0/gtk.css
.window-frame, .window-frame:backdrop {
  box-shadow: 0 0 0 black;
  border-style: none;
  margin: 0;
  border-radius: 0;
}

.titlebar {
  border-radius: 0;
}
(source:
Bspwm forum thread
)
Problems with Java applications
If you have problems, like Java application Windows not resizing, or menus immediately closing after you click, see
Java#Gray window, applications not resizing with WM, menus immediately closing
.
Furthermore, some applications based on Java can not display any window content at all (e.g. Intellij IDEs like PyCharm, CLion, etc). A solution is to install
wmname
and add the following line:
~/.config/bspwm/bspwmrc
wmname LG3D
Additionally, these errors can often be solved by setting an
environment variable
for the JVM within e.g
bspwmrc
:
export _JAVA_AWT_WM_NONREPARENTING=1
Problems with keybindings using fish
If you use
fish
, you will find that you are unable to switch desktops. This is because bspc's use of the ^ character is incompatible with fish. You can fix this by explicitly telling sxhkd to use bash to execute commands:
$ set -U SXHKD_SHELL /usr/bin/bash
Alternatively, the ^ character may be escaped with a backslash in your sxhkdrc file.
Performance issues using fish
sxhkd
uses the shell set in the SHELL environment variable in order to execute commands.
fish
can have long initialization time due to large or improper configuration files, thus all sxhkd commands can take much longer to execute than with other shells. To fix this without changing your default SHELL you can make tell sxhkd explicitly to use bash, or another faster shell to execute commands (for example, sh):
$ set -U SXHKD_SHELL sh
Error messages "Could not grab key 43 with modfield 68" on start
Either you try to use the same key twice, or you start sxhkd twice. Check bspwmrc and
~/.profile
or
~/.bash_profile
for excessive commands starting sxhkd.
See also
Mailing List: bspwm
at
librelist.com.
#bspwm
- IRC channel at irc.libera.chat
#bspwm:matrix.org
- Matrix channel
https://bbs.archlinux.org/viewtopic.php?id=149444
- Arch BBS thread
https://github.com/baskerville/bspwm
- GitHub project
https://github.com/windelicato/dotfiles/wiki/bspwm-for-dummies
- earsplit's "bspwm for dummies"