bspwm

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 (or bspwm-git^AUR for development version) and sxhkd for the X hotkey daemon (or sxhkd-git^AUR for development version).

Starting

Run bspwm using xinit.

Configuration

The example configuration is located in /usr/share/doc/bspwm/examples/.

Copy/install from there into and into .

The file 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 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 or to find the monitor names.

The total number of desktops were maintained at ten in the above example. This is so that each desktop can still be addressed with in the sxhkdrc.

Rules

There are two ways to set window rules (as of cd97a32).

The first is by using the built in rule command, as shown in the example bspwmrc:

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.

If a particular window does not seem to be behaving according to your rules, check the class name of the program. This can be accomplished by running to make sure you are using the proper string, which requires the package.

Using lemonbar

An example panel for 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 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 :

Using polybar

Polybar can be used by adding to your bspwmrc configuration file, where is the name of the bar.

Using pid

You can emulate a dropdown terminal (like i3's scratchpad feature if you put a terminal in it) using bspwm's window flags. Append the following to the end of the bspwm configuration file (adapt to your own terminal emulator):

The flag ensures that the window is always present on the current desktop. And is:

The hotkey for toggling the scratchpad should be bound to:

id=$(cat /tmp/scratchid);\
bspc node $id --flag hidden;bspc node -f $id

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 :

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.

Other

For a scratch-pad which can use any window type without pre-defined rules, see:

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 .

Different monitor configurations for different machines

Since the 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 monitor VGA-0 -d I II III IV V
     bspc monitor VGA-1 -d VI VII VIII IX X
 elif [[ $HOSTNAME == yetanotherhost ]]; then
     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 and call it from 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 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:

(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 and add the following line in your :

wmname LG3D

Additionally, these errors can often be solved by setting an environment variable for the JVM within or a shell rc like , since BSPWM is a non reparenting WM.

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 or for excessive commands starting sxhkd.

gollark: My logic gates are crashing me somehow.

gollark: I accidentally broke a thingy.

gollark: No, in the middle.

gollark: Just don't use OC if you don't want it.

gollark: Why?