See also [[#Multi_head_or_xinerama_troubles|xinerama troubles]] if your multi-head setup doesn't behave as described below.

See also [[#Multi_head_or_xinerama_troubles|xinerama troubles]] if your multi-head setup doesn't behave as described below.

−

XMonad's defaults may seem confusing and chaotic until explained and illustrated. First we'll look at how things work by default, then at the most common keybinding customizations people make.

+

XMonad's defaults with multiple monitors may seem confusing and chaotic until explained and illustrated. First we'll look at how things work by default, then at common workspace keybinding customizations.

To ''focus'' visible workspaces rather than ''swapping'' their screens modify your keybindings as shown in [[#Replacing greedyView with view|the next section below]]. See the section about [[#Other multi head customizations|other customizations]] to give each monitor its own set of workspaces.

To ''focus'' visible workspaces rather than ''swapping'' their screens modify your keybindings as shown in [[#Replacing greedyView with view|the next section below]]. See the section about [[#Other multi head customizations|other customizations]] to give each monitor its own set of workspaces.

The xmonad man page nicely summarizes how multi-head works by default:

The xmonad man page nicely summarizes how multi-head works by default:

−

<blockquote>When running with multiple monitors (Xinerama, TwinView, xrandr), each screen has exactly 1 workspace visible. Pressing '''<code>mod-{w,e,r}</code>''' switches the focus between screens, while pressing '''<code>shift-mod-{w,e,r}</code>''' moves the current window to that screen. When xmonad starts, workspace 1 is on screen 1, workspace 2 is on screen 2, etc. When switching workspaces to one that is already visible, the current and visible workspaces are swapped.</blockquote>

+

:When running with multiple monitors (Xinerama, TwinView, xrandr), each screen has exactly one workspace visible. Pressing '''<code>mod-{w,e,r}</code>''' switches the focus between screens, while pressing '''<code>shift-mod-{w,e,r}</code>''' moves the current window to that screen. When xmonad starts, workspace 1 is on screen 1, workspace 2 is on screen 2, etc. When switching workspaces to one that is already visible, the current and visible workspaces are swapped.

'''visible workspaces swap''' (default keybindings): When you have multiple workspaces visible and mod-n to a different ''visible'' workspace, your current one swaps with the other one. We'll see how to change that below, if you don't like the swapping -- simply change 'greedyView' to 'view' in your workspace key bindings. To illustrate with two monitors, using the convention "[1*] [3 ]" to mean workspaces 1 and 3 are visible with left monitor the currently active one:

'''visible workspaces swap''' (default keybindings): When you have multiple workspaces visible and mod-n to a different ''visible'' workspace, your current one swaps with the other one. We'll see how to change that below, if you don't like the swapping -- simply change 'greedyView' to 'view' in your workspace key bindings. To illustrate with two monitors, using the convention "[1*] [3 ]" to mean workspaces 1 and 3 are visible with left monitor the currently active one:

'''my focus moves instead''' (custom workspace switching bindings): By replacing the 'greedyView' function with 'view' in the workspace switching bindings you can have your focus shift to the monitor displaying the given workspace, instead of having that workspace 'brought to you.' (See the next section for examples of how to do this.) For example:

'''my focus moves instead''' (custom workspace switching bindings): By replacing the 'greedyView' function with 'view' in the workspace switching bindings you can have your focus shift to the monitor displaying the given workspace, instead of having that workspace 'brought to you.' (See the next section for examples of how to do this.) For example:

−

<code>

+

<pre>

-- 'view' workspace switching

-- 'view' workspace switching

Line 223:

Line 223:

[1 ] [4*] -- mod-w --> [1*] [4 ] -- mod-4 --> [1 ] [4*]

[1 ] [4*] -- mod-w --> [1*] [4 ] -- mod-4 --> [1 ] [4*]

−

</code>

+

</pre>

−

Users of the <hask>view</hask> action may also want to add key bindings such

+

<hask>view</hask> users may also want to add key bindings such as shiftNextScreen and swapNextScreen from the xmonad-contrib extension [http://xmonad.org/xmonad-docs/xmonad-contrib/XMonad-Actions-CycleWS.html XMonad.Actions.CycleWS].

(<hask>doF W.swapDown</hask> is the same as using <hask>insertPosition Lower ____</hask>.) To avoid problems with floating window dialogs it's highly recommended to also add an <hask>isDialog</hask> hook as shown below. Adding <hask>doF W.swapDown</hask> to your manageHook will result in new windows being inserted below the focus; for floating windows this means behind the current window. A minimal config would look like this:

<haskell>

<haskell>

import XMonad

import XMonad

import qualified XMonad.StackSet as W

import qualified XMonad.StackSet as W

+

import XMonad.Hooks.ManageHelpers

+

main = xmonad defaultConfig

main = xmonad defaultConfig

−

{ manageHook = manageHook defaultConfig <+> doF W.swapDown

+

{ manageHook = isDialog --> doF W.shiftMaster <+> doF W.swapDown

--

--

-- To prevent unwanted swaps on other workspaces when using

-- To prevent unwanted swaps on other workspaces when using

Line 484:

Line 490:

</haskell>

</haskell>

−

'''Warning:''' <code>doF W.swapDown</code> without restrictions will result in new floating windows popping up ''behind'' focused floating windows, and undesirable focus changes when starting and quickly destroying a window. Better would be to only match specific windows to swapDown or use composeOne as shown above.

+

'''Warning:''' <code>doF W.swapDown</code> without restrictions will result in new floating windows popping up ''behind'' focused floating windows, and undesirable focus changes when starting and quickly destroying a window. It is better to only match specific windows to swapDown or use composeOne as shown above.

Since approximately November 2010, the stock configuration no longer causes flash windows to immediately disappear. However, tiling flash's windows is often not what you want. Try some or all of the following hooks.

+

For browser plugins and most apps, including mplayer floated by manage hook (as in the default manageHook) the following setup allows normal toggling of fullscreen. A few mplayer versions are configured to use a different fullscreen method, but they can be made to work with the isFullscreen hook by adding a line <code>fstype=none</code> to ~/.mplayer/config, or using the <code>-fstype=none</code> flag from the command line. See also the end of the faq regarding using handleEventHook instead.

For browser plugins and most apps, including mplayer floated by manage hook (as in the default manageHook) the following setup allows normal toggling of fullscreen. A few mplayer versions are configured to use a different fullscreen method, but they can be made to work with the isFullscreen hook by adding a line <code>fstype=none</code> to ~/.mplayer/config, or using the <code>-fstype=none</code> flag from the command line. See also the end of the faq regarding using handleEventHook instead.

Line 640:

Line 648:

===I need to find the class title or some other X property of my program===

===I need to find the class title or some other X property of my program===

−

If you are using something like XMonad.Actions.WindowGo, or a hook, or some

+

When using XMonad.Layout.IM, ManageHooks, XMonad.Actions.WindowGo, or several other modules you need to specify detailed information about a window's properties.

−

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 <tt>xprop | grep CLASS</tt> or the like, and then click on the window. xprop will then print out quite a bit of useful information about the window.

+

+

See below for a script to nicely format output from the <tt>xprop</tt> program discussed in detail in this FAQ.

+

+

Otherwise, you can generally find what you need by splitting your screen between the window and a terminal; in the terminal, run <tt>xprop WM_CLASS</tt> or the like, and then click on the window. xprop will print out quite a bit of useful information about the window.

* '''resource''' (also known as '''appName''') is the first element in WM_CLASS(STRING)

* '''resource''' (also known as '''appName''') is the first element in WM_CLASS(STRING)

* '''className''' is the second element in WM_CLASS(STRING)

* '''className''' is the second element in WM_CLASS(STRING)

Line 698:

Line 709:

==== A handy script to print out window information ====

==== A handy script to print out window information ====

−

This script will print window information (if available) in formats usable within <tt>xmonad.hs</tt>.

+

This script will print window information (if available) in formats usable within <tt>xmonad.hs</tt>. It is also included in the $src/XMonadContrib/scripts directory with

Check to see whether there is a Rectangle corresponding to each of your screens. If there is not, and the compiledWithXinerama diagnostic returns True, there may be a problem with your X server configuration.

+

Check to see whether there is a Rectangle corresponding to each of your screens. If there is not, and the compiledWithXinerama diagnostic returns True, there may be a problem with your X server configuration. The most common one is having your monitors set to ''clone'' one another. See 'man xrandr', or, if using the proprietary nvidia drivers, 'nvidia-settings' to see how reconfigure them.

+

+

Also, there can be two versions of the X11 haskell library installed, one of them built with Xinerama, and other without it. If XMonad is using the one built with Xinerama, and the output of the commands use the version without it, all these tests will work but these problems will persist. Check the output of ghc-pkg to see if there is more than one version of X11 installed.

====Missing X11 headers====

====Missing X11 headers====

Line 975:

Line 987:

render this annoying behaviour. Aside from patching the offending program, you can:

render this annoying behaviour. Aside from patching the offending program, you can:

−

# Use a layout which uses these size hints like Hinted Grid, or HintedTile

+

<ol>

−

# Use the [http://xmonad.org/xmonad-docs/xmonad-contrib/XMonad-Layout-LayoutHints.html layoutHints] modifier on any layout

+

<li>Use a layout which uses these size hints like Hinted Grid, or HintedTile</li>

−

# Workaround in .vimrc. These lines in your .vimrc lets you change the number of lines with F4/Shift-F4:

+

<li>Use the [http://xmonad.org/xmonad-docs/xmonad-contrib/XMonad-Layout-LayoutHints.html layoutHints] modifier on any layout</li>

+

<li>Workaround in .vimrc. These lines in your .vimrc lets you change the number of lines with F4/Shift-F4:</li>

ontoillogical says: Most people turn off menus and toolbars and adjust fonts in their .emacs. That's what breaks emacs' display in tiling WMs. To get emacs to look correctly, move all of the stuff that affects how emacs draws a frame to .Xdefaults/.Xresources

ontoillogical says: Most people turn off menus and toolbars and adjust fonts in their .emacs. That's what breaks emacs' display in tiling WMs. To get emacs to look correctly, move all of the stuff that affects how emacs draws a frame to .Xdefaults/.Xresources

Line 1,044:

Line 1,059:

=== Problems with Java applications, Applet java console ===

=== Problems with Java applications, Applet java console ===

+

+

There are two classes of problems: blank, grey windows and windows that can't be focused for keyboard input. The latter should be fixed in the newest xmonad, so follow the instructions on the website for getting a copy of the darcs repository and build it. Remember to rebuild xmonad-contrib (preferably also from darcs) afterwards! The remainder of this section covers the blank, grey window problems.

The Java gui toolkit has a hardcoded list of so-called "non-reparenting"

The Java gui toolkit has a hardcoded list of so-called "non-reparenting"

Line 1,049:

Line 1,066:

managers). Attempts to run Java applications may result in `grey blobs' where

managers). Attempts to run Java applications may result in `grey blobs' where

windows should be, as the Java gui code gets confused.

windows should be, as the Java gui code gets confused.

−

−

The following workarounds also fix 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, or the menu disappears when you are looking at it.)

−

−

If you are still having focus problems, even after implementing the workarounds, see also

−

[http://code.google.com/p/xmonad/issues/detail?id=177 issue 177].

====Preferred Method====

====Preferred Method====

Line 1,063:

Line 1,075:

====Using SetWMName====

====Using SetWMName====

−

Otherwise, you can lie to Java about what window manager you are using, by having the [http://xmonad.org/xmonad-docs/xmonad-contrib/XMonad-Hooks-SetWMName.html SetWMName] extension convince Java that xmonad is '''"LG3D"'''. Normally you would use this in

+

Otherwise, you can lie to Java about what window manager you are using, by having the [http://xmonad.org/xmonad-docs/xmonad-contrib/XMonad-Hooks-SetWMName.html SetWMName] extension convince Java that xmonad is '''"LG3D"'''. (**WARNING: This *breaks* recent versions of gtk+3!** Use the Preferred Method above instead, if necessary upgrading your Java to a version which supports it.) Normally you would use this in the startup hook, like this:

−

startup hook, like this:

+

<haskell>

<haskell>

Line 1,317:

Line 1,328:

http://hackage.haskell.org/cgi-bin/hackage-scripts/package/filepath

http://hackage.haskell.org/cgi-bin/hackage-scripts/package/filepath

+

+

=== configure: error: cannot run C compiled programs. ===

+

+

This typically means that you have /tmp mounted with noexec. To use another directory, make an alias that temporarily changes $TMPDIR, like

1 When I start xmonad, nothing happens.

Don't panic, this is expected behavior. XMonad is a minimal window manager, meaning it doesn't set a background, start a status bar, display a splash screen or play a soothing sound effect when it starts up. Once xmonad has started, the only thing it does is listen for your first command. Try pressing mod-shift-enter (that is Alt, Shift, and Enter pressed at the same time) to bring up an xterm. Once the xterm appears, use it to read xmonad's man page or point a web browser at http://xmonad.org/tour.html. If no xterm appears, see if any other advice on this page applies.

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

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

xmonad

This requires that the ghc and the xmonad executable (or a symlink to them) are in a
directory in the display manager $PATH environment. Alternatively, you can use the full path to xmonad and set ghc's path systemwide. If you do this, you'll also have to change the mod-q binding to use /path/to/xmonad and restart X to have xmonad use the new mod-q (first time only) since the mod-q binding calls xmonad to recompile itself. (See mod-q doesn't work section below.)

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:

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.

2.4 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".

2.5 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

2.6 not found errors or changes to xmonad.hs won't take effect

Ensure that ghc, and the xmonad executable are both in the environment PATH from which you start X. Alternatively symlink them to locations already in the PATH. ghc-pkg list should show ghc, xmonad, X11, etc. without brackets, e.g. {xmonad} is bad. ghc-pkg check will tell you if you have inconsistent dependencies or other registration problems.

The mod-q action calls the xmonad binary to recompile itself, so if your display manager is starting it with /path/to/xmonad you'll also have to edit your xmonad.hs mod-q binding to use the full path and restart X (or in newer versions use 'xmonad --restart') to restart xmonad with the new mod-q full path binding.

2.7 Configuring xmonad requires GHC, which is 200MB!

Yes. You can use xmonad-light, which allows some of the basic configurations, but if you really want to get the best xmonad experience, you need GHC.

3 Configuration

3.1 How do I configure xmonad?

By creating and editing the ~/.xmonad/xmonad.hs file, a Haskell source file.

You can use any Haskell you want in this module. The xmonad-contrib package contains many extension modules to make customizing xmonad easier. To have your changes take effect, save the xmonad.hs and either restart (mod-q) or exit X and log back in.

For extensive information on configuring, see the links at the top of this page, and the configuration tips page.

3.2 Rebinding the mod key (Alt conflicts with other apps; I want the ___ 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.

3.3 Multi head and workspaces (desktops)

See also xinerama troubles if your multi-head setup doesn't behave as described below.

XMonad's defaults with multiple monitors may seem confusing and chaotic until explained and illustrated. First we'll look at how things work by default, then at common workspace keybinding customizations.

To focus visible workspaces rather than swapping their screens modify your keybindings as shown in the next section below. See the section about other customizations to give each monitor its own set of workspaces.

The xmonad man page nicely summarizes how multi-head works by default:

When running with multiple monitors (Xinerama, TwinView, xrandr), each screen has exactly one workspace visible. Pressing mod-{w,e,r} switches the focus between screens, while pressing shift-mod-{w,e,r} moves the current window to that screen. When xmonad starts, workspace 1 is on screen 1, workspace 2 is on screen 2, etc. When switching workspaces to one that is already visible, the current and visible workspaces are swapped.

visible workspaces swap (default keybindings): When you have multiple workspaces visible and mod-n to a different visible workspace, your current one swaps with the other one. We'll see how to change that below, if you don't like the swapping -- simply change 'greedyView' to 'view' in your workspace key bindings. To illustrate with two monitors, using the convention "[1*] [3 ]" to mean workspaces 1 and 3 are visible with left monitor the currently active one:

my focus moves instead (custom workspace switching bindings): By replacing the 'greedyView' function with 'view' in the workspace switching bindings you can have your focus shift to the monitor displaying the given workspace, instead of having that workspace 'brought to you.' (See the next section for examples of how to do this.) For example:

3.3.2 Other multi head customizations

By default, XMonad doesn't link all your monitor screens into one workspace like Gnome and friends, neither does it use a model like dwm's where each monitor has its own set of workspaces. To set up dwm style workspaces for each screen, see (0.9 or greater) Layout.IndependentScreens

3.3.3 Screens are in wrong order

Sometimes drivers don't do what you want, and your screens left to right are something
weird like 1 0 2, so your mod-{w,e,r} bindings are messed up. Your driver may provide a utility to set screen order, but if not, or if you just don't want to mess with
it, here's how to rebind the screen switching bindings:

Note that if you choose not to use myKeys for the key lists appended together with

3.6 Does xmonad support a statusbar?

Yes. The Hooks.DynamicLog and Hooks.ManageDocks modules are your friends for this purpose.

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

If, like xclock, your app doesn't set wm strut properties, so that ManageDocks and avoidStruts automatically leaves a gap, you can do it manually. Import the Layout.Gaps module and, set a gap of, e.g. (30,0,0,0), in xmonad.hs. A similar trick can be done for xsystray.

There is an excellent command-line option and in-text command reference for the SVN version of dzen2 here

3.6.2 gkrellm or other monitors that aren't bars

Gkrellm does not behave like a dock by default. However, there is an option in .gkrellm2/user_config which says dock = 0. If you set it to 1 xmonad will recognize gkrellm as a dock.

Unfortunately gkrellm usually won't hide under other windows regardless of any combination of above and below options in said config file. Opening and closing the gkrellm config usually resolves this (right click the top of gkrellm and select Configure.. from the menu).

In xmonad-darcs (will release as xmonad-0.9) the Layout.Monitor module may be helpful.

3.6.3 Make space for a panel dock or tray

ManageDocks makes it possible for Xmonad to work with panels in the way they expect, automatically leaving the appropriate amount of room for them at the edges of the screen. ManageDocks has been enabled in the example configuration above. By itself, configuration looks like this:

3.7 Make new windows appear 'below' rather than 'above' the current window

See also the Hooks.InsertPosition module for placement hooks other than W.SwapDown to use in stack order manageHooks.

3.7.1 Force a few tiled windows down

If you only need to position a few windows below rather than above, and can specify window properties that will avoid matching floating dialogs, etc. then adding a few swapDown manageHooks (or similar from Hooks.InsertPosition referenced above) should do the trick.

3.7.2 Limit windows forced down by using composeOne

To position as many windows as possible below the focus while avoiding problems with z-order while using multiple floating windows, use Hooks.ManageHelpers composeOne and (-?>) in place of composeAll and (-->) to specify hooks that only fire if earlier ones have not matched. You can use this to add swapDown last in your composeOne list, so that it's applied only to windows that haven't earlier been floated or identified as transient or dialog windows.

Warning:doF W.swapDown without restrictions will result in new floating windows popping up behind focused floating windows, and undesirable focus changes when starting and quickly destroying a window. It is better to only match specific windows to swapDown or use composeOne as shown above.

Note that this is not a good solution for people who use floating windows, since many operations on floats put the floating window into the master position. Some transient windows will be swappedDown to appear below the floating parent unless the user keeps a tiled window in master and floating windows lower in the stack at all times. As with swapDown it's best to use it only on specific windows or at the end of a composeOne list if you use floating windows very often.

3.8 Prevent new windows from stealing focus

For an avoidMaster that keeps the focus with the master instead of focusing

the newly created window replace

W.Stack t [](r:rs)-> W.Stack t [r] rs

with

W.Stack t [](r:rs)-> W.Stack r [](t:rs)

in the above avoidMaster code.

3.9 Firefox annoyances

3.9.1 Stop Firefox from taking focus while using EwmhDesktops

If one uses EWM Hints support, firefox is enabled to choose when you view its workspace, i.e. if you open links from emails or irc or whatever. If you find it annoying... In about:config (vimperator :preferences!) set browser.tabs.loadDivertedInBackground to True to be able to load urls while working elsewhere, then browse them all later when you choose to shift to the firefox workspace. Also ubuntu users may need to disable the ubufox extension.

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

3.10 Watch fullscreen flash video

Since approximately November 2010, the stock configuration no longer causes flash windows to immediately disappear. However, tiling flash's windows is often not what you want. Try some or all of the following hooks.

For browser plugins and most apps, including mplayer floated by manage hook (as in the default manageHook) the following setup allows normal toggling of fullscreen. A few mplayer versions are configured to use a different fullscreen method, but they can be made to work with the isFullscreen hook by adding a line fstype=none to ~/.mplayer/config, or using the -fstype=none flag from the command line. See also the end of the faq regarding using handleEventHook instead.

Add one of the following manageHooks, and modify layoutHook with smartBorders:

If you have multi-head and the focusDown hook doesn't work for you, in darcs xmonad/xmonad-contrib (greater than 0.9.1) XMonad.Hooks.EwmhDesktops has a fullscreenEventHook that is also worth a try. Add it to any existing handleEventHook with <+>, or simply use it as your handleEventHook if you don't already have one. This also is useful for people who prefer tiling mplayer when not fullscreened, or use totem, vlc, or other players that require something like fullscreenEventHook to work at all.

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

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

You may also launch applications from your xmonad.hs, using startupHook, however this runs each time xmonad is restarted with mod-q. Also in > xmonad-0.8 see spawnPid, mkSpawner, spawnOn.

Use manageHook to arrange your programs on different workspaces by matching various window properties such as className, appName (resource), title, or role.

3.13 Using floating windows

Use the regular swap or focus up and down to navigate them, and regular mod-enter to raise a window to the front. For a mod-enter binding, the darcs shiftMaster works better than swapMaster if you use multiple floats over tiled windows. See also this
swapDown manage hook warning above. If you use that manageHook on all windows you will create new floats behind existing ones. If you use lots of floats for some reason for better float usability see SimpleFloat layout, FloatKeys, Hooks.Place, and Config.Bluetile in xmonad-contrib.

3.14 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, i.e. .xinitrc, .xsession, display manager startup or
.Desktop files:

# For example, a nice left-pointing arrow head cursor

xsetroot -cursor_name left_ptr

If you have development headers for X11, other cursors can be found in /usr/include/X11/cursorfont.h

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.

3.15 Removing the borders around mplayer

You can also use the fullscreen layout, with the NoBorders smartBorders layout modifier, which automatically takes care of most cases.

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

3.16 I need to find the class title or some other X property of my program

When using XMonad.Layout.IM, ManageHooks, XMonad.Actions.WindowGo, or several other modules you need to specify detailed information about a window's properties.

See below for a script to nicely format output from the xprop program discussed in detail in this FAQ.

Otherwise, you can generally find what you need by splitting your screen between the window and a terminal; in the terminal, run xprop WM_CLASS or the like, and then click on the window. xprop will print out quite a bit of useful information about the window.

resource (also known as appName) is the first element in WM_CLASS(STRING)

It works like xprop: by default you click on a window with the crosshairs, or you can specify windows using the -id or -name options. (The -root and -font selectors could be used, but are less than useful. Also, -frame is unlikely to do anything useful.)

3.18 How can I send a key sequence to a window?

This can be useful when some application uses a hotkey that you
want to use in XMonad, yet be able to send the application window the
hotkey when needed.

A solution is to use xdotool,
which can (among other nifty things), send a fake keypress to the
currently focused window. So, for instance, you can use the following
keybinding to send Alt+L to the focused window by pressing Ctrl+Alt+L:

, ((mod1Mask|controlMask, xK_l), spawn "xdotool key alt+l")

xdotool can also paste
a line of ASCII text into the focused window. For instance, the
following keybinding will insert the email address email@example.org
each time the key Ctrl+Alt+e is pressed:

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, layout, and even arbitrary

[X (MaybeString)]

, and format them nicely, printing them to xmonad's stdout.

3.20 How can I make xmonad use UTF8?

TODO: is this still accurate? Doesn't xmonad-0.8 and greater always use UTF8 with no extra imports or configuration changes?

Due to extensions like DynamicLog, xmonad is capable of text outputting which is not by default but can be encoded in UTF8. Therefore, if you want to output non-ASCII characters, you can take advantage of the System.IO.UTF8 module.

For example using DynamicLog you can define its output ppOutput like his:

As it may not be ideal to reopen the file before every writing, you can just place the code somewhere else. See ray's config in xmonad's config archive.

3.21 How do I use compositing with xmonad?

Xmonad has the ability to use some compositing features yet still be actually useable ;-). For example, some really nice transparency can be used with a composite aware app like urxvt and xcompmgr.

First enable compositing in your X server configuration by including the following in your xorg.conf

Section "Extensions"
Option "Composite" "enable"
EndSection

restart the X server and confirm it's working with xdpyinfo | grep Composite. If it returns Composite, then good...

Include this in ~/.Xdefaults

URxvt.depth: 32
URxvt*background: rgba:0000/0000/0000/cccc

this specifies that urxvt uses 32 bit colors and uses a transparent black background. The four c's specify the amount of alpha with ffff being full black and 0000 being fully transparent. You can also use the fading and blurRadius resources to give some nice effects in the transparency. see man urxvt.

finally you need to fire up xcompgr so that this will all actually work. probably you'll want to include it in your ~/.xinitrc or ~/.xsession file:

xcompmgr -c &

the -c option provides a soft shadow around your windows. There are many options, see man xcompmgr.

For an example with screenshots see andrewsw's config in the config archive.

On newer versions of XMonad, see also XMonad.Hooks.FadeInactive documentation.

3.22 How do I find a function which does ...?

Hayoo! API search can be used to find existing functions within XMonad and XMonadContrib which do useful things. For example, the search string

(next AND screen) package:xmonad

will find all existing functions which mention moving to the next Xinerama screen.

4 Troubleshooting

4.1 Multi head or xinerama troubles

4.1.1 xmonad does not detect my multi-head setup

To diagnose the problem, execute the following on the command line:

ghc -e Graphics.X11.Xinerama.compiledWithXinerama

If the output is True, skip to the getScreenInfo test below. If the output is False, your Haskell X11 library was not built against Xinerama. This is true of old Debian and Ubuntu packages, and may also occur if you built from source.

First, be sure that the Xinerama development headers are installed (libxinerama-dev in Debian and Ubuntu).

Next, check the configure output for the Haskell X11 library for the following lines (If using cabal: cabal install X11 -v --reinstall):

In the X11, xmonad and xmonad-contrib source directories. Try the compiledWithXinerama diagnostic again, this time it should return True. As always, execute "xmonad --recompile" when reinstalling any part of xmonad.

If compiledWithXinerama is True and multi-head still doesn't work, execute "xmonad --recompile" and press mod-q. If the problem persists, execute this command:

Check to see whether there is a Rectangle corresponding to each of your screens. If there is not, and the compiledWithXinerama diagnostic returns True, there may be a problem with your X server configuration. The most common one is having your monitors set to clone one another. See 'man xrandr', or, if using the proprietary nvidia drivers, 'nvidia-settings' to see how reconfigure them.

Also, there can be two versions of the X11 haskell library installed, one of them built with Xinerama, and other without it. If XMonad is using the one built with Xinerama, and the output of the commands use the version without it, all these tests will work but these problems will persist. Check the output of ghc-pkg to see if there is more than one version of X11 installed.

4.1.2 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

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

4.1.4 Something is weird with multi head windows or workspaces (desktops)

This message seen at xmonad's stdout when starting xmonad means that another window manager is already running. If the other WM was started from a DE, you can use Util.Replace to have xmonad ask the other WM to exit before starting up. Note: If exiting your previously running wm would lead to your X session ending, then this method won't work.

Otherwise refer to the appropriate page for starting xmonad instead of your other WM (Gnome, KDE).

4.3 mod-q doesn't work

4.3.1 Upgraded GHC and now xmonad xmonad-contrib etc are not found

When you change ghc versions you need to rebuild or reinstall haskell libraries to make sure they are compatible and registered with the new ghc. Often your distro packagers will try to make this as automatic as possible, by making it just happen. Or at least they will make it easier, e.g. gentoo's ghc-updater and haskell-updater. (This isn't just a Haskell/ghc issue; it's true for other languages, too: c.f. python-updater scripts, distro policies regarding gcc and glibc changes.)

4.3.2 Changes to the config file ignored or 'xmonad not found' when starting X

Both ghc and xmonad must be in your display manager init's $PATH when starting X and xmonad for reconfiguration by mod-q. Make sure the environment from which you start xmonad has the appropriate settings.

When changing the xmonad.hs 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 haskell-X11 or XMonadContrib library, changes to that package will not be noticed by xmonad's recompilation
checker, so xmonad.hs won't be recompiled. (needs confirmation: is this true?) To fix this:

xmonad --recompile

after reinstalling the contrib library.

4.4 Tabbed or other decorated layouts not shown

Both xmobar and xmonad's default
Theme
use the -misc-fixed-*-*-*-*-10-*-*-*-*-*-*-* font by default. This is
possibly the most commonly installed font in the *nix world, but if it's not installed,
or core fonts aren't working for some reason, you'll have problems. Without the font
you have set in your Theme....

tabs and other decorated layouts will simply not draw. There should be font related errors
in .xsession-errors or wherever your display manager directs stderr to help confirm that
this is the cause of missing decorations. xmobar will spit out a cryptic error message
and refuse to run.

Check with xfontsel that you have the fixed 10 font if you want to use the defaults.
For xft, check that your xmonad and xmobar were compiled with xft support. (They are
by default on most distros) Then customize your theme by using something like the
following in your layoutHook

4.5 DE panels pagers or EwmhDesktops are broken (just upgraded to >0.8)

Starting with 0.9,
EwmhDesktops users mustchange configuration by removing the obsolete ewmhDesktopsLayout from layoutHook, (it no longer exists), and updating to the current ewmh support which still includes a logHook, but in place of the old layout modifier, uses a startupHook and handleEventHook (see ff.).(No need to change config if using ewmh via Config.Desktop, Config.Gnome, etc. Your config will automatically be updated to use current ewmh support.)

Users of defaultConfig that explicitly include EwmhDesktops hooks and the ewmhDesktopsLayout modifier should remove them and instead use the new

ewmh

function which adds EWMH support to

defaultConfig

all at once. You should keep avoidStruts and manageDocks if you're using them.

4.6 defaultGaps doesn't work any more! (just upgraded to >0.7)

See Make space for a panel section: use XMonad.Hooks.ManageDocks avoidStruts for this instead of Gaps, or import XMonad.Layout.Gaps.

4.7 Showing fractions of lines in gvim, urxvt,etc.

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. Aside from patching the offending program, you can:

Use a layout which uses these size hints like Hinted Grid, or HintedTile

4.8 Emacs mini-buffer starts at wrong size

ontoillogical says: Most people turn off menus and toolbars and adjust fonts in their .emacs. That's what breaks emacs' display in tiling WMs. To get emacs to look correctly, move all of the stuff that affects how emacs draws a frame to .Xdefaults/.Xresources

If you're having emacs sizing problems setting these in .Xdefaults is still worth a try even if you don't have any custom .emacs settings.

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

The simplest solution is to up/downgrade to a kernel version without this bug.

4.11 XMonad is frozen!

4.11.1 XMonad stops but the current window still responds to keys

Usually this is because a dynamicLog is writing to a pipe handle that's not being read. For example the xmonad.hs writes to some status bar in the logHook, but the status bar is not installed, not in $PATH, not set up to read its stdin, or just plain not running. Eventually the pipe fills up and blocks and xmonad waits for it to be read before continuing.

To cat the full pipe and free up xmonad, find xmonad's pid via pgrep or htop, etc. let's say it's 1001, then ls -l /proc/1001/fd/ and look for the largest numbered pipe. Let's use 4. Then cat /proc/1001/fd/4 to unblock xmonad so you can fix your xmonad.hs and xmobarrc to work correctly. (If catting that pipe doesn't spew out a bunch of stuff and unfreeze things, try the others listed.)

With the post 0.9

=<< xmobar

and

statusBar

modifiers it isn't obvious that xmonad is writing to a pipe. If you don't want xmonad info shown in your
status bar, you will probably be better off launching it by other means such as .xinitrc. You can also customize your PP's ppOutput field to use the default

hPutStrLn

to write to stdout, or change it to

\s ->return()

to do nothing at all.
With xmobar, if your logHook is writing to its stdin via

4.11.2 XMonad stops responding to keys (usually due to unclutter)

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.
Or use XMonad.Actions.Warp or XMonad.Actions.UpdatePointer xmonad-contrib extension instead.

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

Often you can get X to behave again by running 'xclock -display :0' on the appropriate display via ssh or from a virtual terminal. If that's not enough kill suspect apps similarly.

There is also an option in (pre evdev versions of) 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"

4.12 Problems with Java applications, Applet java console

There are two classes of problems: blank, grey windows and windows that can't be focused for keyboard input. The latter should be fixed in the newest xmonad, so follow the instructions on the website for getting a copy of the darcs repository and build it. Remember to rebuild xmonad-contrib (preferably also from darcs) afterwards! The remainder of this section covers the blank, grey window problems.

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.

4.12.1 Preferred Method

If you are using openjdk6 >= 1.6.1, the cleanest way to work around the hardcoded list is to warn the vm that xmonad is non-reparenting by exporting the appropriate environment variable:

_JAVA_AWT_WM_NONREPARENTING=1

Using JDK 7 seems to work well, too, see below.

4.12.2 Using SetWMName

Otherwise, you can lie to Java about what window manager you are using, by having the SetWMName extension convince Java that xmonad is "LG3D". (**WARNING: This *breaks* recent versions of gtk+3!** Use the Preferred Method above instead, if necessary upgrading your Java to a version which supports it.) Normally you would use this in the startup hook, like this:

However, modules using Hooks.EwmhDesktops, such as Config.Gnome, Config.Desktops, etc. also set WM Name as part of supporting Extended Window Manager Hints. Combining EWMH support with the "LG3D" workaround takes special attention to modifying the appropriate hook for your xmonad version:

Starting with xmonad-0.9. the window manager name is set once in EWMH startupHook after each mod-q, along with other EWMH initialization, but after that can be changed and not overwritten till the next mod-q. See below for example startupHooks combining both startupHooks.

In xmonad versions 0.7 and 0.8 the EWMH configs setWMName to "xmonad" on each logHook event, so to use "LG3D" instead, it's necessary to either

patch the XMonad.Hooks.EwmhDesktops source and rebuild xmonad-contrib

OR

use the version 0.8.* hack shown below to repeatedly setWMName "LG3D" after the ewmh logHook runs.

With xmonad-0.9 or greater there is no need to spam the X server with setWMName in logHook, see above for how to modify startupHook instead.

4.12.4 Changing AWT Toolkit

Another option is to use an AWT toolkit that is more window manager agnostic, (Some report that this causes keyboard to fail in some java applications. It also doesn't seem to work as widely or reliably as setWMName or other preferred methods above.) If you want to try it, set the environment variable:

Even if you don't use Bash, you can often set environmental variables by putting them in .profile and logging back in:

export AWT_TOOLKIT=MToolkit

Using the free blackdown java runtime also seems to work correctly to fix this issue.

4.12.5 Use JDK 7

Using JDK 7 also seems to work well.

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.

Gunnar Ahlberg #xmonad:

JDK 7 solved problems remaining even when using setWMName "LG3D" in logHook.

4.12.6 Persuade a java application to use a specific java runtime (JRE)

Sometimes it turns out that a program works with a specific JRE version, but not with another. Commercial programs tend to ship with their own JRE, so you may even notice that one program works while another doesn't. (For example, I've had a setup where Maple had problems while Matlab behaved well.) A java symlink in the right place can do wonders here. See this Ubuntu bug report for a number of examples.

4.13 XMonad doesn't save my layouts and windows

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.

4.14 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 use a
French keyboard layout. You may need to set your own mod key, or use
different key bindings in xmonad.hs. See the xmonad.org docs on configuring and customizing for advice on rebinding keys. Also currently xmonad only handles the first of duplicate key symbols bound, so if you have for example multiple xK_Backspace keys not all will be bound. There are patches available on the xmonad mailing list (or darcswatch) to change this.

4.14.1 Media keys

XMonad.Util.EZConfig additionalKeysP or Graphics.X11.ExtraTypes are the best way to bind the XF86 family of special keys. Note that some special laptop keys are handled by acpi and may show up as button events instead, or even bypass X completely.

4.14.2 French keyboard workspace switching

See XMonad.Config.Azerty for an azertyConfig to use in place of defaultConfig. This will adjust keybindings for the azerty layout, fixing workspaces switching, etc.

4.14.3 Numeric keypad keys like xK_KP_2 not working

Bind to the non-numeric versions of these keys. They work regardless of NumLock status. To avoid conflicts with other apps you probably want to use them with modifiers. Here is an example of using them to navigate workspaces in the usual mod-N mod-shift-N way, but on the key pad:

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

4.16 OpenOffice looks bad

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

OOO_FORCE_DESKTOP=gnome

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

4.17 Help! xmonad just segfaulted

if you updated a previously built xmonad, or XMonadContrib, when a
dependent library has changed in the meantime, GHC will happily 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 example, 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:

xmonad --recompile

Another possibility is your xmonad was compiled against a very old
version of the haskell-x11 library. Use haskell-X11-1.4.2 or newer.
This version incorporates a couple of WM_HINTS related segfault bug
fixes.

When using ghc 6.6, or old versions of Cabal, you may get errors when configuring:

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

4.20 A manage hook is having no effect

If a manage hook that checks an attribute of a window(e.g. resource =? "foo"
--> bar) doesn't work even though the property is the same as reported by
xprop, it can be caused by a program setting the corresponding property after
the window has been created. To debug whether or not the term on the right
hand side is at fault, it is useful to log which resource (or other property)
xmonad sees:

(resource >>= io .appendFile"/home/<youruser>/xmonad_debug">> idHook)

If opening the desired window causes xmonad to produce a log entry with the
resource you were interested in, it means that the term on the right-hand side
of --> is not working.