I want to...
Comparison
Comparisons ... check if one value is equal to another 1 == 2
... check if one value is different from another 1 != 2
... check if one value is less than another 1 < 2
builtins.lessThan 1 2 (for numbers only!)
... check if one value is less than or equal to another 1 <= 2
... check if one value is more than another 1 > 2
builtins.moreThan 1 2 (for numbers only!)
... check if one value is more than or equal to another 1 >= 2
... compare two values, as a comparator function lib.trivial.compare 1 2
Boolean logic ... check that both expressions are true <expression 1> && <expression 2>
lib.trivial.and <expression 1> <expression 2>
... check that at least one expression is true <expression 1> || <expression 2>
lib.trivial.or <expression 1> <expression 2>
Function
Typecheck ... check if something is a function builtins.isFunction <value> (does not work with custom-set metadata!)
lib.trivial.isFunction <value> (... use this one instead)
Creation ... define a function <parameter>: <body expression>
... unpack named arguments from a set argument { parameter1, parameter2 }: <body expression>
... allow (and ignore) unspecified named arguments { parameter1, parameter2, ... }: <body expression>
... also make the whole set itself accessible { parameter1, parameter2} @ <identifier>: <body expression>
... generate a function that always returns the same value lib.trivial.const <value>
Metadata ... add metadata to a function of what named arguments it expects lib.trivial.setFunctionArgs <function> <argument set>
... get a set of all named arguments expected by a function builtins.functionArgs <function> (does not work with custom-set metadata!)
lib.trivial.functionArgs <function> (... use this one instead)
Calling ... call a function <function> <argument>
... call a function, but only if the argument is not null lib.trivial.mapNullable <function> <argument>
... call a two-argument function, with the arguments flipped lib.trivial.flip <function> <argument 2> <argument 1>
... call a series of functions in sequence, each receiving the return value of the last lib.trivial.pipe <value> <list of functions>
List (array)
Typecheck ... check if something is a list builtins.isList <value>
Creation ... create a list literal [ <value 1> <value 2> <value 3> <...> ]
... generate a list using a generator function builtins.genList <generator (index)> <length>
... generate a list from a range of integers lib.lists.range <first integer> <last integer>
... wrap a value in a list, if it isn't already one lib.lists.toList <value>
Metadata ... get the length of a list builtins.length <list>
Elements ... get the element at a given index builtins.elemAt <list> <index>
... get the first element builtins.head <list>
... get the first N elements, as a list lib.lists.take <amount> <list>
... get all elements except for the first builtins.tail <list>
... get all elements except for the first N, as a list lib.lists.drop <amount> <list>
... get the last element lib.lists.last <list>
... get all elements except for the last lib.lists.init <list>
... get a specified subset of elements, as a list lib.lists.subList <start index> <amount> <list>
... find the first element that satisfies a predicate lib.lists.findFirst <predicate (value)> <default> <list>
Checks ... check that the list contains a given value builtins.elem <value> <list>
... check that all elements satisfy a predicate builtins.all <predicate (value)> <list>
... check that at least one element satisfies a predicate builtins.any <predicate (value)> <list>
... count how many elements satisfy a predicate lib.lists.count <predicate (value)> <list>
... check that there are no common elements among two lists lib.lists.mutuallyExclusive <list 1> <list 2>
Combining ... combine (concatenate) two lists <list 1> ++ <list 2> (for conditional concatenation)
lib.trivial.concat <list 1> <list 2>
... combine (concatenate) many lists builtins.concatLists <list of lists>
... return either the specified list or an empty one, depending on a boolean lib.lists.optionals <boolean> <list>
... zip two lists together into a list of {fst, snd} sets lib.lists.zipLists <list 1> <list 2>
... zip two lists together, with a custom combiner lib.lists.zipListsWith <combiner (value 1, value 2)> <list 1> <list 2>
... flatten a list of lists into a single list lib.lists.flatten <list>
... get a list of values that exist in both of two lists, ie. the intersection lib.lists.intersectLists <list 1> <list 2> (O(nm) complexity!)
... get a list of values from one list that do not exist in the other, ie. subtraction lib.lists.subtractLists <elements to subtract> <list> (O(nm) complexity!)
... get the Cartesian product of two lists, with a custom combiner lib.lists.crossLists <combiner (value 1, value 2)> <list 1> <list 2>
Deriving ... filter the list by a predicate builtins.filter <predicate (value)> <list>
... filter the list, by removing a specific value whenever it occurs lib.lists.remove <value> <list>
... filter the list, by removing duplicate values lib.lists.unique <list> (O(n^2) complexity!)
... transform each item in a list builtins.map <transformer (value)> <list>
lib.lists.forEach <list> <transformer (value)>
... transform each item in a list, with access to the index lib.lists.imap0 <transformer (index, value)> <list>
... transform each item in a list and flatten the result, like a flatmap lib.lists.concatMap <transformer (value)> <list>
... intersperse a value between each element in a list lib.strings.intersperse <value> <list>
... reduce a list to a single value builtins.foldl' <reducer (previous, value)> <initial value> <list>
... reduce a list to a single value, starting from the right lib.lists.foldr <reducer (value, previous)> <initial value> <list>
... split a list into a {right, wrong} set based on a predicate builtins.partition <predicate (value)> <list>
... group elements together based on the key returned from a function builtins.groupBy <key function (value)> <list>
... group elements together based on the key returned from a function, with a custom reducer lib.lists.groupBy' <reducer (previous, value)> <initial value> <key function (value)> <list>
Ordering ... sort a list by a comparator function builtins.sort <comparator> <list>
lib.lists.sort <comparator> <list> (quicksort)
... sort a list by 'natural sorting' lib.lists.naturalSort <list>
... compare two lists element-wise, wrapping a value comparator lib.lists.compareLists <comparator> <list 1> <list 2>
... reverse a list lib.lists.reverseList <list>
Attribute set (object)
Typecheck ... check if something is an attribute set builtins.isAttrs <value>
... check if something is a derivation lib.attrsets.isDerivation <value>
Creation ... create a set literal { <attribute 1> = <value 1>; <attribute 2> = <value 2>; <...> }
... copy some attributes from the scope { inherit <attribute 1> <attribute 2> <...>; <... regular attributes go here ...> }
... copy some attributes from another set { inherit (<set>) <attribute 1> <attribute 2> <...>; <... regular attributes go here ...> } (the (parens) are literal!)
... create a set from a list of {name, value} sets builtins.listToAttrs <list>
... generate a set using a generator function lib.attrsets.genAttrs <list of attributes> <generator (attribute)>
Attributes ... access an attribute (property) <set>.<attribute>
... access an attribute (property) dynamically builtins.getAttr <set> <attribute>
... access an attribute (property), with a default fallback <set>.<attribute> or <default>
... access a nested attribute path <attribute 1>.<attribute 2>.<attribute 3>.<...>
... access a nested attribute path dynamically lib.attrsets.getAttrFromPath <attribute path> <set>
... access a nested attribute path dynamically, with a default fallback lib.attrsets.attrByPath <attribute path> <default> <set>
Checks ... check if a set has an attribute <set> ? <attribute>
... check if a set has an attribute dynamically builtins.hasAttr <set> <attribute>
... check if an attribute path exists lib.attrsets.hasAttrByPath <list of attributes> <set>
Combining ... combine (merge) two attribute sets <set 1> // <set 2>
lib.trivial.mergeAttrs <set 1> <set 2>
... combine (merge) two attribute sets, recursively lib.attrsets.recursiveUpdate <set 1> <set 2>
... combine (merge) two attribute sets, recursively, with a predicate for recursing lib.attrsets.recursiveUpdateUntil <predicate (attribute path, value 1, value 2)> <set 1> <set 2>
... return either the specified set or an empty one, depending on a boolean lib.attrsets.optionalAttrs <boolean> <set> (for conditional merges)
Deriving ... transform each value in a set builtins.mapAttrs <transformer (name, value)> <set>
... transform each value in a set, recursively lib.attrsets.mapAttrsRecursive <transformer (attribute path, value)> <set>
... transform each value in a set, recursively, with a predicate for recursing lib.attrsets.mapAttrsRecursive <predicate (set)> <transformer (attribute path, value)> <set>
... transform each value in a set, returning only a list of the values lib.attrsets.mapAttrsToList <transformer (name, value)> <set>
... transform each name and value in a set lib.attrsets.mapAttrs' <transformer (name, value)> <set>
Subsets ... get a subset that doesn't include particular attributes builtins.removeAttrs <set> <list of attributes>
... get a subset that *only* includes particular attributes lib.attrsets.attrVals <list of attributes> <set>
{ inherit (<set>) <attribute 1> <attribute 2> <...>; }
... get a subset of attributes that match a predicate function lib.attrsets.filterAttrs <predicate (name, value)> <set>
... get a subset of attributes that match a predicate function, recursively lib.attrsets.filterAttrsRecursive <predicate (name, value)> <set>
... get a subset (2) of all attributes that also exist in another set (1), ie. the intersection builtins.intersectAttrs <set 1> <set 2>
Lists ... get a list of all attribute names builtins.attrNames <set>
... get a list of all values builtins.attrValues <set>
... get a list of all values that match a predicate, recursively lib.attrsets.collect <predicate (value)> <set>
List/set combinations
Transposing ... transpose a list of sets into a set of lists lib.attrsets.zipAttrs <list of sets>
... transpose a list of sets into a set of lists, with a values transformer builtins.zipAttrsWith <transformer (name, values)> <list of sets>
... transpose a list of sets into a set of lists, with a values transformer, but only for specific attributes lib.attrsets.zipAttrsWithNames <attributes> <transformer (name, values)> <list of sets>
... transpose a set of lists into a list of sets, based on the Cartesian product of each attribute's list elements lib.attrsets.cartesianProductOfSets <set>
List of sets ... extract a specified attribute from every set in a list, into a list of values builtins.catAttrs <attribute> <list>
... reduce over the values of each attribute separately, in a list of sets lib.attrsets.foldAttrs <reducer (value, previous)> <initial value> <list>
Null
Typecheck ... check if something is null <value> == null
builtins.isNull <value> (deprecated)
Boolean
Typecheck ... check if something is a boolean builtins.isBool <value>
Creation ... create a boolean literal true
false
Deriving ... negate a boolean !<boolean>
Conversion ... convert a boolean to a string lib.trivial.boolToString <boolean>
String
Typecheck ... check if something is a string builtins.isString <value>
... check if something is automatically coercible into a string lib.strings.isCoercibleToString <value>
... check if something is a string representing a store path lib.strings.isStorePath <value>
Creation ... create a string literal "string"
Metadata ... get the length of a string builtins.stringLength <string>
Checks ... check whether a string contains a certain substring lib.strings.hasInfix <substring> <string>
... check whether a string starts with a certain prefix lib.strings.hasPrefix <prefix> <string>
... check whether a string ends with a certain suffix lib.strings.hasSuffix <suffix> <string>
Combining ... combine (concatenate) two strings <string 1> + <string 2>
... return either the specified string or an empty one, depending on a boolean lib.strings.optionalString <boolean> <string> (for conditional concatenation)
... concatenate a list of strings into a single string lib.strings.concatStrings <list>
... concatenate a list of strings into a single string, with a delimiter builtins.concatStringsSep <delimiter> <list>
Substrings ... get a substring out of a string builtins.substring <start index> <length> <string>
Matching ... test a string against a regex, and return a list of matched groups builtins.match <regex> <string>
Deriving ... replace one or more substrings builtins.replaceStrings <matches> <replacements> <string>
... convert a string to lowercase lib.strings.toLower <string>
... convert a string to UPPERCASE lib.strings.toUpper <string>
... remove a prefix from a string lib.strings.removePrefix <string>
... remove a suffix from a string lib.strings.removeSuffix <string>
... left-pad a string lib.strings.fixedWidthString <width> <filler> <string>
Splitting ... split a string by a delimiter lib.strings.splitString <delimiter> <string>
... split a string by a regex, returning both substrings and delimiters builtins.split <regex> <string>
Conversion ... convert a string to an integer lib.strings.toInt <string>
... convert a string to an absolute path /. + <string>
... convert a string to a relative path ./. + <string>
... convert a string to a regular expression that exactly matches that string lib.strings.escapeRegex <string>
Number
Typecheck ... check if something is a float builtins.isFloat <value>
... check if something is an integer builtins.isInt <value>
Creation ... create a number literal 42
42.0
Calculation ... negate a number -<number>
... add/sum two numbers <number 1> + <number 2>
builtins.add <number 1> <number 2>
... subtract one number from another <number 1> - <number 2>
builtins.sub <number 1> <number 2>
... multiply two numbers <number> * <multiplier>
builtins.mul <number> <multiplier>
... divide one number by another <number> / <divisor>
builtins.div <number> <divisor>
... do an integer modulo lib.trivial.mod <number> <divisor>
... get the smallest of two numbers lib.trivial.min <number 1> <number 2>
... get the largest of two numbers lib.trivial.max <number 1> <number 2>
Rounding ... round up to the nearest integer builtins.ceil <number>
... round down to the nearest integer builtins.floor <number>
Bitwise ... do a bitwise AND builtins.bitAnd <number 1> <number 2>
... do a bitwise OR builtins.bitOr <number 1> <number 2>
... do a bitwise XOR builtins.bitXor <number 1> <number 2>
... do a bitwise NOT lib.trivial.bitNot <number>
Formatting ... left-pad a number, producing a string lib.strings.fixedWidthNumber <width> <number>
Conversion ... convert a float to a string with precision guard lib.strings.floatToString <float>
... convert a positive integer to a hex string lib.trivial.toHexString <integer>
... convert a positive integer to a list of digits in the specified base lib.trivial.toBaseDigits <base> <integer>
Path
Typecheck ... check if something is a path builtins.isPath <value>
... check whether a path currently exists builtins.pathExists <path>
Creation ... create a path literal /path/to/something
... create a path literal, relative to the user's home directory ~/path/to/something
... create a path literal, for a path that is found somewhere in NIX_PATH <path/to/something> (the <brackets> are literal!)
... create a path with custom settings builtins.path { path, name, filter, recursive, sha256 }
... create a path from an existing store path, preventing a store copy builtins.storePath <path>
Loading ... import a path; ie. load and parse/evaluate it as Nix code import <path>
Deriving ... only copy files/folders to the store that match a predicate builtins.filterSource <predicate> <path> (consider using builtins.path instead)
FIXME: https://nixos.org/manual/nixpkgs/stable/#sec-pkgs-nix-gitignore
FIXME: lib.sources.cleanSource
Specialized string utilities
Hashing ... get the hash of a string builtins.hashString <algorithm> <string>
Escaping ... escape a string parameter for safe usage in Bash lib.strings.escapeShellArg <string>
... escape a list of string parameters for safe usage in Bash lib.strings.escapeShellArgs <list>
... escape a string for safe embedding in XML lib.strings.escapeXML <string>
... sanitize a string for safe usage as a derivation name lib.strings.sanitizeDerivationName <string>
Path handling ... get the base name of a string path builtins.baseNameOf <string>
... get the directory name of a string path builtins.dirOf <string>
Versions ... compare two version strings builtins.compareVersions <version 1> <version 2>
... split a version string into its components builtins.splitVersion <string>
... parse a string into a {name, version} set builtins.parseDrvName <string>
Autoconf ... generate an autoconf enable/disable flag for a given feature lib.strings.enableFeature <boolean> <feature>
... generate an autoconf enable/disable flag for a given feature, with a value lib.strings.enableFeatureAs <boolean> <feature> <value>
... generate an autoconf with/without flag for a given feature lib.strings.withFeature <boolean> <feature>
... generate an autoconf with/without flag for a given feature, with a value lib.strings.withFeatureAs <boolean> <feature> <value>
Option
Note: Options are just specially-formatted attribute sets.
Typecheck ... check if something is an Option lib.options.isOption <value>
Creation ... create a new Option lib.options.mkOption { type, internal, visible, readOnly, default, apply, defaultText, example, description, relatedPackages }
... create a new Option for a boolean toggle lib.options.mkEnableOption { name }
... create a new (inaccessible) dummy Option lib.options.mkSinkUndeclaredOptions { <same as mkOption>}
Option values
... mark an option value as having a specific priority during option merging lib.mkOverride <priority> <value> (when not specified, an option has priority 100; lower priority values have preference)
... mark an option value as having priority 1000, for default values lib.mkDefault <value>
... mark an option value as having priority 50, for forcing an override lib.mkForce <value>
... mark an option value as needing to be merged with its current value, instead of replaced lib.mkMerge <value>
... mark an option value as only applying when a condition is true lib.mkIf <condition> <value> (useful for dealing with infinite recursion issues for dependent configuration options)
... like mkIf, but throws an error if the condition is false, rather than omitting the value lib.mkAssert <condition> <value>
Search paths
... generate a Unix-style search path from a list of string paths lib.strings.makeSearchPath <subdirectory> <list>
... generate a Unix-style search path for the specified output of a list of packages lib.strings.makeSearchPathOutput <subdirectory> <output> <list>
... generate a Unix-style library search path from a list of packages lib.strings.makeLibraryPath <list>
... generate a Unix-style binary search path from a list of packages lib.strings.makeBinaryPath <list>
Serialization
... turn a value into a string builtins.toString <value>
... turn a value into XML builtins.toXML <value>
... turn a value into JSON builtins.toJSON <value>
... turn a value into YAML lib.generators.toYAML {} <value>
... turn a value into INI lib.generators.toINI { mkSectionName, mkKeyValue, listsAsDuplicateKeys } <value>
... turn a value into git-config INI lib.generators.toGitINI <value>
... parse JSON builtins.fromJSON <string>
... parse TOML builtins.fromTOML <string>
Filesystem
... get the hash of a file builtins.hashFile <algorithm> <path>
... read the (types of) entries in the specified directory builtins.readDir <path>
... read the contents of a file builtins.readFile <path>
... read the contents of a file, without the trailing newline lib.strings.fileContents <path>
... store a string as a file in the Nix store builtins.toFile <name> <string> (returns a string, not a path!)
Evaluation
... forcibly evaluate one value before evaluating and returning another builtins.seq <to evaluate> <to evaluate and return>
... forcibly evaluate like above, but evaluating the first value recursively builtins.deepSeq <to evaluate> <to evaluate and return>
... try to forcibly evaluate, returning a {success, value} set as the result builtins.tryEval <to evaluate>
Derivations
... specify a derivation stdenv.mkDerivation { pname, version, meta, nativeBuildInputs, buildInputs, passthru, builder, args, outputs, phases, unpackPhase, patchPhase, configurePhase, buildPhase, checkPhase, installPhase, fixupPhase, installCheckPhase, distPhase, ... } (see the nixpkgs manual for the full list of attributes)
builtins.derivation { name, builder, args, system, outputs, ... } (only use this if you don't have nixpkgs available)
Fetching
... fetch a Git repository into a store path builtins.fetchGit { url, name, rev, ref, submodules, allRefs }
... fetch and unpack a tarball into a store path builtins.fetchTarball <url>
builtins.fetchTarball { url, sha256 }
... fetch a single file at a URL into a store path builtins.fetchurl <url>
FIXME: nixpkgs fetchers, preferred
Building
... get (a placeholder for) the build's output path builtins.placeholder <output>
Markers
... mark an attribute set as something for Nix to recurse into during eg. builds lib.attrsets.recurseIntoAttrs <set>
... mark a string as a literal Nix expression, for use in Option attributes lib.options.literalExpression <string>
... mark a string as DocBook markup, for use in Option attributes lib.options.literalDocBook <string>
Versions
... get the current nixpkgs version number lib.trivial.version
... get the current nixpkgs release number lib.trivial.release
... get the current nixpkgs release codename lib.trivial.codeName
... get the current nixpkgs version suffix lib.trivial.versionSuffix
... get the current nixpkgs revision, or a default value if unknown lib.trivial.revisionWithDefault <string>
Logging and errors
... log a value
Expression Return and log value are same? Transformation applied to logged value? Forcibly evaluated?
lib.debug.traceVal <value/expression> Yes No No
lib.debug.traceValSeq <value/expression> Yes No Yes
lib.debug.traceValSeqN <value/expression> Yes No Yes, maximum depth
lib.debug.traceValFn <transformer (value)> <value/expression> Yes Yes No
lib.debug.traceValSeqFn <transformer (value)> <value/expression> Yes Yes Yes
lib.debug.traceValSeqNFn <depth> <transformer (value)> <value/expression> Yes Yes Yes, maximum depth
builtins.trace <value> <expression> No No No
lib.debug.traceSeq <value> <expression> No No Yes
lib.debug.traceSeqN <depth> <value> <expression> No No Yes, maximum depth
... log the input and output of a function, forcibly evaluated to a maximum depth lib.debug.traceFnSeqN <depth> <function name> <function> <argument>
... log a warning, then continue evaluating an expression lib.trivial.warn <message> <expression>
... throw an error, which often but not always aborts evaluation builtins.throw <message>
... print an error, and abort evaluation builtins.abort <message>
... assert that an expression is true, throwing an error otherwise lib.asserts.assertMsg <expression> <message>
Tests
... run a set of tests lib.debug.runTests { tests = <list of test names to run>; <name> = { expr, expected }; <...> }
... create a test that expects all values in a list to be true lib.debug.testAllTrue <list>
Miscellaneous
... get the type of a value, as a string builtins.typeOf <value>
... get the architecture/platform string of the current system builtins.currentSystem
... get the value of an environment variable builtins.getEnv <variable>
... check whether the code is being evaluated inside of a Nix shell lib.trivial.inNixShell
... call an identity function lib.trivial.id <value>
Notes: Anything prefixed with `builtins` is provided by Nix, anything prefixed with `lib` or `stdenv` is provided by nixpkgs.
The {set, syntax} means that a function expects a set of parameters instead of a single one; see the manual for details.
"Attribute path" means a list of attribute names as strings, representing a hierarchical path.