Wombat’s Book of Nix

Strings are enclosed by double quotes ("), or two single quotes (').

They can span multiple lines.

The Boolean values in Nix are true and false.

File paths play an important role in building software, so Nix has a special data type for them. Paths may be absolute (e.g. /bin/sh) or relative (e.g. ./data/file1.csv). Note that paths are not enclosed in quotation marks; they are not strings!

Enclosing a path in angle brackets, e.g. <nixpkgs> causes the directories listed in the environment variable NIX_PATH to be searched for the given file or directory name. These are called lookup paths.

List elements are enclosed in square brackets and separated by spaces (not commas). The elements need not be of the same type.

Lists can be empty.

List elements can be of any type, and can even be lists themselves.

Attribute sets associate keys with values. They are enclosed in curly brackets, and the associations are terminated by semi-colons. Note that the final semi-colon before the closing bracket is required.

The keys of an attribute set must be strings. When the key is not a valid identifier, it must be enclosed in quotation marks.

Attribute sets can be empty.

Values of attribute sets can be of any type, and can even be attribute sets themselves.

In Section 2.11.4, “Recursive attribute sets” you will be introduced to a special type of attribute set.

We’ll learn how to write functions later in this chapter. For now, note that functions are "first-class values", meaning that they can be treated like any other data type. For example, a function can be assigned to a variable, appear as an element in a list, or be associated with a key in an attribute set.

You can declare variables in Nix and assign values to them.

In Nix, values are immutable; once you assign a value to a variable, you cannot change it. You can, however, create a new variable with the same name, but in a different scope. Don’t worry if you don’t completely understand the previous sentence; we will see some examples in [_functions], Section 2.15, “Let expressions”, and Section 2.16, “With expressions”.

The usual arithmetic operators are provided.

Numbers without a decimal point are assumed to be integers. To ensure that a number is interpreted as a floating-point value, add a decimal point.

In the example below, the first expression results in integer division (rounding down), while the second produces a floating-point result.

String concatenation uses the + operator.

You can use the ${variable} syntax to insert the value of a variable within a string.

Nix provides some built-in functions for working with strings; a few examples are shown below. For more information on these and other built-in functions, see the Nix Manual (https://nixos.org/manual/nix/stable/language/builtins).

How long is this string?

Given a starting position and a length, extract a substring. The first character of a string has index 0.

Convert an expression to a string.

Paths can be concatenated to produce a new path.

A path can be concatenated with a string to produce a new path.

Strings can be concatenated with paths, but with a side-effect that may surprise you: if the path exists, the file is copied to the Nix store! The result is a string, not a path.

In the example below, the file file.txt is copied to /nix/store/gp8ba25gpwvbqizqfr58jr014gmv1hd8-file.txt (not, as you might expect, to /home/wombat/nix/store/gp8ba25gpwvbqizqfr58jr014gmv1hd8-file.txt).

The path must exist.

Nix provides some built-in functions for working with paths; a few examples are shown below. For more information on these and other built-in functions, see the Nix Manual (https://nixos.org/manual/nix/stable/language/builtins).

Does the path exist?

Get a list of the files in a directory, along with the type of each file.

Read the contents of a file into a string.

Lists can be concatenated using the ++ operator.

Nix provides some built-in functions for working with lists; a few examples are shown below. For more information on these and other built-in functions, see the Nix Manual (https://nixos.org/manual/nix/stable/language/builtins).

Testing if an element appears in a list.

Selecting an item from a list by index. The first element in a list has index 0.

Determining the number of elements in a list.

Accessing the first element of a list.

Dropping the first element of a list.

Functions are useful for working with lists. Functions will be introduced in Section 2.12, “Functions”, but the following examples should be somewhat self-explanatory.

Using a function to filter (select elements from) a list.

Applying a function to all the elements in a list.

The . operator selects an attribute from a set.

We can use the ? operator to find out if a set has a particular attribute.

We can use the // operator to modify an attribute set. Recall that Nix values are immutable, so the result is a new value (the original is not modified). Attributes in the right-hand set take preference.

An ordinary attribute set cannot refer to its own elements. To do this, you need a recursive attribute set.

Nix provides some built-in functions for working with attribute sets; a few examples are shown below. For more information on these and other built-in functions, see the Nix Manual (https://nixos.org/manual/nix/stable/language/builtins).

Get an alphabetical list of the keys.

Get the values associated with each key, in alphabetical order by the key names.

What value is associated with a key?

Does the set have a value for a key?

Remove one or more keys and associated values from a set.

Functions are defined using the syntax parameter: expression, where the expression typically involves the parameter. Consider the following example.

We created a function that adds 1 to its input. However, it doesn’t have a name, so we can’t use it directly. Anonymous functions do have their uses, as we shall see shortly.

Note that the message printed by the Nix REPL when we created the function uses the term lambda. This derives from a branch of mathematics called lambda calculus. Lambda calculus was the inspiration for most functional languages such as Nix. Functional programmers often call anonymous functions "lambdas".

The Nix REPL confirms that the expression x: x + 1 defines a function.

How can we use a function? Recall from Section 2.2.8, “Functions” that functions can be treated like any other data type. In particular, we can assign it to a variable.

Procedural languages such as C or Java often use parenthesis to apply a function to a value, e.g. f(5). Nix, like lambda calculus and most functional languages, does not require parenthesis for function application. This reduces visual clutter when chaining a series of functions.

Now that our function has a name, we can use it.

Functions in Nix always have a single parameter. To define a calculation that requires more than one parameter, we create functions that return functions!

We have created a function called add. When applied to a parameter a, it returns a new function that adds a to its input. Note that the expression (b: a+b) is an anonymous function. We never call it directly, so it doesn’t need a name. Anonymous functions are useful after all!

I used parentheses to emphasise the inner function, but they aren’t necessary. More commonly we would write the following.

If we only supply one parameter to add, the result is a new function rather than a simple value. Invoking a function without supplying all of the expected parameters is called partial application.

Now let’s apply add 3 to the value 5.

In fact, the parentheses aren’t needed.

If you’ve never used a functional programming language, this all probably seems very strange. Imagine that you want to add two numbers, but you have a very unusual calculator labeled "add". This calculator never displays a result, it only produces more calculators! If you enter the value 3 into the "add" calculator, it gives you a second calculator labeled "add 3". You then enter 5 into the "add 3" calculator, which displays the result of the addition, 8.

With that image in mind, let’s walk through the steps again in the REPL, but this time in more detail. The function add takes a single parameter a, and returns a new function that takes a single parameter b, and returns the value a + b. Let’s apply add to the value 3, and give the resulting new function a name, g.

The function g takes a single parameter and adds 3 to it. The Nix REPL confirms that g is indeed a function.

Now we can apply g to a number to get a new number.

I said earlier that a function in Nix always has a single parameter. However, that parameter need not be a simple value; it could be a list or an attribute set. This approach is widely used in Nix, and the language has some special features to support it. This is an important topic, so we will cover it separately in Section 2.13, “Argument sets”.

To specify an attribute set as a function parameter, we use a set pattern, which has the form

Note that while the key-value associations in attribute sets are separated by semi-colons, the key names in the attribute set _pattern are separated by commas. Here’s an example of a function that has an attribute set as an input parameter.

We can make some values in an argument set optional by providing default values, using the syntax name ? value. This is illustrated below.

A function can allow the caller to supply argument sets that contain "extra" values. This is done with the special parameter …​.

One reason for doing this is to allow the caller to pass the same argument set to multiple functions, even though each function may not need all of the values.

Another reason for allowing variadic arguments is when a function calls another function, supplying the same argument set. An example is shown in Section 2.13.4, “@-patterns”.

It can be convenient for a function to be able to reference the argument set as a whole. This is done using an @-pattern.

Alternatively, the @-pattern can appear after the argument set, as in the example below.

An @-pattern is the only way a function can access variadic attributes, so they are often used together. In the example below, the function greet passes its argument set, including the variadic arguments, to the function confirmAddress.

Next, we’ll create a simple Haskell program.

Before we package the program, let’s verify that it runs. We’re going to need Haskell. By now you’ve probably figured out that we can write a flake.nix and define a development shell that includes Haskell. We’ll do that shortly, but first I want to show you a handy shortcut. We can launch a temporary shell with any Nix packages we want. This is convenient when you just want to try out some new software and you’re not sure if you’ll use it again. It’s also convenient when you’re not ready to write flake.nix (perhaps you’re not sure what tools and packages you need), and you want to experiment a bit first.

The command to enter a temporary shell is

nix shell -p installables

Where installables are flakes and other types of packages that you need. (You can learn more about these in the Nix manual.)

It’s time to write a Cabal file for this program. This is just an ordinary Cabal file; we don’t need to do anything special for Nix.

We won’t write flake.nix just yet. First we’ll try building the package manually. (If you didn’t run the nix shell command from earlier, do so now.)

The cabal command is provided by the cabal-install package. The error happens because we don’t have cabal-install available in the temporary shell. We can correct that.

Note that we’re now inside a temporary shell inside the previous temporary shell! To get back to the original shell, we have to exit twice. Alternatively, we could have done exit followed by the second nix-shell command.

After a lot of output messages, the build succeeds.

Now we should write flake.nix. We already know how to write most of the flake from the examples we did earlier. The two parts that will be different are the development shell and the package builder.

However, there’s a much simpler way, using haskell-flake. The following command will create flake.nix based on their template.

Examining the flake, you’ll notice that it is well-commented. The only thing we need to change for now is the name in packages.default; I’ve highlighted the change below.

We also need a LICENSE file. For now, this can be empty.

Let’s try out the new flake. Nix flakes only “see” files that are part of the repository. We need to add all of the important files to the repo before building or running the flake.

We’ll deal with those warnings later. The important thing for now is that the build succeeded.

Now we can run the program.

By the way, we didn’t need to do nix build earlier. The nix run command will first build the program for us if needed.

We’d like to share this package with others, but first we should do some cleanup. It’s time to deal with those warnings. When the package was built, Nix created a flake.lock file. We need to add this to the repo, and commit all important files.

You can test that your package is properly configured by going to another directory and running it from there.

If you move the project to a public repo, anyone can run it. Recall from the beginning of the tutorial that you were able to run hello-flake directly from my repo with the following command.

Modify the URL accordingly and invite someone else to run your new Haskell flake.

Next, we’ll create a simple Python program.

Before we package the program, let’s verify that it runs. We’re going to need Python. By now you’ve probably figured out that we can write a flake.nix and define a development shell that includes Python. We’ll do that shortly, but first I want to show you a handy shortcut. We can launch a temporary shell with any Nix packages we want. This is convenient when you just want to try out some new software and you’re not sure if you’ll use it again. It’s also convenient when you’re not ready to write flake.nix (perhaps you’re not sure what tools and packages you need), and you want to experiment a bit first.

The command to enter a temporary shell is

nix shell -p installables

Where installables are flakes and other types of packages that you need. (You can learn more about these in the Nix manual.)

Let’s enter a shell with Python so we can test the program.

Next, create a Python script to build the package. We’ll use Python’s setuptools, but you can use other build tools. For more information on setuptools, see the Python Packaging User Guide, especially the section on setup args.

We won’t write flake.nix just yet. First we’ll try building the package manually. (If you didn’t run the nix shell command from earlier, do so now.)

The missing module error happens because we don’t have build available in the temporary shell. We can fix that by adding “build” to the temporary shell. When you need support for both a language and some of its packages, it’s best to use one of the Nix functions that are specific to the programming language and build system. For Python, we can use the withPackages function.

Note that we’re now inside a temporary shell inside the previous temporary shell! To get back to the original shell, we have to exit twice. Alternatively, we could have done exit followed by the second nix-shell command.

After a lot of output messages, the build succeeds.

Now we should write flake.nix. We already know how to write most of the flake from the examples we did earlier. The two parts that will be different are the development shell and the package builder.

Let’s start with the development shell. It seems logical to write something like the following.

Note that we need the parentheses to prevent python.withPackages and the argument from being processed as two separate tokens. Suppose we wanted to work with virtualenv and pip instead of build. We could write something like the following.

For the package builder, we can use the buildPythonApplication function.

If you put all the pieces together, your flake.nix should look something like this.

Let’s try out the new flake.

Nix flakes only “see” files that are part of the repository. We need to add all of the important files to the repo before building or running the flake.

We’ll deal with those warnings later. The important thing for now is that the build succeeded.

Now we can run the program.

By the way, we didn’t need to do nix build earlier. The nix run command will first build the program for us if needed.

We’d like to share this package with others, but first we should do some cleanup. It’s time to deal with those warnings. When the package was built, Nix created a flake.lock file. We need to add this to the repo, and commit all important files.

You can test that your package is properly configured by going to another directory and running it from there.

If you move the project to a public repo, anyone can run it. Recall from the beginning of the tutorial that you were able to run hello-flake directly from my repo with the following command.

Modify the URL accordingly and invite someone else to run your new Python flake.

In this example, we will use a flake defined in a remote git repo. However, you can use any of the flake reference styles defined in Section 10.1.2, “Run a flake”.

In this example, we will use a flake defined in a remote git repo. However, you can use any of the flake reference styles defined in Section 10.1.2, “Run a flake”.

Occasionally you might want to run a short Haskell program that depends on a Haskell library, but you don’t want to bother writing a cabal file.

Example: Access the extra package from the haskellPackages set in the nixpkgs repo.

Occasionally you might want to run a short Python program that depends on a Python library, but you don’t want to bother configuring a builder.

Example: Access the html_sanitizer package from the python3nnPackages set in the nixpkgs repo.

Here’s a demonstration using the shell.

In this example, we will use a flake defined in a remote git repo. However, you can use any of the flake reference styles defined in Section 10.1.2, “Run a flake”.

Line 5 adds hello-flake as an input to this flake. Line 8 allows the output function to reference hello-flake. Line 16 adds hello-flake as a build input for this flake.

Let’s take a closer look at the buildInputs expression from line 16.

Why is the first part hello-flake and the last part hello? The first part refers to the name we assigned in the input section of our flake, and the last part is the name of the package or app we want. (See Section 3.1, “Flake outputs” for how to identify flake outputs.)

Here’s a demonstration using the shell.

Occasionally you might want to run a short Haskell program that depends on a Haskell library, but you don’t want to bother writing a cabal file. In this example, we will access the extra package from the haskellPackages set in the nixpkgs repo.

Line 12 makes a custom GHC that knows about extra, and line 16 makes that custom GHC available in the development environment.

Here’s a short Haskell program that uses the new flake.

Here’s a demonstration using the program.

Set the value of the environment variable FOO to “bar”.

Here’s a demonstration using the shell.

In this example, we will use a nix package (not a flake) defined in a remote git repo. However, you can use any of the flake reference styles defined in Section 10.1.2, “Run a flake”.

The hello-nix repo provides a default.nix. If the derivation in that file allows us to supply our own package set, then our flake can call it to build hello nix. If instead it requires <nixpkgs>, it is not pure and we cannot use it.

For example, if the file begins with an expression such as

then it requires nixpkgs so we cannot use it. Instead, we have to write our own derivation (see Section 10.4.5.2, “If the nix derivation requires nixpkgs”).

Fortunately the file begins with

then it accepts a package set as an argument, only using <nixpkgs> if no argument is provided. We can use it directly to build hello-nix (see Section 10.4.5.1, “If the nix derivation does not require nixpkgs”).

See Section 8.2, “Introducing a dependency”.

In this example, we will use a flake defined in a remote git repo. However, you can use any of the flake reference styles defined in Section 10.1.2, “Run a flake”.

Line 5 adds hello-flake as an input to this flake, Line 8 allows the output function to reference hello-flake. As expected, we need to add hello-flake as a build input, which we do in line 35. Let’s take a closer look at the buildInputs expression from line 35.

Why is the first part hello-flake and the last part hello? The first part refers to the name we assigned in the input section of our flake, and the last part is the name of the package or app we want. (See Section 3.1, “Flake outputs” for how to identify flake outputs.)

Line 35 does make hello-flake available at build and runtime, but it doesn’t put it on the path, so our hello-again script won’t be able to find it. There are various ways to deal with this problem. In this case we simply edited the script (lines 30-32) as we install it, by specifying the full path to hello-nix.

Here’s a demonstration using the flake.

If you use haskell-flake (see Section 9.1.5, “The Nix flake”) nothing special needs to be added to flake.nix. Simply list your Haskell package dependencies to your cabal file as you normally would.

In this example we will access three Haskell packages (pandoc-linear-table, pandoc-logic-proof, and pandoc-columns) that are defined as flakes on my hard drive. We are using haskell-flake, so the development environment is set up automatically; no need to define devShells.

In this example, we will use a nix package (not a flake) defined in a remote git repo. However, you can use any of the flake reference styles defined in Section 10.1.2, “Run a flake”.

We already covered how to add a non-flake input to a flake and build it in Section 10.4.5, “Access a non-flake package (not in nixpkgs)”; here we will focus on making it available at runtime. We will write a flake to package a very simple shell script. All it does is invoke hello-nix, which is the input we added earlier.

Lines 5-8 and 15 were explained in Section 10.4.5, “Access a non-flake package (not in nixpkgs)”. As expected, we need to add helloNix as a build input, which we do in line 40. That does make it available at build and runtime, but it doesn’t put it on the path, so our hello-again script won’t be able to find it.

There are various ways to deal with this problem. In this case we simply edited the script (lines 34-36) as we install it, by specifying the full path to hello-nix.

Here’s a demonstration using the flake.