xmonad logo


      building and installation


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 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

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 ghc6

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. If you are stuck with ghc 6.6 or 6.4 you can still run xmonad if you follow the older install directions here

X11 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: libXinerama libXext libX11


Recent versions of Cabal provide a tool, cabal-install, which automates the building of Haskell libraries, including gathering all dependencies. Your distribution may have a binary package for cabal-install, in which case you should use that. Otherwise the following steps will install it:

  • Download cabal install
  • Run the bootstrap script to install cabal-install with all of it's dependencies into your home directory.
        $ tar xzf cabal-install-0.6.2.tar.gz
        $ cd cabal-install-0.6.2/
        $ ./bootstrap.sh
  • Add ~/.cabal/bin to your $PATH
        $ echo "export PATH=$PATH:~/.cabal/bin" >> ~/.profile

Once you have a working cabal-install, you can then simply install any Haskell package you find on hackage.haskell.org, such as xmonad, xmonad-contrib or xmobar:

    $ cabal install xmonad


xmonad-contrib requires you to install libxft C headers, unless you install it without xft support:

    $ cabal install xmonad-contrib --flags="-use_xft"

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, #xmonad @ freenode.org, 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