2title: User's Guide for Haskell in Nixpkgs
7# How to install Haskell packages
9Nixpkgs distributes build instructions for all Haskell packages registered on
10[Hackage](http://hackage.haskell.org/), but strangely enough normal Nix package
11lookups don't seem to discover any of them:
13 $ nix-env -qa cabal-install
14 error: selector ‘cabal-install’ matches no derivations
17 error: selector ‘ghc’ matches no derivations
19The Haskell package set is not registered in the top-level namespace because it
20is *huge*. If all Haskell packages were visible to these commands, then
21name-based search/install operations would be much slower than they are now. We
22avoided that by keeping all Haskell-related packages in a separate attribute
23set called `haskellPackages`, which the following command will list:
25 $ nix-env -f "<nixpkgs>" -qaP -A haskellPackages
26 haskellPackages.a50 a50-0.5
27 haskellPackages.abacate haskell-abacate-0.0.0.0
28 haskellPackages.abcBridge haskell-abcBridge-0.12
29 haskellPackages.afv afv-0.1.1
30 haskellPackages.alex alex-3.1.4
31 haskellPackages.Allure Allure-0.4.101.1
32 haskellPackages.alms alms-0.6.7
33 [... some 8000 entries omitted ...]
35To install any of those packages into your profile, refer to them by their
36attribute path (first column):
38 $ nix-env -f "<nixpkgs>" -iA haskellPackages.Allure ...
40The attribute path of any Haskell packages corresponds to the name of that
41particular package on Hackage: the package `cabal-install` has the attribute
42`haskellPackages.cabal-install`, and so on. (Actually, this convention causes
43trouble with packages like `3dmodels` and `4Blocks`, because these names are
44invalid identifiers in the Nix language. The issue of how to deal with these
45rare corner cases is currently unresolved.)
47Haskell packages who's Nix name (second column) begins with a `haskell-` prefix
48are packages that provide a library whereas packages without that prefix
49provide just executables. Libraries may provide executables too, though: the
50package `haskell-pandoc`, for example, installs both a library and an
51application. You can install and use Haskell executables just like any other
52program in Nixpkgs, but using Haskell libraries for development is a bit
53trickier and we'll address that subject in great detail in section [How to
54create a development environment].
56Attribute paths are deterministic inside of Nixpkgs, but the path necessary to
57reach Nixpkgs varies from system to system. We dodged that problem by giving
58`nix-env` an explicit `-f "<nixpkgs>"` parameter, but if you call `nix-env`
59without that flag, then chances are the invocation fails:
61 $ nix-env -iA haskellPackages.cabal-install
62 error: attribute ‘haskellPackages’ in selection path
63 ‘haskellPackages.cabal-install’ not found
65On NixOS, for example, Nixpkgs does *not* exist in the top-level namespace by
66default. To figure out the proper attribute path, it's easiest to query for the
67path of a well-known Nixpkgs package, i.e.:
69 $ nix-env -qaP coreutils
70 nixos.pkgs.coreutils coreutils-8.23
72If your system responds like that (most NixOS installatios will), then the
73attribute path to `haskellPackages` is `nixos.pkgs.haskellPackages`. Thus, if
74you want to use `nix-env` without giving an explicit `-f` flag, then that's the
77 $ nix-env -qaP -A nixos.pkgs.haskellPackages
78 $ nix-env -iA nixos.pkgs.haskellPackages.cabal-install
80Our current default compiler is GHC 7.10.x and the `haskellPackages` set
81contains packages built with that particular version. Nixpkgs contains the
82latest major release of every GHC since 6.10.4, however, and there is a whole
83family of package sets available that defines Hackage packages built with each
84of those compilers, too:
86 $ nix-env -f "<nixpkgs>" -qaP -A haskell.packages.ghc6123
87 $ nix-env -f "<nixpkgs>" -qaP -A haskell.packages.ghc763
89The name `haskellPackages` is really just a synonym for
90`haskell.packages.ghc7101`, because we prefer that package set internally and
91recommend it to our users as their default choice, but ultimately you are free
92to compile your Haskell packages with any GHC version you please. The following
93command displays the complete list of available compilers:
95 $ nix-env -f "<nixpkgs>" -qaP -A haskell.compiler
96 haskell.compiler.ghc6104 ghc-6.10.4
97 haskell.compiler.ghc6123 ghc-6.12.3
98 haskell.compiler.ghc704 ghc-7.0.4
99 haskell.compiler.ghc722 ghc-7.2.2
100 haskell.compiler.ghc742 ghc-7.4.2
101 haskell.compiler.ghc763 ghc-7.6.3
102 haskell.compiler.ghc784 ghc-7.8.4
103 haskell.compiler.ghc7101 ghc-7.10.1
104 haskell.compiler.ghcHEAD ghc-7.11.20150402
105 haskell.compiler.ghcjs ghcjs-0.1.0
106 haskell.compiler.jhc jhc-0.8.2
107 haskell.compiler.uhc uhc-1.1.9.0
109We have no package sets for `jhc` or `uhc` yet, unfortunately, but for every
110version of GHC listed above, there exists a package set based on that compiler.
111Also, the attributes `haskell.compiler.ghcXYC` and
112`haskell.packages.ghcXYC.ghc` are synonymous for the sake of convenience.
114# How to create a development environment
116## How to install a compiler
118A simple development environment consists of a Haskell compiler and the tool
119`cabal-install`, and we saw in section [How to install Haskell packages] how
120you can install those programs into your user profile:
122 $ nix-env -f "<nixpkgs>" -iA haskellPackages.ghc haskellPackages.cabal-install
124Instead of the default package set `haskellPackages`, you can also use the more
125precise name `haskell.compiler.ghc7101`, which has the advantage that it refers
126to the same GHC version regardless of what Nixpkgs considers "default" at any
129Once you've made those tools available in `$PATH`, it's possible to build
130Hackage packages the same way people without access to Nix do it all the time:
132 $ cabal get lens-4.11 && cd lens-4.11
133 $ cabal install -j --dependencies-only
137If you enjoy working with Cabal sandboxes, then that's entirely possible too:
138just execute the command
142before installing the required dependencies.
144The `nix-shell` utility makes it easy to switch to a different compiler
145version; just enter the Nix shell environment with the command
147 $ nix-shell -p haskell.compiler.ghc784
149to bring GHC 7.8.4 into `$PATH`. Re-running `cabal configure` switches your
150build to use that compiler instead. If you're working on a project that doesn't
151depend on any additional system libraries outside of GHC, then it's sufficient
152even to run the `cabal configure` command inside of the shell:
154 $ nix-shell -p haskell.compiler.ghc784 --command "cabal configure"
156Afterwards, all other commands like `cabal build` work just fine in any shell
157environment, because the configure phase recorded the absolute paths to all
158required tools like GHC in its build configuration inside of the `dist/`
159directory. Please note, however, that `nix-collect-garbage` can break such an
160environment because the Nix store paths created by `nix-shell` aren't "alive"
161anymore once `nix-shell` has terminated. If you find that your Haskell builds
162no longer work after garbage collection, then you'll have to re-run `cabal
163configure` inside of a new `nix-shell` environment.
165## How to install a compiler with libraries
167GHC expects to find all installed libraries inside of its own `lib` directory.
168This approach works fine on traditional Unix systems, but it doesn't work for
169Nix, because GHC's store path is immutable once it's built. We cannot install
170additional libraries into that location. As a consequence, our copies of GHC
171don't know any packages except their own core libraries, like `base`,
172`containers`, `Cabal`, etc.
174We can register additional libraries to GHC, however, using a special build
175function called `ghcWithPackages`. That function expects one argument: a
176function that maps from an attribute set of Haskell packages to a list of
177packages, which determines the libraries known to that particular version of
178GHC. For example, the Nix expression `ghcWithPackages (pkgs: [pkgs.mtl])`
179generates a copy of GHC that has the `mtl` library registered in addition to
180its normal core packages:
182 $ nix-shell -p "haskellPackages.ghcWithPackages (pkgs: [pkgs.mtl])"
184 [nix-shell:~]$ ghc-pkg list mtl
185 /nix/store/zy79...-ghc-7.10.1/lib/ghc-7.10.1/package.conf.d:
188This function allows users to define their own development environment by means
189of an override. After adding the following snippet to `~/.nixpkgs/config.nix`,
192 packageOverrides = super: let self = super.pkgs; in
194 myHaskellEnv = self.haskell.packages.ghc7101.ghcWithPackages
195 (haskellPackages: with haskellPackages; [
197 arrows async cgi criterion
199 cabal-install haskintex
204it's possible to install that compiler with `nix-env -f "<nixpkgs>" -iA
205myHaskellEnv`. If you'd like to switch that development environment to a
206different version of GHC, just replace the `ghc7101` bit in the previous
207definition with the appropriate name. Of course, it's also possible to define
208any number of these development environments! (You can't install two of them
209into the same profile at the same time, though, because that would result in
212The generated `ghc` program is a wrapper script that re-directs the real
213GHC executable to use a new `lib` directory --- one that we specifically
214constructed to contain all those packages the user requested:
217 #! /nix/store/xlxj...-bash-4.3-p33/bin/bash -e
218 export NIX_GHC=/nix/store/19sm...-ghc-7.10.1/bin/ghc
219 export NIX_GHCPKG=/nix/store/19sm...-ghc-7.10.1/bin/ghc-pkg
220 export NIX_GHC_DOCDIR=/nix/store/19sm...-ghc-7.10.1/share/doc/ghc/html
221 export NIX_GHC_LIBDIR=/nix/store/19sm...-ghc-7.10.1/lib/ghc-7.10.1
222 exec /nix/store/j50p...-ghc-7.10.1/bin/ghc "-B$NIX_GHC_LIBDIR" "$@"
224The variables `$NIX_GHC`, `$NIX_GHCPKG`, etc. point to the *new* store path
225`ghcWithPackages` constructed specifically for this environment. The last line
226of the wrapper script then executes the real `ghc`, but passes the path to the
227new `lib` directory using GHC's `-B` flag.
229The purpose of those environment variables is to work around an impurity in the
230popular [ghc-paths](http://hackage.haskell.org/package/ghc-paths) library. That
231library promises to give its users access to GHC's installation paths. Only,
232the library can't possible know that path when it's compiled, because the path
233GHC considers its own is determined only much later, when the user configures
234it through `ghcWithPackages`. So we [patched
235ghc-paths](https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/haskell-modules/ghc-paths-nix.patch)
236to return the paths found in those environment variables at run-time rather
237than trying to guess them at compile-time.
239To make sure that mechanism works properly all the time, we recommend that you
240set those variables to meaningful values in your shell environment, too, i.e.
241by adding the following code to your `~/.bashrc`:
243 if type >/dev/null 2>&1 -p ghc; then
244 eval "$(egrep ^export "$(type -p ghc)")"
247If you are certain that you'll use only one GHC environment which is located in
248your user profile, then you can use the following code, too, which has the
249advantage that it doesn't contain any paths from the Nix store, i.e. those
250settings always remain valid even if a `nix-env -u` operation updates the GHC
251environment in your profile:
253 if [ -e ~/.nix-profile/bin/ghc ]; then
254 export NIX_GHC="$HOME/.nix-profile/bin/ghc"
255 export NIX_GHCPKG="$HOME/.nix-profile/bin/ghc-pkg"
256 export NIX_GHC_DOCDIR="$HOME/.nix-profile/share/doc/ghc/html"
257 export NIX_GHC_LIBDIR="$HOME/.nix-profile/lib/ghc-$($NIX_GHC --numeric-version)"
260## How to create ad hoc environments for `nix-shell`
262The easiest way to create an ad hoc development environment is to run
263`nix-shell` with the appropriate GHC environment given on the command-line:
265 nix-shell -p "haskellPackages.ghcWithPackages (pkgs: with pkgs; [mtl pandoc])"
267For more sophisticated use-cases, however, it's more convenient to save the
268desired configuration in a file called `shell.nix` that looks like this:
270 { nixpkgs ? import <nixpkgs> {}, compiler ? "ghc7101" }:
272 inherit (nixpkgs) pkgs;
273 ghc = pkgs.haskell.packages.${compiler}.ghcWithPackages (ps: with ps; [
277 pkgs.stdenv.mkDerivation {
278 name = "my-haskell-env-0";
279 buildInputs = [ ghc ];
280 shellHook = "eval $(egrep ^export ${ghc}/bin/ghc)";
283Now run `nix-shell` --- or even `nix-shell --pure` --- to enter a shell
284environment that has the appropriate compiler in `$PATH`. If you use `--pure`,
285then add all other packages that your development environment needs into the
286`buildInputs` attribute. If you'd like to switch to a different compiler
287version, then pass an appropriate `compiler` argument to the expression, i.e.
288`nix-shell --argstr compiler ghc784`.
290If you need such an environment because you'd like to compile a Hackage package
291outside of Nix --- i.e. because you're hacking on the latest version from Git
292---, then the package set provides suitable nix-shell environments for you
293already! Every Haskell package has an `env` attribute that provides a shell
294environment suitable for compiling that particular package. If you'd like to
295hack the `lens` library, for example, then you just have to check out the
296source code and enter the appropriate environment:
298 $ cabal get lens-4.11 && cd lens-4.11
299 Downloading lens-4.11...
300 Unpacking to lens-4.11/
302 $ nix-shell "<nixpkgs>" -A haskellPackages.lens.env
303 [nix-shell:/tmp/lens-4.11]$
305At point, you can run `cabal configure`, `cabal build`, and all the other
306development commands. Note that you need `cabal-install` installed in your
307`$PATH` already to use it here --- the `nix-shell` environment does not provide
310# How to create Nix builds for your own private Haskell packages
312If your own Haskell packages have build instructions for Cabal, then you can
313convert those automatically into build instructions for Nix using the
314`cabal2nix` utility, which you can install into your profile by running
315`nix-env -i cabal2nix`.
317## How to build a stand-alone project
319For example, let's assume that you're working on a private project called
320`foo`. To generate a Nix build expression for it, change into the project's
321top-level directory and run the command:
323 $ cabal2nix . >foo.nix
325Then write the following snippet into a file called `default.nix`:
327 { nixpkgs ? import <nixpkgs> {}, compiler ? "ghc7101" }:
328 nixpkgs.pkgs.haskell.packages.${compiler}.callPackage ./foo.nix { }
330Finally, store the following code in a file called `shell.nix`:
332 { nixpkgs ? import <nixpkgs> {}, compiler ? "ghc7101" }:
333 (import ./default.nix { inherit nixpkgs compiler; }).env
335At this point, you can run `nix-build` to have Nix compile your project and
336install it into a Nix store path. The local directory will contain a symlink
337called `result` after `nix-build` returns that points into that location. Of
338course, passing the flag `--argstr compiler ghc763` allows switching the build
339to any version of GHC currently supported.
341Furthermore, you can call `nix-shell` to enter an interactive development
342environment in which you can use `cabal configure` and `cabal build` to develop
343your code. That environment will automatically contain a proper GHC derivation
344with all the required libraries registered as well as all the system-level
345libraries your package might need.
347If your package does not depend on any system-level libraries, then it's
350 $ nix-shell --command "cabal configure"
352once to set up your build. `cabal-install` determines the absolute paths to all
353resources required for the build and writes them into a config file in the
354`dist/` directory. Once that's done, you can run `cabal build` and any other
355command for that project even outside of the `nix-shell` environment. This
356feature is particularly nice for those of us who like to edit their code with
357an IDE, like Emacs' `haskell-mode`, because it's not necessary to start Emacs
358inside of nix-shell just to make it find out the necessary settings for
359building the project; `cabal-install` has already done that for us.
361If you want to do some quick-and-dirty hacking and don't want to bother setting
362up a `default.nix` and `shell.nix` file manually, then you can use the
363`--shell` flag offered by `cabal2nix` to have it generate a stand-alone
364`nix-shell` environment for you. With that feature, running
366 $ cabal2nix --shell . >shell.nix
367 $ nix-shell --command "cabal configure"
369is usually enough to set up a build environment for any given Haskell package.
370You can even use that generated file to run `nix-build`, too:
372 $ nix-build shell.nix
374## How to build projects that depend on each other
376If you have multiple private Haskell packages that depend on each other, then
377you'll have to register those packages in the Nixpkgs set to make them visible
378for the dependency resolution performed by `callPackage`. First of all, change
379into each of your projects top-level directories and generate a `default.nix`
380file with `cabal2nix`:
382 $ cd ~/src/foo && cabal2nix . >default.nix
383 $ cd ~/src/bar && cabal2nix . >default.nix
385Then edit your `~/.nixpkgs/config.nix` file to register those builds in the
386default Haskell package set:
389 packageOverrides = super: let self = super.pkgs; in
391 haskellPackages = super.haskellPackages.override {
392 overrides = self: super: {
393 foo = self.callPackage ../src/foo {};
394 bar = self.callPackage ../src/bar {};
400Once that's accomplished, `nix-env -f "<nixpkgs>" -qA haskellPackages` will
401show your packages like any other package from Hackage, and you can build them
403 $ nix-build "<nixpkgs>" -A haskellPackages.foo
405or enter an interactive shell environment suitable for building them:
407 $ nix-shell "<nixpkgs>" -A haskellPackages.bar.env
409# Miscellaneous Topics
411## How to build with profiling enabled
413Every Haskell package set takes a function called `overrides` that you can use
414to manipulate the package as much as you please. One useful application of this
415feature is to replace the default `mkDerivation` function with one that enables
416library profiling for all packages. To accomplish that, add configure the
417following snippet in your `~/.nixpkgs/config.nix` file:
420 packageOverrides = super: let self = super.pkgs; in
422 profiledHaskellPackages = self.haskellPackages.override {
423 overrides = self: super: {
424 mkDerivation = args: super.mkDerivation (args // {
425 enableLibraryProfiling = true;
432## How to override package versions in a compiler-specific package set
434Nixpkgs provides the latest version of
435[`ghc-events`](http://hackage.haskell.org/package/ghc-events), which is 0.4.4.0
436at the time of this writing. This is fine for users of GHC 7.10.x, but GHC
4377.8.4 cannot compile that binary. Now, one way to solve that problem is to
438register an older version of `ghc-events` in the 7.8.x-specific package set.
439The first step is to generate Nix build instructions with `cabal2nix`:
441 $ cabal2nix cabal://ghc-events-0.4.3.0 >~/.nixpkgs/ghc-events-0.4.3.0.nix
443Then add the override in `~/.nixpkgs/config.nix`:
446 packageOverrides = super: let self = super.pkgs; in
448 haskell = super.haskell // {
449 packages = super.haskell.packages // {
450 ghc784 = super.haskell.packages.ghc784.override {
451 overrides = self: super: {
452 ghc-events = self.callPackage ./ghc-events-0.4.3.0.nix {};
460This code is a little crazy, no doubt, but it's necessary because the intuitive
463 haskell.packages.ghc784 = super.haskell.packages.ghc784.override {
464 overrides = self: super: {
465 ghc-events = self.callPackage ./ghc-events-0.4.3.0.nix {};
469doesn't do what we want it to: that code replaces the `haskell` package set in
470Nixpkgs with one that contains only one entry,`packages`, which contains only
471one entry `ghc784`. This override loses the `haskell.compiler` set, and it
472loses the `haskell.packages.ghcXYZ` sets for all compilers but GHC 7.8.4. To
473avoid that problem, we have to perform the convoluted little dance from above,
474iterating over each step in hierarchy.
476Once it's accomplished, however, we can install a variant of `ghc-events`
477that's compiled with GHC 7.8.4:
479 nix-env -f "<nixpkgs>" -iA haskell.packages.ghc784.ghc-events
481Unfortunately, it turns out that this build fails again while executing the
482test suite! Apparently, the release archive on Hackage is missing some data
483files that the test suite requires, so we cannot run it. We accomplish that by
484re-generating the Nix expression with the `--no-check` flag:
486 $ cabal2nix --no-check cabal://ghc-events-0.4.3.0 >~/.nixpkgs/ghc-events-0.4.3.0.nix
488Now the builds succeeds.
490Of course, in the concrete example of `ghc-events` this whole exercise is not
491an ideal solution, because `ghc-events` can analyze the output emitted by any
492version of GHC later than 6.12 regardless of the compiler version that was used
493to build the `ghc-events' executable, so strictly speaking there's no reason to
494prefer one built with GHC 7.8.x in the first place. However, for users who
495cannot use GHC 7.10.x at all for some reason, the approach of downgrading to an
496older version might be useful.
498## How to recover from GHC's infamous non-deterministic library ID bug
500GHC and distributed build farms don't get along well:
502 https://ghc.haskell.org/trac/ghc/ticket/4012
504When you see an error like this one
506 package foo-0.7.1.0 is broken due to missing package
507 text-1.2.0.4-98506efb1b9ada233bb5c2b2db516d91
509then you have to download and re-install `foo` and all its dependents from
512 # nix-store -q --referrers /nix/store/*-haskell-text-1.2.0.4 \
513 | nix-store --repair-path --option binary-caches http://hydra.nixos.org
515If you're using additional Hydra servers other than `hydra.nixos.org`, then it
516might be necessary to purge the local caches that store data from those
517machines to disable these binary channels for the duration of the previous
518command, i.e. by running:
520 rm /nix/var/nix/binary-cache-v3.sqlite
521 rm /nix/var/nix/manifests/*
522 rm /nix/var/nix/channel-cache/*
524## Builds on Darwin fail with `math.h` not found
526Users of GHC on Darwin have occasionally reported that builds fail, because the
527compiler complains about a missing include file:
529 fatal error: 'math.h' file not found
531The issue has been discussed at length in [ticket
5326390](https://github.com/NixOS/nixpkgs/issues/6390), and so far no good
533solution has been proposed. As a work-around, users who run into this problem
534can configure the environment variables
536 export NIX_CFLAGS_COMPILE="-idirafter /usr/include"
537 export NIX_CFLAGS_LINK="-L/usr/lib"
539in their `~/.bashrc` file to avoid the compiler error.
543- The Youtube video [Nix Loves Haskell](https://www.youtube.com/watch?v=BsBhi_r-OeE)
544 provides an introduction into Haskell NG aimed at beginners. The slides are
545 available at http://cryp.to/nixos-meetup-3-slides.pdf and also -- in a form
546 ready for cut & paste -- at
547 https://github.com/NixOS/cabal2nix/blob/master/doc/nixos-meetup-3-slides.md.
549- Another Youtube video is [Escaping Cabal Hell with Nix](https://www.youtube.com/watch?v=mQd3s57n_2Y),
550 which discusses the subject of Haskell development with Nix but also provides
551 a basic introduction to Nix as well, i.e. it's suitable for viewers with
552 almost no prior Nix experience.
554- Oliver Charles wrote a very nice [Tutorial how to develop Haskell packages with Nix](http://wiki.ocharles.org.uk/Nix).
556- The *Journey into the Haskell NG infrastructure* series of postings
557 describe the new Haskell infrastructure in great detail:
559 - [Part 1](http://lists.science.uu.nl/pipermail/nix-dev/2015-January/015591.html)
560 explains the differences between the old and the new code and gives
561 instructions how to migrate to the new setup.
563 - [Part 2](http://lists.science.uu.nl/pipermail/nix-dev/2015-January/015608.html)
564 looks in-depth at how to tweak and configure your setup by means of
567 - [Part 3](http://lists.science.uu.nl/pipermail/nix-dev/2015-April/016912.html)
568 describes the infrastructure that keeps the Haskell package set in Nixpkgs
keysesc to close
- j k
- move down, up
- enter
- open
- esc
- back, or up a level
- 1 2 3 4
- readme, files, commits, refs
- /
- filter
- y
- copy the clone command
- c
- compare the chosen commit with another (or shift-click both)
- ?
- show or hide this list