Install Instructions

xmonad is a tiling window manager for X11. This document describes how to build and install xmonad. For its features and use, see the guided tour.

Use a pre-built binary

Your operating system distribution may have binary packages for xmonad already, or perhaps, many of their dependencies. If at all possible, use one of these pre-built packages. See the main page for distributions that distribute xmonad binaries.

Building from source

Building xmonad from source is simple. It requires a basic Haskell toolchain, only. We’ll now walk through the complete list of toolchain dependencies.

Install GHC

Note that, if you decide to install xmonad with stack (see further down), this step is not strictly necessary; stack will download the appropriate version of GHC by itself.

To build xmonad, you need the GHC Haskell compiler installed. All common operating systems provide prebuilt binaries of GHC in their package systems. For example, in Debian you would install GHC with:

    $ apt-get install ghc

If your operating system’s package system doesn’t provide a binary version of GHC, you can find pre-built binaries at the GHC home page. It shouldn’t be necessary to compile GHC from source – every common system has a pre-build binary version.

We recommend the latest stable release of GHC.

Install the Necessary C Libraries

Since you’re building an X application, you’ll need the C X11 library headers. On many platforms, these come pre-installed. For others, such as Debian, you can get them from your package manager:

    $ apt-get install libx11-dev

Typically you need the C libraries: libx11 libxext libxinerama libxrandr libxscreensaver.

Further, since xmonad is build with XFT support by default, you will also need the libxft C headers:

    $ apt-get install libxft-dev

Install XMonad

You are now ready to install xmonad with either stack or cabal. For these tool specific instructions, see the document in the core xmonad repo.

If things go wrong..

From time to time people have build problems. Almost always this is due to missing dependencies. Sometimes it is due to problems with the tool chain. The most common problems building xmonad are documented in the FAQ:

If this doesn’t help, try asking on the IRC channel, (join it via webchat), or on the mailing list.

Grab dmenu and dzen

Extra programs that make life with xmonad more exciting: dmenu and dzen. dmenu provides a simple popup menu for launching programs, dzen provides customisable status bars. You can get them here:

Starting xmonad

The simplest way to start xmonad is to modify your .xsession or .xinitrc and add the line:

exec xmonad

as the last line of your file, commenting out any previous window manager. Now, when you log in to X, xmonad will start, (by default in tall tiling mode, with no status bar), and you’ll be presented with an empty screen:

no windows open

From here, and assuming you can find the mod1 modifier key (usually ‘alt’), you can launch clients and access the rest of the window manager’s features. Refer to the manual page, or the cheatsheet