The xmonad-entryhelper package


xmonad-entryhelper makes your compiled XMonad config a standalone binary.

It simulates the XMonad's argument handling and supports customized compliation.

Please check README for details.

[Skip to ReadMe]


Dependenciesbase (<5), directory, extensible-exceptions, filepath, mtl, process, unix, X11, xmonad, xmonad-contrib [details]
CopyrightCopyright (c) 2015 Javran Cheng
AuthorJavran Cheng
Home page
Bug tracker
Source repositoryhead: git clone
UploadedSat Jan 17 07:17:37 UTC 2015 by javran




Maintainers' corner

For package maintainers and hackage trustees

Readme for xmonad-entryhelper-


Build Status Version

xmonad-entryhelper makes your compiled XMonad config a standalone binary.

It simulates the XMonad's argument handling and supports customized compliation.

Table of Contents


xmonad-entryhelper frees you from keeping a xmonad library as a system- or user- level dependency. Instead, you can keep your XMonad configurations either as a local cabal project using cabal sandbox or within a protected environment like those created by hsenv

Simple setup

  1. After installation, modify your xmonad.hs accordingly:

    Your xmonad config might look like:

     -- some imports here
     import ...
     -- your main entry point
     main :: IO ()
     main = _

    Rename your main to something else, import withHelper from XMonad.Util.EntryHelper and use it to call your old main:

     -- some imports here
     import ...
     import XMonad.Util.EntryHelper (withHelper)
     -- your old main entry point
     oldMain :: IO ()
     oldMain = _
     -- your new main entry point
     main :: IO ()
     main = withHelper oldMain

    It is recommended to set the "restart xmonad" action (typically mod-q in your keybinding) to just invoke xmonad --restart. Although the default action, essentially xmonad --recompile && xmonad --restart should work properly, argument --recompile forces the compilation (which might involve removing all binaries and compiling everything). If you are using a build system like make or cabal, forcing a compilation might not be a desired behavior as build systems are in general designed to prevent recompilation.

  2. Finally you need to have a writable local PATH directory.

    For example you can make directory $HOME/bin:

     mkdir -p ~/bin

    And append the following lines in your shell profile file (it's usually your ~/.bash_profile file):

     # my local executable files
     export PATH="${HOME}/bin:${PATH}"

    Create soft link to your compiled xmonad binary:

     # the binary name varies depending on your OS and architecture,
     # check your ~/.xmonad/ directory to find out
     $ ln -s ~/.xmonad/xmonad-x86_64-linux ~/bin/xmonad

    And verify if xmonad is now leading to your compiled xmonad config:

     $ source ~/.profile
     $ which xmonad

    If this doesn't work, check articles like Zsh/Bash startup files loading order for troubleshooting.

  3. Now you are free to remove XMonad from your system- or user- level packages. Because your compiled XMonad will work on its own:

     $ xmonad --help
     xmonad-entryhelper - XMonad config entry point wrapper
     Usage: xmonad [OPTION]
       --help                       Print this message
       --version                    Print XMonad's version number
       --recompile                  Recompile XMonad
       --replace                    Replace the running window manager with XMonad
       --restart                    Request a running XMonad process to restart

Argument handling

Although this projects tries to resemble the argument handling behavior of XMonad, there are not exact the same. The differences are:

Advanced features


Feel free to open issues for either bug report, enhancement or discussion.