Language cheatsheet

Every nix block on this page parses with nix-instantiate --parse. Outputs shown were produced by nix eval --expr on Nix 2.35.2. In fish, wrap expressions in single quotes.

Literals

builtins.typeOf returns the type name. 7 / 2 is 3; 7.0 / 2 is 3.5.

Strings

let name = "nix"; n = 3; in [
  "hi ${name}"
  "count: ${toString n}"
  "tab\tnewline\n"
  ''
    indented
      keeps relative indent
  ''
  ("a" + "b")
]

[ "hi nix" "count: 3" "tab\tnewline\n" "indented\n  keeps relative indent\n" "ab" ]

Interpolation needs a string; ${3} fails with cannot coerce an integer to a string. Inside ''...'', escape ${ as ''${ and '' as '''.

Paths

[ ./foo (./foo + "bar") (builtins.typeOf ./foo) ]

[ /tmp/foo /tmp/foobar "path" ]

Relative to the file, or to cwd under --expr (run from /tmp here). A path interpolated into a string is copied to the store. ./foo + ./bar is /tmp/foo/tmp/bar, not a join.

Lists

[ ([ 1 2 ] ++ [ 3 ]) (builtins.elemAt [ 10 20 ] 1) (builtins.length [ ]) (map (x: x * 2) [ 1 2 ]) ]

[ [ 1 2 3 ] 20 0 [ 2 4 ] ]

Space-separated. Commas are a syntax error. Parenthesise any expression that is not a single token: [ (f x) (1 + 2) ].

Attrsets

let s = { a = 1; b.c = 2; "quoted key" = 3; ${"dyn" + "amic"} = 4; }; in
[ s.a s.b.c (s ? a) (s.z or "fallback") (builtins.attrNames s) ]

[ 1 2 true "fallback" [ "a" "b" "dynamic" "quoted key" ] ]

Duplicate keys are an error. attrNames is sorted. s.b.c = 2; nests automatically.

rec

rec { a = 1; b = a + 1; }

{ a = 1; b = 2; }

Without rec, b = a + 1 is undefined variable 'a'. A cycle is infinite recursion encountered.

let

let
  a = 1;
  b = a + 1;
  inherit (builtins) toString;
in
toString (a + b)

"3"

Bindings see each other regardless of order. Inner let shadows outer.

with

let a = 100; s = { a = 1; b = 2; }; in with s; [ a b ]

[ 100 2 ]

with has the lowest priority: a stays 100 from the let. Use for short package lists only.

inherit

let x = 1; y = 2; pkgs = { nodejs = "n"; pnpm = "p"; }; in
{ inherit x y; inherit (pkgs) nodejs; }

{ nodejs = "n"; x = 1; y = 2; }

inherit x; is x = x;. inherit (s) x; is x = s.x;. Works in let too.

Functions

let
  inc = x: x + 1;
  add = a: b: a + b;
  f = { a, b ? 10, ... }@args: a + b + builtins.length (builtins.attrNames args);
in
[ (inc 1) (add 1 2) ((add 1) 2) (f { a = 1; }) (f { a = 1; b = 1; z = 0; }) ]

[ 2 3 3 12 5 ]

Application binds tightest and is left-associative: f a b is (f a) b; toString 1 + 2 is (toString 1) + 2.

if, assert

let x = 5; in [
  (if x > 3 then "big" else "small")
  (assert x == 5; "asserted")
]

[ "big" "asserted" ]

if needs a real boolean and always has an else. assert cond; body throws if cond is false. assert 1 == 2; "ok" reports an integer with value '1' is not equal to an integer with value '2'.

Operators

[
  ({ x = { a = 1; }; } // { x = { b = 2; }; })
  ({ a = 1; } ? b)
  ({ a = 1; }.b or "none")
  (true -> false)
]

[ { x = { b = 2; }; } false "none" false ]

// replaces nested sets wholesale. lib.recursiveUpdate merges deeply.

import

{ name, greeting ? "Hello" }:
"${greeting}, ${name}!"

Saved as greet.nix. import ./greet.nix returns the function; import ./greet.nix { name = "Dave"; } returns "Hello, Dave!". A file holds exactly one expression. import of a directory reads its default.nix. Under --expr, relative imports need --impure; prefer nix eval -f greet.nix --apply 'f: f { name = "Dave"; }'.

Laziness

let unused = throw "never"; s = { bad = throw "boom"; ok = 1; }; in
[ s.ok (builtins.length [ (throw "x") ]) (builtins.seq s 2) ]

[ 1 1 2 ]

Nothing is evaluated until forced. builtins.seq a b forces a shallowly; builtins.deepSeq forces recursively. builtins.tryEval (throw "x") is { success = false; value = false; }.

Builtins used daily

builtins.currentSystem is unavailable in pure mode, which is every flake.

lib used daily

Available as pkgs.lib or nixpkgs.lib. Signatures from the lib source doc comments.

Find anything else at noogle.dev, or builtins.unsafeGetAttrPos "name" lib.attrsets to jump to the source line.

Comments

# line comment
1 /* block
comment */ + 1

2