Difference between revisions of "Xmonad/Frequently asked questions"

From HaskellWiki
Jump to navigation Jump to search
(Changed pointer follows focus example to use updatePointer.)
Line 471: Line 471:
Additionally, if you change and reinstall the XMonadContrib library,
Additionally, if you change and reinstall the XMonadContrib library,
changes to that package will not be noticed by ghc's recompilation
changes to that package will not be noticed by xmonad's recompilation
checker, so xmonad.hs won't be recompiled. To fix this:
checker, so xmonad.hs won't be recompiled. To fix this:

Revision as of 18:22, 19 March 2008



xmonad: frequently asked questions

What build dependencies does xmonad have?

The [http://hackage.haskell.org/cgi-bin/hackage-scripts/package/xmonad hackage page for xmonad] lists all dependencies, including:

  • Standard Haskell libraries (you might already have these installed):
  • Haskell X11 bindings:
  • C libraries:
    • libX
    • libXext
    • libXinerama

You likely have these already if you've built any programs for X.

Can I install without root permission?

Yes, the Haskell libraries that xmonad depends on can all by installed in the user package database. Simply append --user to the install phase:

   $ runhaskell Setup.hs install --user

The library will be registered in your ~/.ghc/ database.

How do I configure xmonad?

By editing the Config.hs file, a Haskell source file. You can use any Haskell you want in this module. To have your changes take effect, recompile xmonad, reinstall it, and either restart (mod-q) or exit X, and log back in.

Example configurations are available on the wiki.

Note that when reinstalling, cabal might prevent you from overwriting the running xmonad binary:

   Installing: /home/dons/lib/xmonad-0.2/ghc-6.6 & /home/dons/bin xmonad-0.2...
   copy /usr/obj/cabal/xmonad/xmonad to /home/dons/bin/xmonad
   *** Exception: /home/dons/bin/xmonad: copyFile: resource busy (Text file busy)

The solution is to remove the old xmonad binary before install.

   rm `which xmonad`

This is not required if you're using newer Cabal versions.

Does xmonad support a statusbar?


Arbitrary external programs may be used as a statusbar. See for example dzen or xmobar, an extensible status bar.

xmonad lets you use any application as a 'statusbar', as long as it is visible in a given 'gap' on the screen, and has the override-redirect property set to true. Many status bar/dock programs already set this property, for example, dzen. To set other applications, you can sometimes use normal X resources. For example, to use xclock, launch it with

   xclock -digital -xrm '*overrideRedirect: True' -geometry 1024x30+0+0

And set a gap of (30,0,0,0) in Config.hs. A similar trick can be done for xsystray.

You can see screenshots of statusbars on the screenshots page.

dzen status bars

In versions of xmonad > 0.4 the XMonadContrib library comes with a really easy function for getting a status bar working with dzen. To use it, simply have a ~/.xmonad/xmonad.hs containing:

   import XMonad
   import XMonad.Hooks.DynamicLog
   main = dzen xmonad

which will launch xmonad with dzen2 if found, set up with nice colours and workspace information. See Don's config example for more information.

How can I use xmonad with a display manager? (xdm, kdm, gdm)

The simplest way is to create or modify your ~/.xsession file to run xmonad. If you don't already have a .xsession, the minimal example looks like:


This requires that the xmonad executable (or a symlink to it) is in a directory in your $PATH. Alternatively, you can use the full path to xmonad. People using 'startx' can use these example xinitrc and run-xmonad scripts.

If you are using xdm, you're done. Login and enjoy xmonad.

If you're using kdm or gdm (KDE and GNOME's display mangers, respectively), you're almost done. When logging in, select the entry that says "xsession" or "default session" from the menu in order to use your ~/.xsession to start xmonad.

Alternatively, if you want a menu entry specifically for xmonad, create a file named "xmonad.desktop" in your /usr/share/xsessions (location varies by distribution) directory. For example:

   [Desktop Entry]
   Comment=This session starts xmonad

Replace the "Exec=..." line with the actual path to your xmonad executable, and you should be able to login by selecting "xmonad" as a session from the menu in gdm/kdm.

For instructions on using gdm to launch a full GNOME session with xmonad as the window manager read this.

Using a dock client

As of version 0.2, dock clients (such as gkrellm) aren't specially supported. They will be treated as a normal window. It is possible to use them by explicitly unmanaging the window, after moving it into a gap space. Dock clients are fully supported in version 0.4 and later.

X11 fails to find libX11 or libXinerama

Cabal has difficulty locating library directories on some platforms (such as the Mac or RHEL4). First, locate the directory that contains libX11.so (libX11.dylib on Mac OS X). Add the following line to the .cabal file for the package:

   extra-lib-dirs: /your/path/here/

For example, on a 64 bit machine you might need to add:

   extra-lib-dirs: /usr/X11R6/lib/lib64

You can also add the paths to your .buildinfo file, or set the LD_LIBRARY_PATH environment variable.

xmonad does not detect my multi-head setup

You may not have the Xinerama development files installed, install them, then watch the configure output for X11. Look for the following lines:

   checking X11/extensions/Xinerama.h usability... yes
   checking X11/extensions/Xinerama.h presence... yes
   checking for X11/extensions/Xinerama.h... yes

Be sure to clean and rebuild xmonad after building and installing X11.

The following ghci commands can help investigate your Xinerama setup.

   :m + Graphics.X11.Xinerama Graphics.X11.Xlib.Display
   openDisplay "" >>= getScreenInfo

compiledWithXinerama should give a Bool result, and getScreenInfo a list of screen Rectangles.

XMonad/Util/XSelection.hs:90:49: Couldn't match expected type `CChar' against inferred type `GHC.Word.Word8'

When building a darcs version of xmonad, you may also need to use a darcs version of the X11 library. That is available from:

   darcs get http://darcs.haskell.org/X11

if you get a type error in a build, the first suspect is that the libraries you depend on are out of date.

Missing X11 headers

Your build will fail if you've not installed the X11 C library headers at some point. ./configure for the Haskell X11 library will fail. To install the X11 C libs:

  • debian
   apt-get install libx11-dev
  • ubuntu

Rebinding the mod key

xmonad uses 'alt', actually mod1, as the default modifier. You may bind to other mod keys by editing your xmonad.hs modMask value, or by using xmodmap to rebind a key to mod1. The apple command key can be rebound to mod1 in this way. Use xmodmap to find what key your mod1 is bound to, as well.

You can rebind the Caps Lock key, to mod, if you wish. See this mailing list item.

If your new key binding doesn't appear to work, double check it doesn't clash with an existing binding.

An example, binding to the control key:

    import XMonad

    main = xmonad defaultConfig {
                modMask = controlMask

Saving layout

xmonad will remember your workspace layouts during dynamic restart (mod-q), but not when quitting X altogether. Note that this means if you add or remove layouts to the config.hs file, the changes won't be noticed during a hot-restart (the state from the previous session will be used).

You can reinitialise the xmonad state dynamically with mod-shift-space.

Startup programs

You may launch programs at startup in the usual X manner: by adding them to your .xsession or .Xinitrc. For example, the following .xsession file launches xpmroot to set the background image, xmodmap to rebind caps lock to ctrl. It then launches a status bar program with dzen, before finally launching xmonad:

   # .xsession
   xpmroot ~/.bg/407511721_eb8559457c_o.xpm &
   xrdb -merge .Xresources
   xmodmap -e "remove Lock = Caps_Lock"
   xmodmap -e "keysym Caps_Lock = Control_L"
   xmodmap -e "add Control = Control_L"
   status | dzen2 -ta r -fg '#a8a3f7' \
                        -bg '#3f3c6d' \
                        -fn '-*-terminus-medium-r-normal--16-*' \
                        -e "button1=exec:xterm" & 
   urxvt &

Losing text when resizing xterms

Being a dynamic tiling window manager, xmonad, like ion or dwm, makes heavy use of resizing. Clients such as xterm, might not take well to resizing and the window might require a refresh (Ctrl-L). To minimize this, several users recommend urxvt (rxvt-unicode), which handles resizing much better.

Showing fractions of lines in gvim

This is due to certain layouts doesn't care about so called size hints (resize increments) specifically the WM_NORMAL_HINTS(WM_SIZE_HINTS) (use xprop to see it). This, combined with certain programs, like gvim, which doesn't check if it gets enough size to render the last line and uses it anyway render this annoying behaviour. If this is a matter for you, you have the following options.

  1. Use a layout which uses these size hints like TilePrime or HintedTile
  2. Help factor out the features of TilePrime/HintedTile into other layouts, possibly into the xmonad core
  3. Workaround in .vimrc. These lines in your .vimrc lets you change the number of lines with F4/Shift-F4:
  map <F4> :let &lines=&lines-1^M
  map <S-F4> :let &lines=&lines+1^M

The ^M is created with Ctrl-V Ctrl-M.

Dynamic restart

The dynamic reconfigure and restart feature (mod-q) assumes that xmonad is in your $PATH environment. If it isn't, restarting will have no effect.

Some keys not working

If you've an unusual keyboard, X may not know precisely which keys you've bound xmonad actions to. An example is when you've use a French keyboard. You may need to set your own mod key, or use different key bindings in Config.hs. See this thread for advice on rebindings keys.

Firefox's annoying popup downloader

Some applications, notably Firefox 1 and 2, create tranisent windows not set with the transient property. (e.g. firefox's download manager). When these windows appear, they can take focus and be annoying. For the case of firefox, the 'Download Statusbar' extension is useful for disabling this annoying UI feature.

Copy and Paste on the Mac

When using X11 for Mac OS X, and you switch from the quartz WM to xmonad, you can lose copy/paste functionality between X windows and normal Mac apps. To fix this, and restore copy and paste, add

 quartz-wm --only-proxy &

in your .xinitrc above the line that runs xmonad. It will capture and syncronize copy/paste events in both environments. More specifically, it mirrors OS X copy actions into both PRIMARY and CLIPBOARD, but only CLIPBOARD into OS X paste.

Building xmonad 0.4.x with GHC 6.8

   "Can't find module Data.Set"

The ghc version 6.8 uses a smaller base library, with some modules xmonad depends on moved into the 'containers' package. Additionally, some language extension flags have changed.

To build xmonad 0.4 with ghc 6.8, you'll need to amend your .cabal file slightly, to something like:

   -build-depends:      base>=2.0, X11>=1.3.0, mtl>=1.0, unix>=1.0
   +build-depends:      base>=2.0, X11>=1.3.0, mtl>=1.0, unix>=1.0, containers
   -ghc-options:        -funbox-strict-fields -O2 -fasm -Wall -optl-Wl,-s
   +ghc-options:        -funbox-strict-fields -O2 -fasm -Wall -optl-Wl,-s -XPatternGuards -XExistentialQuantification -XMultiParamTypeClasses -XTypeSynonymInstances -fglasgow-exts

Alternatively, you can update to cabal 1.2, and use a version of xmonad more recent than 0.4, which will build with either ghc 6.6.x or ghc 6.8.

Setting the X cursor

By default xmonad doesn't set a particular X cursor, which usually means the default X cursor will be used by the system. To set your own custom cursor, use the xsetroot program, as follows, from your startup file:

   xsetroot -cursor_name left_ptr

For example, to get nice left-pointing arrow head cursor.

Note that some display managers, such as "slim", don't unset the changes they make to the cursor when the window manager starts. This can be worked around by setting the cursor, as above.


OpenOffice won't use (strangely) the GTK look, unless the following environment variable is set:


Use this if you don't like the default look of OpenOffice in xmonad.

Problems with Java applications

The Java gui toolkit has a hardcoded list of so-called "non-reparenting" window managers. xmonad is not on this list (nor are many of the newer window managers). Attempts to run Java applications may result in `grey blobs' where windows should be, as the Java gui code gets confused.

To work around this silly restriction, you can attempt to fake the window manager used by setting the environment variable:


This seems to fix:

 * cgoban3
 * Netbeans

It also fixes an issue with Java gui applications where menus are not "selectable". Clicking on the menu item opens the dropdown list of options but you can't select one.

 * Using the free blackdown java runtime also seems to work correctly.
 * Using JDK 7 also seems to work, Anthony Brown writes:

I just downloaded and early binary release of JDK 7 and it looks like the new Java version behaves properly ... I tried using some Gui apps that gave me the infamous grey windows with Java6 (or Java5 without setting AWT_TOOLKIT=MToolkit) and so far no problems occured.

I don't like borders around mplayer

You can also use the fullscreen layout, with the NoBorders layout modifier:

   import XMonad
   import XMonad.Layout.NoBorders
   main = xmonad $ defaultConfig
                       { layoutHook = smartBorders
                                           (layoutHook defaultConfig) }

which adds 'smartBorders' to the default tiling modes.

You can also remove borders with a key binding using Actions.NoBorders extension. There's drawback: you need manually remove border any time you launch mplayer.

Although this action should be able to be automated, unfortunately you cannot currently use manageHook for this purpose. That's because borders are drawn after runManageHook is executed (see Operations.hs for details).

Alternatively you can manually move the mplayer window 1 pixel to the left and one pixel up by importing XMonad.Actions.FloatKeys and adding a keybinding similar to ((modm, xK_b), withFocused (keysMoveWindow (-1,-1)). (I have not tested yet if this can be used in combination with the manageHook.)

Compiling xmonad on PowerPC and compiler is not interactive

If you have ghc installed and are trying to compile xmonad and your compiler complains about not being interactive, never fear. To compile Setup.hs simply type:

   ghc --make Setup.hs -o Setup

Now you can:

   ./Setup configure
   ./Setup build
   sudo ./Setup install

If during the build process ghc complains about the "impossible happening", and mentions that you should change something to "-fvia-C", just edit the *.cabal file replacing the line that sets the arguments for ghc, changing "-fasm" to "-fvia-C".

Cabal: Executable stanza starting with field 'flag small_base description'

A related error is:

   *** Exception: getSection got a line without a '{'.  Consider this a bug.

These are all symptoms of trying to compile xmonad with an old version of cabal.

The darcs version after xmonad 0.4 switched to requiring Cabal 1.2 to build xmonad. You must have Cabal 1.2 or newer to build xmonad older than 0.4. It will work fine with ghc 6.6.1, and you do not need to updated ghc. This will also not break older packages. Get cabal from Hackage:


Build and install as usual, then rebuild xmonad.

To build Cabal with ghc 6.6.1 you will also need the filepath library, which is also (of course) available from hackage:


Changes to the config file ignored

Both ghc and xmonad must be in your $PATH for reconfiguration to work.

When changing the config.hs (0.4) or xmonad.hs (0.5) and restarting with mod-q, xmonad will attempt to exec the xmonad binary. This means it must be in your $PATH environment variable, or the exec will fail silently and the old xmonad instance keeps running.

With xmonad 0.5 and later, mod-q will also call ghc on your ~/.xmonad/xmonad.hs file, and will continue with defaults if ghc is not found.

Additionally, if you change and reinstall the XMonadContrib library, changes to that package will not be noticed by xmonad's recompilation checker, so xmonad.hs won't be recompiled. To fix this:

   touch ~/.xmonad/xmonad.hs

after reinstalling the contrib library.

Help! xmonad just segfaulted

Due to this bug in GHC's recompilation checker,


if you updated a previously built xmonad, or XMonadContrib, when a depedent library has changed in the meantime, GHC will happilly go ahead and link your libraries together, into a broken binary. This will at best produce a linker error, and at worst, a version of xmonad that will segfault.

The rule is: when rebuilding, for exammple, XMonadContrib, always clean first if any library it depends on has changed.

   runhaskell Setup.lhs clean

You may also want to make sure your config gets rebuilt:

   touch ~/.xmonad/xmonad.hs

Floating a window or sending it to a specific workspace by default

See Xmonad/General_xmonad.hs_config_tipps for this.

unclutter and xmonad stops responding to keys

The number one cause for this is the 'unclutter' program, which can fool some clients into thinking they've lost the pointer, when in fact they have not. See the '-noevents' flag to unclutter.

An app seems to have frozen and xmonad stops responding to keys

There is an option in xorg.conf which enables the key combination Ctrl+Alt+Keypad-Divide to break active keyboard and mouse grabs. This may allow xmonad to continue normally in such cases. To enable this key combination, add the following line to your xorg.conf in the Section Server Flags then restart X:

Option "AllowDeactivateGrabs" "on"

Another workaround is to run 'xclock -display :0' via ssh or from a virtual terminal.

How do I uninstall xmonad?

If you have installed xmonad using your package manager, then just use it. The following applies if you have built xmonad from source code (either darcs or stable release). Let's assume you've installed xmonad to the $PREFIX (that is, gave --prefix=$PREFIX argument to Setup.lhs configure). If unsure, try your $HOME and /usr/local as $PREFIX.

 rm  -f $PREFIX/bin/xmonad
 rm -rf $HOME/.xmonad
 rm -rf $PREFIX/lib/xmonad-$VERSION
 # If you have installed XMonadContrib:
 rm -rf $PREFIX/lib/xmonad-contrib-$VERSION

If you have installed xmonad 0.5 or newer, also run

 ghc-pkg unregister xmonad
 # If you have installed XMonadContrib:
 ghc-pkg unregister xmonad-contrib

Do not forget to purge that evil source code!

I need to find the class / title / some other X property of my program!

If you are using something like XMonad.Actions.WindowGo, or a hook, or some other feature like that where XMonad needs to know detailed information about a window, you can generally find what you need by splitting your screen between the window and a terminal; in the terminal, run xprop, and then click on the window. xprop will then print out quite a bit of useful information about the window. Sample output might look like:

_MOTIF_DRAG_RECEIVER_INFO(_MOTIF_DRAG_RECEIVER_INFO) = 0x6c, 0x0, 0x5, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0
XdndAware(ATOM) = BITMAP
		window state: Normal
		icon window: 0x0
		Client accepts input or input focus: True
		Initial state is Normal State.
		window id # of group leader: 0xf600001
_NET_WM_USER_TIME_WINDOW(WINDOW): window id # 0xf600013
WM_CLIENT_LEADER(WINDOW): window id # 0xf600001
		program specified minimum size: 32 by 34
		program specified resize increment: 8 by 17
		program specified base size: 16 by 0
		window gravity: NorthWest
WM_CLASS(STRING) = "emacs", "Emacs"
WM_ICON_NAME(STRING) = "emacs@craft"
_NET_WM_ICON_NAME(UTF8_STRING) = 0x45, 0x4d, 0x41, 0x43, 0x53
_NET_WM_NAME(UTF8_STRING) = 0x45, 0x4d, 0x41, 0x43, 0x53

Note the last several lines contain useful information like the CLASS and hinting information.

I don't use statusbar, but I'd like to have layout displayed for some time when it changes

Let's assume you have import qualified XMonad.StackSet as S in xmonad.hs.

Add the following declaration somewhere in the toplevel:

curLayout :: X String
curLayout = gets windowset >>= return . description . S.layout . S.workspace . S.current

Then add the keybinding:

   , ((mod1Mask, xK_a     ), sendMessage NextLayout >> (curLayout >>= \d->spawn $"xmessage "++d))

You might want to change xmessage to the more friendly program, such as osd_cat, qt-dialog or dzen2.

Another option is to use Layout.ShowWName which has some user configurable options such as font, color and fade timings.

More flexible way is to use dynamicLogString from XMonad.Hooks.DynamicLog (was added after 0.6 release), which can also display current workspace, window name etc. and format them nicely.

How do I configure pointer-follows-focus?

In your config, import XMonad.Actions.Warp from Xmonad contrib and add this function:

pointerFollowsFocus :: Rational -> Rational -> X ()
pointerFollowsFocus h v = do
    dpy <- asks display
    root <- asks theRoot
    withFocused $ \w -> do
        wa <- io $ getWindowAttributes dpy w
        (sameRoot,_,w',_,_,_,_,_) <- io $ queryPointer dpy root
        if (sameRoot && w == w') then
            return ()
            io $ warpPointer dpy none w 0 0 0 0
                (fraction h (wa_width wa)) (fraction v (wa_height wa))
          where fraction x y = floor (x * fromIntegral y)

Then set the logHook in your config to “pointerFollowsFocus x y”. If you already have a logHook, append “ >> pointerFollowsFocus x y” to it. For example:

myLogHook = dynamicLogWithPP defaultPP { ppCurrent = xmobarColor "#60ff45" ""
                                       , ppVisible = xmobarColor "#fffff0" "" } >> pointerFollowsFocus 1 1

Alternatively, if you are using the darcs release, you can use the already defined XMonad.Actions.UpdatePointer:

myLogHook = dynamicLogWithPP .... >> updatePointer