Daniel Gröber edited this page Sep 17, 2017 · 10 revisions

Installing the ghc-mod program

Using the cabal tool

The recommended way to install ghc-mod is using cabal, however you can also install it using stack, see Installing the ghc-mod program using Stack.

Checking and installing prerequisites

Starting with ghc-mod version you need a more recent version of cabal , namely Cabal-, than is contained in most distributions. To check which version you have on your system run:

$ cabal --version
cabal-install version
compiled using version of the Cabal library

You'll want to see a cabal-install version greater than 1.24. If this is not the case you first need to install a more recent version of the cabal tool, which is part of the cabal-install package, by running the following command in your home directory:

$ cabal install cabal-install

This will install the cabal executable into ~/.cabal/bin. If you want you can add this directory to your PATH which is assumed below but you can also just refer to the executable by its full path for the purposes of installing ghc-mod. Just replace cabal in the instructions below by ~/.cabal/bin/cabal.

Actually installing ghc-mod

Now you're ready to actually install the ghc-mod program. Simply run the following command in your home directory:

$ cabal install ghc-mod

This will install the ghc-mod package and place the ghc-mod executable into ~/.cabal/bin which you might have to add to your PATH depending on the frontend you are going to use.

That's it, now go figure out which Frontend you're going to use and how to configure it.

Using the stack tool

There are two ways to install ghc-mod with Stack:

  • Global installation
  • Per project installation

The basic procedure is almost the same for both but slightly different so beware.

Global installation

First a few words of caution: Since Stack manages and pins GHC versions per project you need to make sure the ghc-mod you compile as part of a global installation is linked against the same version of GHC as the project(s) you are going to work with otherwise you will most likely get nothing but bizarre looking errors.

To run the installation simply run the command below in your home directory.

stack install ghc-mod

This will install the ghc-mod executables into ~/.local/bin which you will want to add to your PATH.

Per project installation

(Note: This is untested)

Run the following command in your project directory:

stack install ghc-mod --no-copy-bins

This will install ghc-mod into <project directory>/.stack-work/install/*/*/*/bin/.

Doing this has the advantage that you build ghc-mod with whatever GHC version your project is using but your frontend either has to support finding ghc-mod in .stack-work/ or you have to play around with PATH.

Once Support switching GHC versions without recompiling ghc-mod, #615 is fixed this should not be required anymore.

(See also:

Adding .cabal/bin to the PATH environment variable

How to do this varies with the platform you are using, see below.


On GNU/Linux one way to add a directory to the executable search path for desktop sessions is via .xsessionrc. This file gets sourced (shell terminology) before your desktop/window manager is executed and thus any environment variables set in this script will propagate down to everything you run in this session.

By adding something like the following to ~/.xsessionrc you can extend PATH to include ~/.cabal/bin and ~/.local/bin (only needed for stack). If the file doesn't exist yet you'll need to create it.

# add Cabal's bin directory to the executable search PATH if it exists
if [ -d "$HOME/.cabal/bin" ] ; then

# add Stack's bin directory to the executable search PATH if it exists
if [ -d "$HOME/.local/bin" ] ; then

See also: Debian Wiki EnvironmentVariables Page

Mac OS X (with root)

Unfortunately on OSX desktop sessions do not source environment variables from any place that can be easily altered for a single user.

So we have to resort to a more crude method that requires super user priviledges, unless you'd rather not do that in which case see below.

You can add something like the following to /etc/launchd.conf:

setenv PATH /usr/bin:/bin:/usr/local/bin:<home directory>/.cabal/bin:<home directory>/.local/bin

Replace <home directory> with the output of running echo $HOME in your shell.

Once you modified this file you'll have to reboot for the changes to take effect.

See .

Mac OS X (without root)

You can also add the PATH setting to all applications where you are likely to need it seperately. Usually this is going to be your $EDITOR and your $SHELL:

Emacs (OSX)

In Emacs you can add the following to your .emacs configuration Emacs Manual, The Emacs Initialization File:

(setenv "PATH" (concat (getenv "PATH") ":" (getenv "HOME") "/.cabal/bin" ":" (getenv "HOME") "/.local/bin"))
(setq exec-path (append exec-path (list (concat (getenv "HOME") "/.cabal/bin") (concat (getenv "HOME") "/.local/bin"))))

Note that here you have to modify both the PATH environment variable and the regular exec-path variable. Emacs initializes exec-path with the contents of PATH on startup but doesn't sync them afterwards so when you use the systemwide PATH approach you don't need to bother with that.

Vim (OSX)

In your .vimrc, or in some file sourced from there, you can use let to add to your path:

let $PATH .= (":" . $HOME . "/.cabal/bin" . ":" . $HOME . "/.local/bin")