Nix Anti-Patterns

40 recurring Nix mistakes that quietly cost teams time and money, and what to do instead.

Nix rewards teams that use it well and punishes the ones that don't. The costly mistakes rarely look dangerous: An unfiltered src works but leads to countless rebuilds and cache misses. A sleep in a NixOS test mostly works but then fails in the CI if it's under heavy load. Overrides work well at first, but then break after the next update and produce a lot of work. Anti-patterns get copied from repository to repository faster than your seniors can review them, and every copy means pointless rebuilds, fewer cache hits, and the same support questions all over again. This book shows you how to spot them and how to fix them for good.

Why recipes?

This book takes its format from Herb Sutter's Exceptional C++ series. Few developers read programming books cover to cover, but those books got read, because each short item gives a common mistake a name. You skim through, spot the pattern, and wonder whether it's hiding in your own code. Nobody wants to be caught red-handed with a pattern that has a name. Nix Anti-Patterns brings that idea to Nix.

What's inside

• 40 anti-patterns in 8 chapters: Nix language idioms, evaluation purity, building software with Nixpkgs, overriding packages, overlays, flakes, NixOS modules, and NixOS tests.
• Before and after, side by side. Every anti-pattern shows the problematic code next to the better version, then explains what goes wrong and why the fix is better.
• Short enough to actually read. 93 pages, one focused recipe at a time. Read one over coffee, apply it the same afternoon.
• Distilled from real codebases. Since 2023, our Nixcademy trainings have helped companies adopt Nix from Germany to Singapore and across the US. These are the mistakes we see over and over again.

Who it's for

• Developers who know the Nix basics and want their code to hold up in a growing team
• Senior engineers and reviewers who want one reference to point colleagues to, instead of explaining the same fix for the tenth time
• Teams adopting Nix that want to stop the pitfalls before they spread

This is not an introduction to Nix: It assumes you can read and write basic Nix expressions. If you're just starting out, begin with our video courses.

Table of contents

• Nix language idioms
  • Minimize with scopes
  • Avoid @ patterns
  • Avoid // on nested attribute set updates
  • Reuse variables explicitly without rec
• Evaluation purity
  • Pin expression sources explicitly
  • Evaluate Nixpkgs with explicit configuration
  • Import Nixpkgs at one central place
• Building software with Nixpkgs
  • Always filter src attributes
  • Remember to set doCheck
  • Declare environment variables explicitly
  • Also use pname when using version
  • Changing makeFlagsArray correctly
  • Keep derivations ready for cross-compilation
  • Use specialized flags instead of phase overrides
  • Use substituteInPlace for safer string substitution
  • Derive dev shells from packages with inputsFrom
• Overriding packages
  • Write future proof overrideAttrs
  • Use override for inputs, overrideAttrs for attributes
  • Expose feature flags as function arguments
  • Avoid pkgs in callPackage
  • Keep Python packages composable
  • Use finalAttrs instead of rec or let in
  • Leave hooks when overriding phases
• Nixpkgs overlays
  • Overlay nested attributes correctly
  • Use overrideScope to extend package scopes
  • Keep package overrides composable
• Flakes
  • Derive default systems from legacyPackages
  • Define Flake packages via an overlay
  • Avoid helper flakes for system boilerplate
• NixOS modules
  • Parametrize modules with options
  • Avoid specialArgs for better composability
  • Import modules by path
• NixOS tests
  • Separate host and guest packages
  • Double check service units and open ports
  • Always set timeouts
  • Fail fast when KVM is unavailable
  • Start independent work on all nodes before waiting
  • Use the t.assert* helpers instead of plain assert
  • Share node configuration with defaults
  • Wait for conditions instead of sleeping

About the authors

Written by Jacek Galowicz, active in the NixOS community since 2016, CEO of Applicative Systems Group/Nixcademy, and author of the C++17 STL Cookbook. He writes regularly for heise online and c't magazine and teaches software development to university students. Technical editing by Valentin Gagarin, founding member of the Nix documentation team.

Written by humans

Every word in this book is written by people who use Nix every day. We use Grammarly to fix language mistakes, and LLMs only to cross-check the text for contradictions with the official documentation.

DRM-free PDF, with every future update included. Not sure yet? The free sample contains a few complete anti-pattern recipes.