Nix Tutorial 3 : Nix Built‐ins: Functions & Values

Nix comes with many built-in functions and values—these are always available via the builtins set. You’ll use them to process data, control evaluation, interact with files, and more.

---

📝 Table of Contents

1. About Built-ins
2. Global Built-ins
3. Type Checks & Info
4. Lists & Sets
5. String Operations
6. Math & Numbers
7. Files, Paths & Fetching
8. Importing & Loading
9. Control & Debugging
10. Advanced/Experimental
11. Summary Table
12. Further Reading

---

About Built-ins

• Built-ins are always available via the builtins attribute set.
• Some (like import, abort, derivation) are available directly in the global scope.
• See the full built-ins reference in the Nix Manual.

---

Global Built-ins 🌐

These are directly accessible—no builtins. prefix needed:

• import – Load and evaluate a Nix file.
• abort / throw – Abort evaluation and print an error message.
• derivation – Build derivations (see Nix manual for details).

Example:

import ./myfile.nix
abort "Something went wrong!"

---

Type Checks & Info 🔍

Quickly check types or get info about values:

Function	Description	Example
isInt	Is it an integer?	builtins.isInt 42
isFloat	Is it a float?	builtins.isFloat 1.2
isBool	Is it a boolean?	builtins.isBool true
isString	Is it a string?	builtins.isString "hi"
isPath	Is it a path?	builtins.isPath ./foo
isNull	Is it null?	builtins.isNull null
isAttrs	Is it an attribute set?	builtins.isAttrs {}
isList	Is it a list?	builtins.isList [1 2]
isFunction	Is it a function?	builtins.isFunction (x: x)
typeOf	Get the type as a string	builtins.typeOf 42

---

Lists & Sets 📚

Common helpers for working with lists and sets:

• attrNames: Get attribute names.

  builtins.attrNames { a = 1; b = 2; }  # [ "a" "b" ]

• attrValues: Get attribute values (sorted by key).

  builtins.attrValues { a = 1; b = 2; }  # [ 1 2 ]

• elem / elemAt: Check if value is in list, or get an element by index.

  builtins.elem 3 [1 2 3]    # true
  builtins.elemAt [1 2 3] 1  # 2

• length: Length of a list.

  builtins.length [1 2 3]  # 3

• map / filter / all / any: Map, filter, or test over lists.

  builtins.map (x: x * 2) [1 2 3]         # [2 4 6]
  builtins.filter (x: x > 2) [1 2 3 4]    # [3 4]
  builtins.all (x: x < 10) [1 2 3]        # true
  builtins.any (x: x > 2) [1 2 3]         # true

• concatLists / concatMap / concatStringsSep: Join lists.

  builtins.concatLists [[1 2] [3 4]]      # [1 2 3 4]
  builtins.concatMap (x: [x x]) [1 2]     # [1 1 2 2]
  builtins.concatStringsSep "/" ["usr" "bin"]  # "usr/bin"

• partition: Split list into two by predicate.

  builtins.partition (x: x > 0) [-1 0 1 2]
  # { right = [1 2]; wrong = [-1 0]; }

---

String Operations 💬

• replaceStrings: Replace substrings.

  builtins.replaceStrings ["foo"] ["bar"] "foobar"  # "barbar"

• match: Regex match.

  builtins.match "ab" "abc"        # null
  builtins.match "abc" "abc"       # [ ]
  builtins.match "a(b)(c)" "abc"   # [ "b" "c" ]

• split: Split by regex.

  builtins.split "b" "abc"         # [ "a" [ ] "c" ]

• substring: Get a substring.

  builtins.substring 0 3 "nixos"   # "nix"

• stringLength: Length in bytes.

  builtins.stringLength "hello"    # 5

• toString: Convert value to string.

  builtins.toString 42             # "42"
  builtins.toString ./file         # "/full/path/to/file"

---

Math & Numbers ➗

• add, sub, mul, div: Arithmetic operations.

  builtins.add 2 3    # 5
  builtins.sub 7 2    # 5
  builtins.mul 2 4    # 8
  builtins.div 6 3    # 2

• bitAnd, bitOr, bitXor: Bitwise logic.

  builtins.bitAnd 6 3  # 2

• ceil, floor: Rounding.

  builtins.ceil 1.2    # 2
  builtins.floor 1.7   # 1

• lessThan: Comparison.

  builtins.lessThan 2 3  # true

---

Files, Paths & Fetching 📁

• baseNameOf / dirOf: Get filename or directory.

  builtins.baseNameOf ./foo/bar.txt  # "bar.txt"
  builtins.dirOf "/foo/bar.txt"      # "/foo"

• readFile / readDir: Read files or list directories.

  builtins.readFile ./file.txt
  builtins.readDir ./mydir

• pathExists: Does a path exist?

  builtins.pathExists ./file.txt

• fetchGit / fetchTarball / fetchTree / fetchurl: Fetch sources from Git, tarballs, files, or URLs.

  builtins.fetchGit { url = "https://github.com/NixOS/nix.git"; }
  builtins.fetchTarball "https://github.com/NixOS/nixpkgs/archive/23.05.tar.gz"
  builtins.fetchurl "https://nixos.org/logo/nixlogo.png"

• storePath: Reference an existing store path without copying.

  builtins.storePath /nix/store/abc...-foo

• toFile: Write a string to a file in the Nix store.

  builtins.toFile "name.txt" "Hello, Nix!"

---

Importing & Loading 📦

• import: Load a Nix file as an expression.

  import ./myfile.nix

• fromJSON, toJSON: Parse or generate JSON.

  builtins.fromJSON ''{"foo": 1}''
  builtins.toJSON { foo = 1; }

• fromTOML: Parse TOML.

  builtins.fromTOML ''x=1\n[section]\ny=2''

• toXML: Convert value to XML string.

  builtins.toXML { foo = "bar"; }

• readFileType: Get the type of a path (file, dir, symlink).

  builtins.readFileType ./foo.txt

---

Control & Debugging 🚦

• abort, throw: Abort evaluation.

  abort "Fatal error"
  throw "Problem!"

• assert: Check a condition (see language constructs).

  • See assertions in Nix.

• trace, traceVerbose: Print a value for debugging.

  builtins.trace "Debug value" 42

• tryEval: Test if expression evaluates without error.

  builtins.tryEval (1 / 0)  # { success = false; value = false; }

• deepSeq, seq: Force evaluation order.

  builtins.seq a b         # Like Haskell's seq
  builtins.deepSeq a b     # Evaluate deeply

• warn: Print a warning.

  builtins.warn "Careful!" 1

• break: Pause in debug mode (REPL).

  builtins.break "debug"

• trace, traceVerbose: Print during evaluation for debugging.

---

Advanced/Experimental 🧪

Some built-ins are experimental and require enabling features in nix.conf (e.g. flakes, fetch-closure, etc).

• fetchClosure, fetchTree, getFlake, parseFlakeRef, flakeRefToString, outputOf: Advanced fetching and flake handling.
• addDrvOutputDependencies, unsafeDiscardOutputDependency, unsafeDiscardStringContext: Advanced context management.
• currentSystem, currentTime: Query evaluation environment.

See the Nix Manual built-ins section for details and a complete list.

---

Summary Table 📖

Built-in Example	Description
isInt 1	Check type (integer)
attrNames { a = 1; }	List attribute names
readFile ./foo.txt	Read file as string
import ./default.nix	Import and evaluate file
toJSON { x = 1; }	Convert value to JSON
add 2 3	Math addition
fetchGit { ... }	Fetch from Git
throw "err"	Abort evaluation
tryEval (throw "e")	Try and catch error

---

Further Reading 🔗

• Nix Manual: Built-ins
• NixOS Wiki: Nix Built-ins
• Nix Pills: Built-ins

---

Explore built-ins in the REPL: Try builtins.<TAB> to list available functions!

---