BSD-3-Clause licensed by Spencer Janssen, Don Stewart, Adam Vogt, David Roundy, Jason Creighton, Brent Yorgey, Peter Jones, Peter Simons, Andrea Rossato, Devin Mullins, Lukas Mai, Alec Berryman, Stefan O'Rear, Daniel Wagner, Peter J. Jones, Daniel Schoepe, Karsten Schoelzel, Neil Mitchell, Joachim Breitner, Peter De Wachter, Eric Mertens, Geoff Reedy, Michiel Derhaeg, Philipp Balzarek, Valery V. Vorotyntsev, Alex Tarkovsky, Fabian Beuke, Felix Hirn, Michael Sloan, Tomas Janousek, Vanessa McHale, Nicolas Pouillard, Aaron Denney, Austin Seipp, Benno Fünfstück, Brandon S Allbery, Chris Mears, Christian Thiemann, Clint Adams, Daniel Neri, David Lazar, Ferenc Wagner, Francesco Ariis, Gábor Lipták, Ivan N. Veselov, Ivan Tarasov, Javran Cheng, Jens Petersen, Joey Hess, Jonne Ransijn, Josh Holland, Khudyakov Alexey, Klaus Weidner, Michael G. Sloan, Mikkel Christiansen, Nicolas Dudebout, Ondřej Súkup, Paul Hebble, Shachaf Ben-Kiki, Siim Põder, Tim McIver, Trevor Elliott, Wouter Swierstra, Conrad Irwin, Tim Thelion
Maintained by [email protected]
This version can be pinned in stack with:xmonad-0.15@sha256:db671d78ecd66f39f23decf60974a3e078525ec9d2be68a3946b0cfb4d3954fa,5255

xmonad: A Tiling Window Manager

Build Status

xmonad is a tiling window manager for X. Windows are arranged automatically to tile the screen without gaps or overlap, maximising screen use. Window manager features are accessible from the keyboard: a mouse is optional. xmonad is written, configured and extensible in Haskell. Custom layout algorithms, key bindings and other extensions may be written by the user in config files. Layouts are applied dynamically, and different layouts may be used on each workspace. Xinerama is fully supported, allowing windows to be tiled on several physical screens.

Quick Start

For the full story, read on.


Building is quite straightforward, and requires a basic Haskell toolchain. On many systems xmonad is available as a binary package in your package system (e.g. on Debian or Gentoo). If at all possible, use this in preference to a source build, as the dependency resolution will be simpler.

We’ll now walk through the complete list of toolchain dependencies.

  • GHC: the Glasgow Haskell Compiler

    You first need a Haskell compiler. Your distribution’s package system will have binaries of GHC (the Glasgow Haskell Compiler), the compiler we use, so install that first. If your operating system’s package system doesn’t provide a binary version of GHC and the cabal-install tool, you can install both using the Haskell Platform.

    It shouldn’t be necessary to compile GHC from source – every common system has a pre-build binary version. However, if you want to build from source, the following links will be helpful:

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

    # for xmonad
    $ apt-get install libx11-dev libxinerama-dev libxext-dev libxrandr-dev libxss-dev
    # for xmonad-contrib
    $ apt-get install libxft-dev

Then build and install with:

$ cabal install

Running xmonad

If you built XMonad using cabal then add:

exec $HOME/.cabal/bin/xmonad

to the last line of your .xsession or .xinitrc file.


See the CONFIG document and the example configuration file.


There are many extensions to xmonad available in the XMonadContrib (xmc) library. Examples include an ion3-like tabbed layout, a prompt/program launcher, and various other useful modules. XMonadContrib is available at:

Other Useful Programs

A nicer xterm replacement, that supports resizing better:

For custom status bars:

For a program dispatch menu:


  • Spencer Janssen
  • Don Stewart
  • Jason Creighton


Change Log / Release Notes

unknown (unknown)

0.15 (September 30, 2018)

  • Reimplement sendMessage to deal properly with windowset changes made during handling.

  • Add new library functions windowBracket and modifyWindowSet to XMonad.Operations.

0.14.2 (August 21, 2018)

Bug Fixes

  • Add the sample configuration file xmonad.hs again to the release tarball. []

0.14.1 (August 20, 2018)

Breaking Changes

  • The cabal build no longer installs xmonad.hs, xmonad.1, and xmonad.1.html as data files. The location cabal picks for chose files isn’t useful as standard tools like man(1) won’t find them there. Instead, we rely on distributors to pick up the files from the source tarball during the build and to install them into proper locations where their users expect them. []

Bug Fixes

  • Add support for GHC 8.6.x by providing an instance for ‘MonadFail X’. A side effect of that change is that our code no longer compiles with GHC versions prior to 8.0.x. We could work around that, no doubt, but the resulting code would require CPP and Cabal flags and whatnot. It feels more reasonable to just require a moderately recent compiler instead of going through all that trouble.

  • xmonad no longer always recompile on startup. Now it only does so if the executable does not have the name that would be used for the compilation output. The purpose of recompiling and executing the results in this case is so that the xmonad executable in the package can be used with custom configurations.


  • Whenever xmonad recompiles, it now explains how it is attempting to recompile, by outputting logs to stderr. If you are using xmonad as a custom X session, then this will end up in a .xsession-errors file.

0.14 (July 30, 2018)

Bug Fixes

  • The state file that xmonad uses while restarting itself is now removed after it is processed. This fixes a bug that manifested in several different ways:

    • Names of old workspaces would be resurrected after a restart
    • Screen sizes would be wrong after changing monitor configuration (#90)
    • spawnOnce stopped working (xmonad/xmonad-contrib#155)
    • Focus did not follow when moving between workspaces (#87)
    • etc.
  • Recover old behavior (in 0.12) when focusFollowsMouse == True: the focus follows when the mouse enters another workspace but not moving into any window.

  • Compiles with GHC 8.4.1

  • Restored compatability with GHC version prior to 8.0.1 by removing the dependency on directory version 1.2.3.

0.13 (February 10, 2017)

Breaking Changes

  • When restarting xmonad, resume state is no longer passed to the next process via the command line. Instead, a temporary state file is created and xmonad’s state is serialized to that file.

    When upgrading to 0.13 from a previous version, the --resume command line option will automatically migrate to a state file.

    This fixes issue #12.


  • You can now control which directory xmonad uses for finding your configuration file and which one is used for storing the compiled version of your configuration. In order of preference:

    1. New environment variables. If you want to use these ensure you set the correct environment variable and also create the directory it references:

    2. The ~/.xmonad directory.

    3. XDG Base Directory Specification directories, if they exist:

      • XDG_CONFIG_HOME/xmonad
      • XDG_CACHE_HOME/xmonad
      • XDG_DATA_HOME/xmonad

    If none of these directories exist then one will be created using the following logic: If the relevant environment variable mentioned in step (1) above is set, the referent directory will be created and used. Otherwise ~/.xmonad will be created and used.

    This fixes a few issues, notably #7 and #56.

  • A custom build script can be used when xmonad is given the --recompile command line option. If an executable named build exists in the xmonad configuration directory it will be called instead of ghc. It takes one argument, the name of the executable binary it must produce.

    This fixes #8. (One of two possible custom build solutions. See the next entry for another solution.)

  • For users who build their xmonad configuration using tools such as cabal or stack, there is another option for executing xmonad.

    Instead of running the xmonad executable directly, arrange to have your login manager run your configuration binary instead. Then, in your binary, use the new launch command instead of xmonad.

    This will keep xmonad from using its configuration file checking/compiling code and directly start the window manager without execing any other binary.

    See the documentation for the launch function in XMonad.Main for more details.

    Fixes #8. (Second way to have a custom build environment for XMonad. See previous entry for another solution.)

0.12 (December 14, 2015)

  • Compiles with GHC 7.10.2, 7.8.4, and 7.6.3

  • Use of data-default allows using def where previously you had to write defaultConfig, defaultXPConfig, etc.

  • The setlocale package is now used instead of a binding shipped with xmonad proper allowing the use of Main.hs instead of Main.hsc

  • No longer encodes paths for spawnPID

  • The default manageHook no longer floats Gimp windows

  • Doesn’t crash when there are fewer workspaces than screens

  • Query is now an instance of Applicative

  • Various improvements to the example configuration file