Rob Hunter

Dwm: A Tutorial for Beginners

This tutorial explains how to install, set up, and customize dwm. dwm is a window manager for X and the forerunner to xmonad and awesome, among others. As a tiling window manager, it automatically creates, adjusts, and moves windows for you so that you can focus on being productive. This means that it’s equally useful whether you’re using multiple large displays or a small netbook screen; it’s also stable and consumes little by way of system resources. dwm is hard to beat in terms of staying out of the way of the user and making the most of however much display real estate is available. Setting it up, however, is somewhat trickier – hence this tutorial.

i. background

A window manager (WM) is not a desktop environment. Examples of the latter include the GNOME and KDE environments for Linux, FreeBSD, etc.; these are fully-featured user interfaces that compete with the user interfaces of OS X, Windows, and so on. As such, they allow the user to control and access many of the features of the operating system through graphical control panels, dialogs, and other visually appealing (but computationally expensive) applications and widgets.

Standalone WMs, however, are more minimalistic. They don’t have as many of the graphical components or shininess of a desktop manager, but they make up for that with speed, simplicity, and security. Additionally, a tiling WM like dwm can automatically handle window arrangement and sizing, so that the user can focus on getting tasks done rather than fighting against the interface.

No WM better illustrates the core strengths of this approach than dwm. It’s fast, intuitive, and has a tiny system footprint. However, setting it up is a somewhat different procedure than simply installing a binary from a repository. (In some distros, you can download a precompiled binary package, but you won’t be able to customize it.) You have to build your own binary from source, but don’t worry – it’s easier than it sounds.

ii. building and installing dwm

First, open up a terminal, using an emulator like GNOME Terminal or sakura. Use apt-get to get the utilities that will be necessary to build and run dwm (this tutorial assumes you’re using Debian or Ubuntu; other distros such as Arch Linux have their own utilities for retrieving source packages, but the principle is the same). Issue the following command:

$ sudo apt-get install build-essential suckless-tools rxvt-unicode

Download the dwm source using apt-get’s source argument. Issue the following command from within your normal user home folder (note that you should not use superuser privileges – e.g., don’t use sudo):

$ apt-get source dwm

apt-get will download and unpack the source packages into a folder called ~/dwm-X.X (where X.X stands for the version number–6.0 is the release currently available at suckless.org, but most Debian and Debian-derived distros such as Ubuntu still ship 5.8.x, which is more stable.). Navigate to the new directory:

$ cd dwm*

Within the ~/dwm-X.X directory, there is a file, config.def.h, which contains the default settings for dwm. Rather than edit it directly, we will create our own custom header file, called config.h:

$ cp config.def.h config.h

Let’s take a look inside config.h. We’re not going to change anything yet, though. (Note: I’m using vim, but use whatever editor you’re comfortable with: nano, gedit, etc.)

 $ vim config.h

You should see a few dozen lines of code. config.h is a C header file which contains the defaults for various aspects of dwm’s behavior. For example, the line

static const char *tags[] = { "1", "2", "3", "4", "5", "6", "7", "8", "9" };

contains the names of the “tags” (analogous to workspaces) that dwm will use; the line

static const char *dmenucmd[] = { "dmenu_run", "-fn", font, "-nb", normbgcolor, "-nf", normfgcolor, "-sb", selbgcolor, "-sf", selfgcolor, NULL };

contains the settings for dmenu, a program launcher that is included in the suckless-tools package that we installed earlier.

We will change some settings later, but for now let’s build and install dwm to make sure that everything is as it should be. From within the directory that the dwm source files were unpacked to, e.g. dwm-6.0, issue the following command:

$ sudo make clean install

make will then output several lines telling you what it’s doing; the last four should read as follows:

CC dwm.c
CC -o dwm
installing executable file to /usr/local/bin
installing manual page to /usr/local/share/man/man1

These indicate that the C compiler has successfully created a binary executable file, called dwm, which has been installed to /usr/local/bin; a man (manual) file has also been created. Congratulations – you just built dwm from source!

So now we can log out and start dwm, right? Well, not yet.* In order to start dwm from the graphical menu that your display manager shows after you boot up your computer, we’ll need to create two new files. First, we’ll create a menu entry for the desktop manager, in the /usr/share/xsessions/ directory:

$ sudo vim /usr/share/xsessions/user-session.desktop

with the following contents:

user-session.desktop
1
2
3
4
5
6
[Desktop Entry]
Encoding=UTF-8
Name=WM from xsession script
Comment=Runs the window manager defined by xsession script
Exec=/etc/X11/Xsession
Type=Application

This will create a new menu entry in your display manager. Attempting to log in using this entry means that your DM will look for a user-created Xsession script, so let’s create one:

$ vim ~/.xsession

Here is a simple Xsession script to get you started:

.xsession
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
#!/bin/bash

xrdb -merge .Xresources

if [ -x /usr/bin/xfce4-power-manager ] ; then
   sleep 1
   xfce4-power-manager &
fi

while true; do
   xsetroot -name "$( date + "%F %I:%M %p" )"
   sleep 10
done &

exec dwm

This script imports any special settings you have specified in an .Xresources file (if you haven’t, you can comment out the second line of the .Xsession script), checks to see if the power manager is running (and if it isn’t, starts it), uses the xsetroot command to display and refresh the date and time every ten seconds, and then finally starts dwm. (Note that I’m using xfce4-power-manager, but you should be able to use gnome-power-manager, etc., as well.)

We’re now ready to log out of our desktop environment (e.g., GNOME), and log into dwm! (Remember to select the “WM from xsession script” menu entry.) You’ll see a blue screen with a gray bar on top. The gray bar is your status bar, indicating the tags (workspaces) and active windows; on the right you’ll see the date and time, thanks to the settings in your Xsession script. Use the tutorial at suckless.org to get comfortable with launching programs using dmenu, manipulating the window layout, switching between tags, etc.

iii. customizing dwm

Now we can start making further customizations to dwm. Open up the config.h file in your dwm-X.X directory, e.g. ~/dwm-6.0/config.h, and start changing the default values to better suit your needs. Here is an example config.h with a few changes:

File /Users/klapaucius/Dropbox/Projects/rhunter/source/downloads/code/config.h could not be found

Most of the settings are similar to those of the default configuration, with some changes to the names of the workspaces, a different terminal emulator (I prefer urxvt or sakura, but gnome-terminal is fine too), and a change to the way that dwm handles the size of terminal windows, so that no gaps appear at the edge of the screen. It also changes the MODKEY setting from Mod1 (“Alt” on most keyboards) to Mod4 (usually, the “Windows” key), in order to avoid conflicts with keyboard commands in other programs. For more guidance on how to customize dwm, check out the guides at suckless.org. Some additional changes that I often make include changing the border width to 0 and prioritizing the monocle display over tile; this creates a more elegant setup on a netbook, for example. For even more changes, you can try your hand at patching (which is a bit more advanced and outside the scope of this tutorial).

Congratulations! You’ve finished setting up a customized, built-from-source installation of dwm! Comments are open if you have questions or suggestions.

*dwm is a WM for X – meaning that it would be launched by starting X from TTY with the startx command and a properly configured .xinitrc file. If you know how to do that, though, you likely do not need this guide; and anyway, it’s far more common now for Linux distros to automatically configure at least one desktop manager such as gdm or kdm. (This guide assumes you’re using gdm or gdm3, but there should be no real difference if you’re using kdm).

(A special thank-you to the fine folks at suckless.org for their documentation, and, of course, for creating and maintaining dwm!)