Nix Language

The Nix language is designed for conveniently creating and composing derivations – precise descriptions of how contents of existing files are used to derive new files.

Tip

These pages are written as a reference. If you are learning Nix, nix.dev has a good introduction to the Nix language.

The language is:

• domain-specific

  The Nix language is purpose-built for working with text files. Its most characteristic features are:

  • File system path primitives, for accessing source files
  • Indented strings and string interpolation, for creating file contents
  • Strings with contexts, for transparently linking files

  It comes with built-in functions to integrate with the Nix store, which manages files and enables realising derivations declared in the Nix language.

• declarative

  There is no notion of executing sequential steps. Dependencies between operations are established only through data.

• pure

  Values cannot change during computation. Functions always produce the same output if their input does not change.

• functional

  Functions are like any other value. Functions can be assigned to names, taken as arguments, or returned by functions.

• lazy

  Values are only computed when they are needed.

• dynamically typed

  Type errors are only detected when expressions are evaluated.

Overview

This is an incomplete overview of language features, by example.

Basic values (primitives)

"hello world"

A string

''
  multi
   line
    string
''

A multi-line string. Strips common prefixed whitespace. Evaluates to "multi\n line\n  string".

# Explanation

A comment.

"hello ${ { a = "world"; }.a }"

"1 2 ${toString 3}"

"${pkgs.bash}/bin/sh"

String interpolation (expands to "hello world", "1 2 3", "/nix/store/<hash>-bash-<version>/bin/sh")

true, false

Booleans

null

Null value

123

An integer

3.141

A floating point number

/etc

An absolute path

./foo.png

A path relative to the file containing this Nix expression

~/.config

A home path. Evaluates to the "<user's home directory>/.config".

<nixpkgs>

A lookup path for Nix files. Value determined by $NIX_PATH environment variable.

Compound values

{ x = 1; y = 2; }

An attribute set with attributes named x and y

{ foo.bar = 1; }

A nested set, equivalent to { foo = { bar = 1; }; }

rec { x = "foo"; y = x + "bar"; }

A recursive set, equivalent to { x = "foo"; y = "foobar"; }.

[ "foo" "bar" "baz" ]

[ 1 2 3 ]

[ (f 1) { a = 1; b = 2; } [ "c" ] ]

Lists with three elements.

Operators

"foo" + "bar"

String concatenation

1 + 2

Integer addition

"foo" == "f" + "oo"

Equality test (evaluates to true)

"foo" != "bar"

Inequality test (evaluates to true)

!true

Boolean negation

{ x = 1; y = 2; }.x

Attribute selection (evaluates to 1)

{ x = 1; y = 2; }.z or 3

Attribute selection with default (evaluates to 3)

{ x = 1; y = 2; } // { z = 3; }

Merge two sets (attributes in the right-hand set taking precedence)

Control structures

if 1 + 1 == 2 then "yes!" else "no!"

Conditional expression.

assert 1 + 1 == 2; "yes!"

Assertion check (evaluates to "yes!").

let x = "foo"; y = "bar"; in x + y

Variable definition. See let-expressions.

with builtins; head [ 1 2 3 ]

Add all attributes from the given set to the scope (evaluates to 1).

See with-expressions for details and shadowing caveats.

inherit pkgs src;

Adds the variables to the current scope (attribute set or let binding). Desugars to pkgs = pkgs; src = src;. See Inheriting attributes.

inherit (pkgs) lib stdenv;

Adds the attributes, from the attribute set in parentheses, to the current scope (attribute set or let binding). Desugars to lib = pkgs.lib; stdenv = pkgs.stdenv;. See Inheriting attributes.

Functions (lambdas)

x: x + 1

A function that expects an integer and returns it increased by 1.

x: y: x + y

Curried function, equivalent to x: (y: x + y). Can be used like a function that takes two arguments and returns their sum.

(x: x + 1) 100

A function call (evaluates to 101)

let inc = x: x + 1; in inc (inc (inc 100))

A function bound to a variable and subsequently called by name (evaluates to 103)

{ x, y }: x + y

A function that expects a set with required attributes x and y and concatenates them

{ x, y ? "bar" }: x + y

A function that expects a set with required attribute x and optional y, using "bar" as default value for y

{ x, y, ... }: x + y

A function that expects a set with required attributes x and y and ignores any other attributes

{ x, y } @ args: x + y

args @ { x, y }: x + y

A function that expects a set with required attributes x and y, and binds the whole set to args

Built-in functions

import ./foo.nix

Load and return Nix expression in given file. See import.

map (x: x + x) [ 1 2 3 ]

Apply a function to every element of a list (evaluates to [ 2 4 6 ]). See map.