This is a brief tutorial that will teach you how to create a basic xmonad configuration.

For more detailed instructions on extending xmonad with the xmonad-contrib library, see XMonad.Doc.Extending.

xmonad can be configured by creating and editing the Haskell file:

    ~/.xmonad/xmonad.hs

If this file does not exist, xmonad will simply use default settings; if it does exist, xmonad will use whatever settings you specify. Note that this file can contain arbitrary Haskell code, which means that you have quite a lot of flexibility in configuring xmonad.

NOTE for users of previous versions (< 0.5) of xmonad: this is a major change in the way xmonad is configured. Prior to version 0.5, configuring xmonad required editing an xmonad source file called Config.hs, recompiling xmonad, and then restarting. From version 0.5 onwards, however, all you have to do is edit xmonad.hs and restart with mod-q; xmonad does the recompiling itself. The format of the configuration file has also changed; it is now simpler and much shorter, only requiring you to list those settings which are different from the defaults.

Here is a basic example, which starts with the default xmonad configuration and overrides the border width, default terminal, and some colours:

    --
    -- An example, simple ~/.xmonad/xmonad.hs file.
    -- It overrides a few basic settings, reusing all the other defaults.
    --

    import XMonad

    main = xmonad $ defaultConfig
        { borderWidth        = 2
        , terminal           = "urxvt"
        , normalBorderColor  = "#cccccc"
        , focusedBorderColor = "#cd8b00" }

This will run 'xmonad', the window manager, with your settings passed as arguments.

Overriding default settings like this (using "record update syntax"), will yield the shortest config file, as you only have to describe values that differ from the defaults.

An alternative is to inline the entire default config file from xmonad, and edit values you wish to change. This is requires more work, but some users may find this easier. You can find the defaults in the XMonad.Config module of the core xmonad library.

However, note that (unlike previous versions of xmonad) you should not edit Config.hs itself.

To see what fields can be customized beyond the ones in the example above, the definition of the XMonad.Core.XConfig data structure can be found in XMonad.Core.

After changing your configuration, it is a good idea to check that it is syntactically and type correct. You can do this easily by loading your configuration file in the Haskell interpreter:

    $ ghci ~/.xmonad/xmonad.hs
    GHCi, version 6.8.1: http://www.haskell.org/ghc/  :? for help
    Loading package base ... linking ... done.
    Ok, modules loaded: Main.

    Prelude Main> :t main
    main :: IO ()

Ok, looks good.

Note, however, that if you skip this step and try restarting xmonad with errors in your xmonad.hs, it's not the end of the world; xmonad will simply display a window showing the errors and continue with the previous configuration settings.

To get xmonad to use your new settings, type mod-q. xmonad will attempt to compile this file, and run it. If everything goes well, xmonad will seamlessly restart itself with the new settings, keeping all your windows, layouts, etc. intact. (If you change anything related to your layouts, you may need to hit mod-shift-space after restarting to see the changes take effect.) If something goes wrong, the previous (default) settings will be used. Note this requires that GHC and xmonad are in your $PATH. If GHC isn't in your path, you can still compile xmonad.hs yourself:

    $ cd ~/.xmonad
    $ /path/to/ghc --make xmonad.hs
    $ ls
    xmonad    xmonad.hi xmonad.hs xmonad.o

When you hit mod-q, this newly compiled xmonad will be used.