JWM Setup Guide

This is a quick guide to getting JWM installed and running. This guide is intended as a high-level guide to getting started with JWM. See the JWM configuration page for a comprehensive JWM configuration reference.


JWM is distributed in source form (available here), however, several distributions make JWM available as a binary package. Note that pre-compiled versions of JWM are often older than the newest version available here. To check the version of JWM, run "jwm -v" from a command line.

Assuming you are installing JWM from source, after downloading and expanding the file, run the "configure" script.


The configure script will configure JWM for your system. By default, it will enable all options provided it can find the appropriate libraries. You may need to install the "development headers" for some libraries to compile JWM. Simply re-run the configure script after installing any necessary packages. If you are missing a necessary library, the configure script will either fail (if the library is required) or tell you that some feature is disabled. JWM is installed to "/usr/local/bin" by default. The prefix where JWM is installed ("/usr/local" by default) can be changed using the configure script if desired using the "--prefix" option. Run "./configure --help" to display the available configuration options.

After successfully running configure, compile JWM by running "make". Once JWM is compiled, you can install it by running "make install" as root ("sudo make install").

Starting JWM

The preferred method for starting JWM varies depending on distribution and the display manager used to login. A common approach is to add the following line to either "$HOME/.xsession" or "$HOME/.Xinitrc":

exec /usr/local/bin/jwm

This will typically cause JWM to load immediately when X starts (if you are not using a login manager) or when the "user-defined" login is selected.


JWM is configured via an XML configuration file. By default, this file is located in "/usr/local/etc/system.jwmrc". To customize JWM, copy this file to "$HOME/.jwmrc" and then modify it using your favorite text editor. Although somewhat verbose, XML (which looks much like HTML) provides a convenient way to represent hierarchical configuration, such as menus. In addition, XML fairly easy to edit either by hand or programmatically.

Some distributions divide up the JWM configuration file into multiple files. Further, at least on distribution, Puppy Linux, provides tools to modify the JWM configuration though a graphical interface.

The rest of this document will describe how the various sections of the JWM configuration file work. Note that the order of the sections in the configuration file is not important. However, it is possible to override settings by specifying them multiple times, in which case the last setting will be used.

Within the JWM configuration file, the top-most "tag" must be JWM. A tag is the thing that starts with a "<" and ends with a ">". All tags must be "closed", this means that there is either an end tag (a tag starting with "</") following it or the tag is an "empty-element" tag, meaning it ends with a "/>". All configuration options are nested within the JWM tag.

Root Menu Configuration

JWM can provide one or more "root" menus. These menus provide a way for one to start programs. In the default configuration distributed with JWM, the root menu can be accessed by clicking on the desktop or by clicking the "JWM" button in the lower-left corner of the screen. Note that you may have a different configuration if you installed JWM from a binary distribution, such as through apt or yum.

The root menu in the default JWM configuration has several programs in it, but you will likely want to customize this menu by adding your own programs. A root menu is found in the configuration file inside the RootMenu tag. For example, it should look something like this:

<RootMenu onroot="12">
   <Program icon="terminal.png" label="Terminal">xterm</Program>
   <Menu icon="folder.png" label="Applications">
      <Program icon="calc.png" label="Calculator">xcalc</Program>
      <Program icon="web-browser.png" label="Midori">midori</Program>
      <Program icon="text-editor.png" label="XEdit">xedit</Program>
   <!-- more stuff here -->

Note that "more stuff here" is an XML comment, that is, JWM will ignore everything between "<!--" and "-->". Also note that I only included the first part of the menu here.

As shown, the root menu has one program (xterm) that shows up on the main part of the menu. The icon "attribute" sets an optional icon to show beside the menu item. The label attribute sets the label to use. If no label is provided, the name of the program is used directly. Finally, the text inside the "tag" (in this case, "xterm") provides the program to run when the menu is clicked.

Submenus can also be created. In the example above, there is one submenu, introduced by the Menu tag. Like programs, submenus can have an icon and label. Within the submenu, additional programs and submenus can be inserted.

The look of menus is controlled by the MenuStyle section. See the configuration page for details.


The default configuration includes a "tray" at the bottom of the screen. This tray has a button to display the root menu and a button show the desktop. It also contains a pager, which shows the virtual desktops, a task list, a clock, and a swallowed application (xload). It is possible to change the position and layout of this tray. In addition, it is possible to create additional trays or completely remove the tray. The section in the configuration file in the Tray tag defines the default tray. To add another tray, simply add another Tray tag and set the position as appropriate.

The look of the trays is controlled primarily by the TrayStyle section. The look of the pager can be refined using the PagerStyle tag.

Focus Model

JWM supports two focus models: click and sloppy. The default focus model is sloppy. Sloppy focus means that the window the mouse is over determines which window has focus. Click focus means that windows behave as in Windows or Mac OS X, where you must click the window to give it focus. To change the focus model, modify the FocusModel setting.


The number of desktops is controlled by the Desktops tag. The width attribute determines how many desktops are available horizontally and the height attribute determines how many desktops are available vertically.

In the Desktops section it is possible to specify a background for all desktops or each individually. Further, it is possible to set names for each desktop.


JWM allows one to customize the behavior of windows based upon their name or "class". This is controlled via "groups". You can have as many groups as you want. Each group is introduced by the Group tag.