Haskell World logo Haskell WorldWrite code, build worlds
Developer Tools

Nix Flakes for a Haskell Dev Setup That Stays Put

A student wrote to me at eleven at night in week three of the semester because cabal build failed on a project that had compiled fine in the lab two hours earlier.

A terminal running a Nix development shell beside an editor showing a flake file and a Haskell module

A student wrote to me at eleven at night in week three of the semester because cabal build failed on a project that had compiled fine in the lab two hours earlier. She had GHC 9.8 from her distribution package manager, the assignment expected 9.4, and the error that came out of the solver complained about a constraint on base instead of saying anything about compiler versions. We spent forty minutes narrowing it down. The fix was one line. The diagnosis was everything else.

That evening is the whole argument for putting a Nix flake in a Haskell repository, and it has little to do with Nix being pleasant to write. A flake records which compiler, which cabal, which language server, and which system libraries the project needs, in one file that travels with the code. Anyone who runs nix develop lands in that exact set. The price is honest: a slow first run, an unfamiliar language to read, and a couple of sharp edges around editors. What follows is the smallest flake that earns its keep, plus the cases where I tell people to leave it alone.

What breaks when the toolchain is not written down

Three failures account for nearly every one of these emails I get. None of them announce themselves clearly.

The first is a compiler mismatch, like the one above. Cabal does not say "you are on the wrong GHC". It says it cannot find a version of some library that satisfies all constraints, and the library it names is usually innocent. If a project has a cabal.project.freeze file generated under 9.4.8, running it under 9.8 produces a page of text that reads like a broken dependency rather than a broken environment.

The second is system libraries. A package that binds to zlib, libpq, or OpenSSL fails at link time with a missing header, and the message points at a C file nobody in the team has opened. On one machine the header is there because someone installed a database client last year. On a fresh laptop it is not. I have watched three people chase the same zlib header in the same week.

The third is the language server. Haskell Language Server binaries are built per GHC version, and 9.4.7 and 9.4.8 are different builds. Install a mismatched one and the editor does not crash, it simply stops showing types, which beginners read as "Haskell tooling is bad" rather than "one version number is off". If you have hit that wall before, the walkthrough on language server troubleshooting covers the symptoms in more detail.

The smallest flake that does the job

You do not need to build the package with Nix to get the benefit. You only need a development shell. A file named flake.nix in the repository root with roughly this shape is enough:

inputs.nixpkgs.url = "github:NixOS/nixpkgs/nixos-25.05";

outputs = { self, nixpkgs }: let system = "x86_64-linux"; pkgs = import nixpkgs { inherit system; }; hp = pkgs.haskell.packages.ghc984; in {

devShells.${system}.default = pkgs.mkShell { packages = [ hp.ghc pkgs.cabal-install hp.haskell-language-server pkgs.pkg-config pkgs.zlib ]; };

};

Two details carry most of the value. Pinning the nixpkgs input to a dated release branch rather than nixos-unstable means the compiler does not change under you in the middle of term. Taking the language server from the same hp attribute set as the compiler means the two cannot drift apart, which removes the third failure above by construction.

Then run nix develop. On a laptop over home broadband, the first run pulls somewhere between 1.5 and 3 GB and takes four to twenty five minutes. Every run after that is a couple of seconds. Inside the shell, cabal build, cabal repl, and your editor behave exactly as they always did.

The one choice that decides whether you wait minutes or hours

Here is the trap that sours people on this approach, and it is a single line in the flake. Pick a GHC attribute that the pinned nixpkgs release treats as its default Haskell compiler, and nearly everything comes prebuilt from the public binary cache. Pick a different minor version, and nixpkgs has no cached language server for it, so Nix cheerfully starts compiling HLS from source. On a four core machine that is forty minutes to well over an hour, with a fan noise that convinces the owner something has gone badly wrong.

Check before you commit. Ask for the compiler alone first, see how long it takes, then add the language server and watch whether Nix reports that it is fetching or building. If the word "building" appears next to haskell-language-server, change the attribute to the release default and try again. I lost an afternoon to this in February before I learned to read that output.

Where the common Nix advice goes wrong

The standard recommendation on forums is to go further: build the package itself with Nix too, using a derivation generated from the cabal file, so that development and continuous integration use byte identical inputs. For a company with twenty engineers and a release pipeline, that is defensible. For a two person side project or a classroom repository, it is the wrong trade.

The reason is the inner loop. Once Nix owns the build, adding a dependency means regenerating a derivation and letting Nix rebuild the dependency closure, where cabal would have resolved it in seconds and compiled only what changed. People who do this to a teaching repository end up with students waiting on a rebuild to try one new library, and the lesson they take away is that Haskell is slow to work with. Keep Nix responsible for the shell and keep cabal responsible for the build. If your builds are the bottleneck instead, the fixes in speeding up cabal builds address that directly and cost nothing.

The second piece of advice to resist is that a flake lets you delete your other installers. It does not, because Nix on Windows needs WSL. If one teammate is on native Windows, the flake becomes a second path to maintain rather than the single source of truth, and you now own two setups instead of one.

How it compares with the alternatives

Rough numbers from setting up all three on the same mid range laptop, repeated across two class groups:

ApproachFirst setupRepeat on new machinePins C librariesNative Windows
GHCup only10 to 15 min10 to 15 min, manualNoYes
Nix flake dev shell5 to 25 minOne commandYesWSL only
Dev container15 to 30 minOne commandYesYes, with Docker

The column that matters for a team is the second one, not the first. A fifteen minute manual setup done by eleven people, half of whom make a different mistake, costs more than one slow download.

An afternoon of work, in order

Start by writing down what you have now: run ghc -V and cabal -V on the machine where the project builds, and note the exact numbers. Add the flake with those versions, commit it, and ask the person whose machine is most broken to run nix develop and then the test suite. Their failure is the useful one.

Next, add direnv with a one line .envrc containing use flake, so entering the directory activates the shell without anyone remembering a command. Put .direnv in your gitignore. Finally, write three lines in the README saying what to install and what to run, because a flake nobody knows about helps nobody. Our class repository has exactly that, and the late night emails about version errors dropped to roughly one a term. Other tooling writeups sit in the developer tools section if you want to keep going.

FAQ

Do I need to understand the Nix language to use a flake?

To copy and adjust the shell above, no. You need to recognise attribute sets and lists, which is maybe twenty minutes of reading. Writing package derivations is a much larger commitment, and the shell gives you most of the payoff without it.

Can I still use GHCup for other projects?

Yes, and I do. GHCup manages the compilers on my PATH for scratch work, and the flake takes over inside project directories. They do not fight, as long as you remember which shell you are in when a version looks wrong.

Does this replace a freeze file?

No, and the two solve different halves of the problem. The flake pins the compiler and the C libraries. A cabal.project.freeze file pins your Haskell dependency versions. Use both, and regenerate the freeze file whenever you change the compiler.

What about stack users?

Stack already pins package versions through its resolver, so the flake adds mainly the system libraries and the language server. The overlap is real, which is part of the tradeoff discussed in stack versus cabal.

AS
Adil Sato

Adil Sato teaches programming concepts at a community college and writes online guides for the questions students ask most in the second week of class, not the first. His focus is on making type systems, monads, and functional patterns understandable without reducing them to metaphors that break down the moment you try to use them for real work.

More posts by Adil

More in Developer Tools

01doorganico 084goad 3hot8 4465456 after5internprogram ahandfulofblessings ahmadpc ahomcybersecurity allodialresources annodex antiquesandperiodcollectibles aotc asianworldkashmir beedlectrics bloggertemplatefree bluefeatheragency bodyweightsolution campaign08blog carfixadvisor catstreetcollective cbstvsports cnfanspurchasing committeeof500yearsofdignityandresistance covertopsdjs cs-kaiyuangame cuestacomunicaciontotal cxoutlet dancebetgame deskgearhub destinyvillastay detectmagazine di33 diamondsteelbuildings donmo dyanadropship emarsysfinance emimattl escapechan eskitarih evautoplay everythingweddings-orlando farmzone feedviewerapp foxstudiosscratch gamevui123 gleasongrade greetingsday hacklabasu iw-kaiyun jagoanproperti jilidskripsi joltbusinessfinance juegodepokergratis juegospucca kaeru-festival latestmehndidesigns lestanzediottaviano litemagazines localcommunityhero lustrsazan mariashebets menswheels newwebstechs1 nikkit ootheday oxigenvpn plurfitness prefetial probudgetcarpetcleaning psychicmrsmartin pyaten qvantor rejoignezlogis rexzbot riselayouts ruchin rwxqsgd5 sakaltime shibiaowang shop-bot skrtips spotlesshaven strcoding tetapatrium topselller uneplanteartificielle vipertechcr webtech1223411 wo-kygaming yamaha-mekar yeknava yoybuysheets zenunwa yamaha-mekar jilidskripsi ankertoto ankertoto ankertoto