How to Setup a Haskell Programming Environment with Nix

With a few lines you can setup your Haskell programming environment (compilers, packages, databases, browsers, and other tools from different ecosystems) with having only the Nix Package Manager installed.

You can check this environment into source control, share it with colleagues and bring them up to speed in seconds. No manually installing apps and—if gone all the way—no “It works on my machine!” due to different package versions.
More: How to install Nix

Nix installs the terminal app nix-shell which creates an environment. In this tutorial we will see how to use it by slowly progressing from simple to intermediate usage.
tldr: Go to final usage example

Try Out Haskell Tools In Nix-Shell

Once the Nix Package Manager is installed, you need to have or create a project folder:

~$ mkdir myproject && cd myproject

In order to compile Haskell files, you need a Haskell compiler like Ghc and preferably a build tool like Cabal.

To get those tools with Nix run:

~/myproject$ nix-shell -p cabal-install ghc

This will download some necessary files and place you in a new shell environment—indicated by changing the shell prompt to [nix-shell:~/myproject]$—where the terminal apps ghc and cabal are available:

[nix-shell:~/myproject]$ cabal --version
cabal-install version 3.0.0.0

Isn’t that convenient? The best thing about nix-shell is that you can make any app in any version available that exists in the Nix Package Repository (e.g. Git and Visual Studio).

Now you can create a basic project folder structure with:

[nix-shell:~/myproject]$ cabal init

You can play around with the Main.hs Haskell file and the project definition file myproject.cabal. You can download any required Haskell package from that definition file by running cabal update, interactively test your app withcabal new-repl, build it with cabal new-build, and run it with the cabal new-run myproject command. These commands work, because Cabal can call the ghc compiler app, which is now also available in the shell environment.
More: A short intro to Cabal (Prefer the newer cabal new-* commands)

Another huge benefit of nix-shell is that it installs Ghc and Cabal locally. It doesn’t modify or pollute the rest of your system. If you run

[nix-shell:~/myproject]$ exit

you will be back in your normal shell environment where Ghc and Cabal don’t exist:

~/myproject$ cabal
cabal: command not found

Think about it: If you work on multiple project that use different versions of Ghc, packages or any other app, these versions will never come into conflict, because they only exist locally in separate environments.

Getting Started On a Haskell Project with a shell.nix file

In most projects you will need more than just a few tools. Remembering what they are and typing them out by hand into a nix-shell -p ... quickly becomes unusable. For that you can specify all your apps, tools and dependencies in a shell.nix file in your project root folder:

# minimal ~/myproject/shell.nix file
let
  myNixPkgs = import <nixpkgs> {};
in
myNixPkgs.mkShell {
  nativeBuildInputs = with myNixPkgs; [
    cabal-install # terminal app cabal
    ghc # Haskell compiler
  ];
}

# minimal ~/myproject/shell.nix file
...
  nativeBuildInputs = with myNixPkgs; [
    # General dev tools
    git 
    ripgrep # Fast text search alternative to grep. Terminal command: "rg"
    vscode # Visual Studio Code. Terminal command: "code"
    # Haskell dev tools
    cabal-install # terminal command: "cabal" 
    ghc # Haskell compiler
    haskellPackages.ghcid # Haskell Code checker
  ];
...

This file is written in the Nix (programming) language and defines the same shell environment (where Cabal and Ghc exist) as the nix-shell -p cabal-install ghc command . You can get into this environment with:

~/myproject$ nix-shell

If you don’t pass any arguments to nix-shell, it will automatically load the environment from the shell.nix file if it exists.

Some popular Haskell packages like digest for cryptographically strong hashing or JuicyPixels for image manipulation require some external C libraries like zlib.h (for fast compression algorithms) that our currently loaded Ghc doesn’t know about. So, if you mention those packages as dependencies in your myproject.cabal file, you will get a compile error that a library is missing:

[nix-shell:~/myproject]$ cabal new-build
...
cabal: Missing dependency on a foreign library:
* Missing (or bad) header file: zlib.h
* Missing (or bad) C library: z
...

Usually, you would now have to install those libraries by hand. To learn how to avoid any manual work by letting Nix manage those Haskell packages dependencies, read on.

When something is managed by Nix, Nix decides where to download from, what version to use and where to store them on your system to not to interfer with the rest of your system. However, when you call cabal update, Cabal decides where to download packages from, which version to use and where to install them. Nix is very good at creating independent environments and reproducibility: If done right, Nix can be configured to recreate an bit-by-bit identical environment for the same shell.nix file. Cabal is less capable. For example, it currently installs packages “globally” into a folder like ~/.cabal/packages.

Let Nix manage Haskell packages for Cabal

You can let Nix manage not only your tools like Ghc and Cabal, but also dependencies like Haskell packages. Nix will also take care to download and provide any external libraries that a package may need. So you don’t need to do that manually.

If you have followed along, you should already have a myproject.cabal file in your project root folder. Then you can just replace your shell.nix with the following:

# extended "~/myproject/shell.nix" file
let
  myNixPkgs = import <nixpkgs> {
    overlays = [myNixPkgsOverlay];
  };

  myNixPkgsOverlay = (nixSelf: nixSuper: {
    myHaskellPackages = nixSelf.haskellPackages.override (oldHaskellPkgs: {
      overrides = nixSelf.lib.composeExtensions (oldHaskellPkgs.overrides or (_: _: {}))  myHaskellPkgsOverlay;
    });
  });

  myHaskellPkgsOverlay = (hSelf: hSuper: {
    # "myproject" is the first part of the "myproject.cabal" project definition file
    myProject = hSelf.callCabal2nix "myproject" ./. {};
  });
in
myNixPkgs.myHaskellPackages.myProject.env

The important line that tells Nix to manage your Haskell packages is:

myProject = hSelf.callCabal2nix "myproject" ./. {};

It creates a new Haskell package myproject that requires those packages as dependencies which you mention in your myproject.cabal file. By convention Haskell packages (and those created with callCabal2nix) have an attribute .env which contains a description for a shell environment with all necessary dependencies to develop that package. This environment is what we load with the last line:

myNixPkgs.myHaskellPackages.myProject.env

This includes Ghc, but unfortuneately not Cabal, because Cabal is not strictly necessary to compile a package/project. You could do it with Ghc alone. To see how to add Cabal and other tools to this environment, read on.

~/myproject$ nix-shell -p cabal-install ghc --run "cabal init"

((import <nixpkgs> {}).haskellPackages.callCabal2nix "myproject" ./. {}).env

Final Bootstrable shell.nix File

A convenient shell.nix to start with is the following:

# full "~/myproject/shell.nix" file
let
  myNixPkgs = import <nixpkgs> {
    overlays = [myNixPkgsOverlay];
  };

  myNixPkgsOverlay = (nixSelf: nixSuper: {
    myHaskellPackages = nixSelf.haskellPackages.override (oldHaskellPkgs: {
      overrides = nixSelf.lib.composeExtensions (oldHaskellPkgs.overrides or (_: _: {}))  myHaskellPkgsOverlay;
    });
  });

  myHaskellPkgsOverlay = (hSelf: hSuper: {
    # "myproject" is the first part of the "myproject.cabal" project definition file
    myProject = hSelf.callCabal2nix "myproject" ./. {};
  });
  
  myDevTools = with myNixPkgs; [
    cabal-install 
    haskellPackages.ghcid
  ];

  myShellHook = ''
    alias repl="cabal new-repl"
  '';
in
myNixPkgs.myHaskellPackages.myProject.env.overrideAttrs (oldEnv: {
  nativeBuildInputs = oldEnv.nativeBuildInputs ++ myDevTools;
  shellHook = myShellHook;
})

~/myproject$ nix-shell -p cabal-install ghc --run "cabal init"