Flakes

Nix flakes is some upcoming feature in the Nix package manager. It allows to download nix expressions from other sources in a declarative way by specifying them a flake.nix file. Those sources are called flakes and also have a flake.nix where they can describe their own dependencies. Sources can be tarballs, git, local directories or mercurial repositories. It makes evaluation reproducible with providing a lock called flake.lock. This lock file describes provides hashes for sources and locks the revision of external version control system. Nix flakes intents to replace nix channels and the nix search path (NIX_PATH).

Installing nix flakes

Right now nix flakes are only available in the unstable nix version and need to be enabled in nix.conf as well. In NixOS this can be achieved with the following line in configuration.nix

{ pkgs, ... }: {
   nix = {
    package = pkgs.nixUnstable;
    extraOptions = ''
      experimental-features = nix-command flakes
    '';
   };
}

On non-nixos system install `nixUnstable` in your environment:

$ nix-env -iA nixUnstable

Edit either ~/.config/nix/nix.conf or /etc/nix/nix.conf and add:

experimental-features = nix-command flakes

This is needed to expose the Nix 2.0 CLI and flakes support that are hidden behind feature-flags.

Finally, if the Nix installation is in multi-user mode, don’t forget to restart the nix-daemon.

There is no official installer yet, but it is possible to download the latest snapshot nix from hydra as shown in here github action.

Basic project usage

Warning: flake makes a strong assumption that the folder is a git repository. It doesn’t work outside of them.

In your repo, run nix flake init to generate the flake.nix file. Then run git add flake.nix to add it to the git staging area, otherwise nix will not recognize that the file exists.

Flake schema

The flake.nix file is a Nix file but that has special restrictions (more on that later).

It has 3 top-level attributes:

description which is self…describing
input is an attribute set of all the dependencies of the flake. The schema is described below.
output is a function of one argument that takes an attribute set of all the realized inputs, and outputs another attribute set which schema is described below.

Input schema

This is not a complete schema but should be enough to get you started:

{
  inputs.bar = { url = "github:foo/bar/branch"; flake = false; }
}

The bar input is then passes to the output schema

Output schema

This is described in the nix package manager src/nix/flake.cc in CmdFlakeCheck.

Where:

<system> is something like "x86_64-linux", "aarch64-linux", "i686-linux", "x86_64-darwin"
<attr> is an attribute name like "hello".
<flake> is a flake name like "nixpkgs".
<store-path> is a /nix/store.. path

{ self, ... }@inputs:
{
  # Executed by `nix flake check`
  checks."<system>"."<attr>" = derivation;
  # Executed by `nix build .#<name>`
  packages."<system>"."<attr>" = derivation;
  # Executed by `nix build .`
  defaultPackage."<system>" = derivation;
  # Executed by `nix run .#<name>
  apps."<system>"."<attr>" = {
    type = "app";
    program = "<store-path>";
  };
  defaultApp."<system>" = { type = "app"; program = "..."; };
  
  # TODO: Not sure how it's being used
  legacyPackages = TODO;
  # TODO: Not sure how it's being used
  overlay = final: prev: { };
  # TODO: Same idea as overlay but a list of them.
  overlays = [];
  # TODO: Not sure how it's being used
  nixosModule = TODO;
  # TODO: Same idea as nixosModule but a list of them.
  nixosModules = [];
  # TODO: Not sure how it's being used
  nixosConfigurations = TODO;
  # TODO: Same idea as nixosModule but a list of them.
  hydraJobs = TODO;
  # Used by `nix flake init -t <flake>`
  defaultTemplate = {
    path = "<store-path>";
    description = "template description goes here?";
  };
  # Used by `nix flake init -t <flake>#<attr>`
  templates."<attr>" = { path = "<store-path>"; description = ""; );
}

Using nix flakes with NixOS

nixos-rebuild switch will reads its configuration from /etc/nixos/flake.nix if is present.

A basic nixos flake.nix could look like this:

{
  outputs = { self, nixpkgs }: {
     # replace 'joes-desktop' with your hostname here.
     nixosConfigurations.joes-desktop = nixpkgs.lib.nixosSystem {
       system = "x86_64-linux";
       modules = [ ./configuration.nix ];
     }
  };
}

nixos-rebuild also allows to specify different flake using the --flake flag:

$ sudo nixos-rebuild switch --flake '.#'

By default nixos-rebuild will use the currents system hostname to lookup the right nixos configuration in nixosConfigurations. You can also override this by using appending it to the flake parameter:

$ sudo nixos-rebuild switch --flake '/etc/nixos#joes-desktop'

To switch a remote configuration, use:

nixos-rebuild --flake .#mymachine \
  --target-host mymachine-hostname --build-host localhost \
  switch

Warning: Remote building seems to be broken at the moment, which is why the build host is set to “localhost”.