This section lists the functions and constants built into the Nix expression evaluator. (The built-in function derivation is discussed above.) Some built-ins, such as derivation, are always in scope of every Nix expression; you can just access them right away. But to prevent polluting the namespace too much, most built-ins are not in scope. Instead, you can access them through the builtins built-in value, which is a set that contains all built-in functions and values. For instance, derivation is also available as builtins.derivation. abort s Abort Nix expression evaluation, print error message s. builtins.add e1 e2 Return the sum of the numbers e1 and e2. builtins.all pred list Return true if the function pred returns true for all elements of list, and false otherwise. builtins.any pred list Return true if the function pred returns true for at least one element of list, and false otherwise. builtins.attrNames set Return the names of the attributes in the set set in a sorted list. For instance, builtins.attrNames { y = 1; x = "foo"; } evaluates to [ "x" "y" ]. builtins.attrValues set Return the values of the attributes in the set set in the order corresponding to the sorted attribute names. baseNameOf s Return the base name of the string s, that is, everything following the final slash in the string. This is similar to the GNU basename command. builtins The set builtins contains all the built-in functions and values. You can use builtins to test for the availability of features in the Nix installation, e.g., if builtins ? getEnv then builtins.getEnv "PATH" else "" This allows a Nix expression to fall back gracefully on older Nix installations that don’t have the desired built-in function. builtins.compareVersions s1 s2 Compare two strings representing versions and return -1 if version s1 is older than version s2, 0 if they are the same, and 1 if s1 is newer than s2. The version comparison algorithm is the same as the one used by nix-env -u. builtins.concatLists lists Concatenate a list of lists into a single list. builtins.currentSystem The built-in value currentSystem evaluates to the Nix platform identifier for the Nix installation on which the expression is being evaluated, such as "i686-linux" or "x86_64-darwin". builtins.deepSeq e1 e2 This is like seq e1 e2, except that e1 is evaluated deeply: if it’s a list or set, its elements or attributes are also evaluated recursively. derivation attrs derivation is described in . dirOf s Return the directory part of the string s, that is, everything before the final slash in the string. This is similar to the GNU dirname command. builtins.div e1 e2 Return the quotient of the numbers e1 and e2. builtins.elem x xs Return true if a value equal to x occurs in the list xs, and false otherwise. builtins.elemAt xs n Return element n from the list xs. Elements are counted starting from 0. A fatal error occurs in the index is out of bounds. builtins.fetchurl url Download the specified URL and return the path of the downloaded file. This function is not available if restricted evaluation mode is enabled. fetchTarball url Download the specified URL, unpack it and return the path of the unpacked tree. The file must be a tape archive (.tar) compressed with gzip, bzip2 or xz. The top-level path component of the files in the tarball is removed, so it is best if the tarball contains a single directory at top level. The typical use of the function is to obtain external Nix expression dependencies, such as a particular version of Nixpkgs, e.g. with import (fetchTarball https://github.com/NixOS/nixpkgs-channels/archive/nixos-14.12.tar.gz) {}; stdenv.mkDerivation { … } This function is not available if restricted evaluation mode is enabled. builtins.filter f xs Return a list consisting of the elements of xs for which the function f returns true. builtins.filterSource e1 e2 This function allows you to copy sources into the Nix store while filtering certain files. For instance, suppose that you want to use the directory source-dir as an input to a Nix expression, e.g. stdenv.mkDerivation { ... src = ./source-dir; } However, if source-dir is a Subversion working copy, then all those annoying .svn subdirectories will also be copied to the store. Worse, the contents of those directories may change a lot, causing lots of spurious rebuilds. With filterSource you can filter out the .svn directories: src = builtins.filterSource (path: type: type != "directory" || baseNameOf path != ".svn") ./source-dir; Thus, the first argument e1 must be a predicate function that is called for each regular file, directory or symlink in the source tree e2. If the function returns true, the file is copied to the Nix store, otherwise it is omitted. The function is called with two arguments. The first is the full path of the file. The second is a string that identifies the type of the file, which is either "regular", "directory", "symlink" or "unknown" (for other kinds of files such as device nodes or fifos — but note that those cannot be copied to the Nix store, so if the predicate returns true for them, the copy will fail). builtins.foldl’ op nul list Reduce a list by applying a binary operator, from left to right, e.g. foldl’ op nul [x0 x1 x2 ...] = op (op (op nul x0) x1) x2) .... The operator is applied strictly, i.e., its arguments are evaluated first. For example, foldl’ (x: y: x + y) 0 [1 2 3] evaluates to 6. builtins.functionArgs f Return a set containing the names of the formal arguments expected by the function f. The value of each attribute is a Boolean denoting whether the corresponding argument has a default value. For instance, functionArgs ({ x, y ? 123}: ...) = { x = false; y = true; }. "Formal argument" here refers to the attributes pattern-matched by the function. Plain lambdas are not included, e.g. functionArgs (x: ...) = { }. builtins.fromJSON e Convert a JSON string to a Nix value. For example, builtins.fromJSON ''{"x": [1, 2, 3], "y": null}'' returns the value { x = [ 1 2 3 ]; y = null; }. Floating point numbers are not supported. builtins.genList generator length Generate list of size length, with each element i> equal to the value returned by generator i. For example, builtins.genList (x: x * x) 5 returns the list [ 0 1 4 9 16 ]. builtins.getAttr s set getAttr returns the attribute named s from set. Evaluation aborts if the attribute doesn’t exist. This is a dynamic version of the . operator, since s is an expression rather than an identifier. builtins.getEnv s getEnv returns the value of the environment variable s, or an empty string if the variable doesn’t exist. This function should be used with care, as it can introduce all sorts of nasty environment dependencies in your Nix expression. getEnv is used in Nix Packages to locate the file ~/.nixpkgs/config.nix, which contains user-local settings for Nix Packages. (That is, it does a getEnv "HOME" to locate the user’s home directory.) builtins.hasAttr s set hasAttr returns true if set has an attribute named s, and false otherwise. This is a dynamic version of the ? operator, since s is an expression rather than an identifier. builtins.hashString type s Return a base-16 representation of the cryptographic hash of string s. The hash algorithm specified by type must be one of "md5", "sha1" or "sha256". builtins.head list Return the first element of a list; abort evaluation if the argument isn’t a list or is an empty list. You can test whether a list is empty by comparing it with []. import path Load, parse and return the Nix expression in the file path. If path is a directory, the file default.nix in that directory is loaded. Evaluation aborts if the file doesn’t exist or contains an incorrect Nix expression. import implements Nix’s module system: you can put any Nix expression (such as a set or a function) in a separate file, and use it from Nix expressions in other files. A Nix expression loaded by import must not contain any free variables (identifiers that are not defined in the Nix expression itself and are not built-in). Therefore, it cannot refer to variables that are in scope at the call site. For instance, if you have a calling expression rec { x = 123; y = import ./foo.nix; } then the following foo.nix will give an error: x + 456 since x is not in scope in foo.nix. If you want x to be available in foo.nix, you should pass it as a function argument: rec { x = 123; y = import ./foo.nix x; } and x: x + 456 (The function argument doesn’t have to be called x in foo.nix; any name would work.) builtins.intersectAttrs e1 e2 Return a set consisting of the attributes in the set e2 that also exist in the set e1. builtins.isAttrs e Return true if e evaluates to a set, and false otherwise. builtins.isList e Return true if e evaluates to a list, and false otherwise. builtins.isFunction e Return true if e evaluates to a function, and false otherwise. builtins.isString e Return true if e evaluates to a string, and false otherwise. builtins.isInt e Return true if e evaluates to an int, and false otherwise. builtins.isBool e Return true if e evaluates to a bool, and false otherwise. isNull e Return true if e evaluates to null, and false otherwise. This function is deprecated; just write e == null instead. builtins.length e Return the length of the list e. builtins.lessThan e1 e2 Return true if the number e1 is less than the number e2, and false otherwise. Evaluation aborts if either e1 or e2 does not evaluate to a number. builtins.listToAttrs e Construct a set from a list specifying the names and values of each attribute. Each element of the list should be a set consisting of a string-valued attribute name specifying the name of the attribute, and an attribute value specifying its value. Example: builtins.listToAttrs [ { name = "foo"; value = 123; } { name = "bar"; value = 456; } ] evaluates to { foo = 123; bar = 456; } map f list Apply the function f to each element in the list list. For example, map (x: "foo" + x) [ "bar" "bla" "abc" ] evaluates to [ "foobar" "foobla" "fooabc" ]. builtins.mul e1 e2 Return the product of the numbers e1 and e2. builtins.parseDrvName s Split the string s into a package name and version. The package name is everything up to but not including the first dash followed by a digit, and the version is everything following that dash. The result is returned in a set { name, version }. Thus, builtins.parseDrvName "nix-0.12pre12876" returns { name = "nix"; version = "0.12pre12876"; }. builtins.pathExists path Return true if the path path exists, and false otherwise. One application of this function is to conditionally include a Nix expression containing user configuration: let fileName = builtins.getEnv "CONFIG_FILE"; config = if fileName != "" && builtins.pathExists (builtins.toPath fileName) then import (builtins.toPath fileName) else { someSetting = false; }; # default configuration in config.someSetting (Note that CONFIG_FILE must be an absolute path for this to work.) builtins.readDir path Return the contents of the directory path as a set mapping directory entries to the corresponding file type. For instance, if directory A contains a regular file B and another directory C, then builtins.readDir ./A will return the set { B = "regular"; C = "directory"; } The possible values for the file type are "regular", "directory", "symlink" and "unknown". builtins.readFile path Return the contents of the file path as a string. removeAttrs set list Remove the attributes listed in list from set. The attributes don’t have to exist in set. For instance, removeAttrs { x = 1; y = 2; z = 3; } [ "a" "x" "z" ] evaluates to { y = 2; }. builtins.replaceStrings from to s Given string s, replace every occurrence of the strings in from with the corresponding string in to. For example, builtins.replaceStrings ["oo" "a"] ["a" "i"] "foobar" evaluates to "fabir". builtins.seq e1 e2 Evaluate e1, then evaluate and return e2. This ensures that a computation is strict in the value of e1. builtins.sort comparator list Return list in sorted order. It repeatedly calls the function comparator with two elements. The comparator should return true if the first element is less than the second, and false otherwise. For example, builtins.sort builtins.lessThan [ 483 249 526 147 42 77 ] produces the list [ 42 77 147 249 483 526 ]. This is a stable sort: it preserves the relative order of elements deemed equal by the comparator. builtins.stringLength e Return the length of the string e. If e is not a string, evaluation is aborted. builtins.sub e1 e2 Return the difference between the numbers e1 and e2. builtins.substring start len s Return the substring of s from character position start (zero-based) up to but not including start + len. If start is greater than the length of the string, an empty string is returned, and if start + len lies beyond the end of the string, only the substring up to the end of the string is returned. start must be non-negative. builtins.tail list Return the second to last elements of a list; abort evaluation if the argument isn’t a list or is an empty list. throw s Throw an error message s. This usually aborts Nix expression evaluation, but in nix-env -qa and other commands that try to evaluate a set of derivations to get information about those derivations, a derivation that throws an error is silently skipped (which is not the case for abort). builtins.toFile name s Store the string s in a file in the Nix store and return its path. The file has suffix name. This file can be used as an input to derivations. One application is to write builders “inline”. For instance, the following Nix expression combines and into one file: { stdenv, fetchurl, perl }: stdenv.mkDerivation { name = "hello-2.1.1"; builder = builtins.toFile "builder.sh" " source $stdenv/setup PATH=$perl/bin:$PATH tar xvfz $src cd hello-* ./configure --prefix=$out make make install "; src = fetchurl { url = http://nix.cs.uu.nl/dist/tarballs/hello-2.1.1.tar.gz; md5 = "70c9ccf9fac07f762c24f2df2290784d"; }; inherit perl; } It is even possible for one file to refer to another, e.g., builder = let configFile = builtins.toFile "foo.conf" " # This is some dummy configuration file. ... "; in builtins.toFile "builder.sh" " source $stdenv/setup ... cp ${configFile} $out/etc/foo.conf "; Note that ${configFile} is an antiquotation (see ), so the result of the expression configFile (i.e., a path like /nix/store/m7p7jfny445k...-foo.conf) will be spliced into the resulting string. It is however not allowed to have files mutually referring to each other, like so: let foo = builtins.toFile "foo" "...${bar}..."; bar = builtins.toFile "bar" "...${foo}..."; in foo This is not allowed because it would cause a cyclic dependency in the computation of the cryptographic hashes for foo and bar. builtins.toJSON e Return a string containing a JSON representation of e. Strings, integers, floats, booleans, nulls and lists are mapped to their JSON equivalents. Sets (except derivations) are represented as objects. Derivations are translated to a JSON string containing the derivation’s output path. Paths are copied to the store and represented as a JSON string of the resulting store path. builtins.toPath s Convert the string value s into a path value. The string s must represent an absolute path (i.e., must start with /). The path need not exist. The resulting path is canonicalised, e.g., builtins.toPath "//foo/xyzzy/../bar/" returns /foo/bar. toString e Convert the expression e to a string. e can be a string (in which case toString is a no-op) or a path (e.g., toString /foo/bar yields "/foo/bar". builtins.toXML e Return a string containing an XML representation of e. The main application for toXML is to communicate information with the builder in a more structured format than plain environment variables. shows an example where this is the case. The builder is supposed to generate the configuration file for a Jetty servlet container. A servlet container contains a number of servlets (*.war files) each exported under a specific URI prefix. So the servlet configuration is a list of sets containing the path and war of the servlet (). This kind of information is difficult to communicate with the normal method of passing information through an environment variable, which just concatenates everything together into a string (which might just work in this case, but wouldn’t work if fields are optional or contain lists themselves). Instead the Nix expression is converted to an XML representation with toXML, which is unambiguous and can easily be processed with the appropriate tools. For instance, in the example an XSLT stylesheet () is applied to it () to generate the XML configuration file for the Jetty server. The XML representation produced from by toXML is shown in . Note that uses the toFile built-in to write the builder and the stylesheet “inline” in the Nix expression. The path of the stylesheet is spliced into the builder at xsltproc ${stylesheet} .... $out/server-conf.xml]]> "; servlets = builtins.toXML []]> ]]> builtins.trace e1 e2 Evaluate e1 and print its abstract syntax representation on standard error. Then return e2. This function is useful for debugging. builtins.typeOf e Return a string representing the type of the value e, namely "int", "bool", "string", "path", "null", "set", "list" or "lambda".