Nix flakes

What are Nix flakes?

A self-contained Nix module that takes inputs (can be from other flakes) and create outputs. It is comparable to Guix channels (or the NUR) in the way any arbitrary value can be exported, thus extending a Nix module in any direction the author can make it to. Also, it supercedes Nix channels as a way to manage your system.

So, why use flakes?

• Since it is self-contained, it is easier to compose and develop environments for projects.

• It is more declarative compared to Nix channels.

• Provides a structure for discoverability through exploring the output.

• In case you're using NixOS, it also provides an easier way to extend it with third-party custom modules.

Exploring a Nix flake

To get started with a flake, you can quickly create one with nix flake init. This will create flake.nix which is also required for Nix to recognize the project as a flake.

Here's the skeleton of a flake.

{
  description = "A basic flake.";
  inputs = {};
  outputs = {};
}

It is really just an attribute set that mainly deals with three attributes:

• description which is self-descriptive enough to see what's it for. ;p

• inputs which contains inputs (that are other flakes) to be used for...

• ...the outputs which is a set or a function that returns an attribute set to be exported.

Here's a real example of a basic flake.

{
  description = "A basic flake with some real inputs this time.";
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs";

    home-manager.url = "github:nix-community/home-manager";
    home-manager.inputs.nixpkgs.follows = "nixpkgs";
  };
  outputs = attrs@{ self, nixpkgs, home-manager, ... }: {
    homeManagerConfiguration = import ./hmUsers;
    packages.x86_64-linux = {
      hello = nixpkgs.pkgs.hello;
    };
  };
}

The flake requires other flakes from the nixpkgs and home-manager as indicated from the URL. This will get the latest revision of both inputs.

This is not ideal as it will get the latest revisions every time it requests the inputs. While you can pin the version by adding more information (e.g., nixpkgs.url = "github:NixOS/nixpkgs/nixos-21.11", home-manager.url = "github:nix-community/home-manager/781d25b315def05cd7ede3765226c54216f0b1fe"), this isn't really necessary for the most part as we have lockfiles to secure our dependencies version. These lockfiles can be found at flake.lock where complete metadata for the flakes are found.

Selected list of attributes for outputs

While you can export attributes of any type, there are common attributes you'll mostly see.

As an example, here's the flake of my NixOS configuration.

nix flake show github:foo-dogsquared/nixos-config | nix run nixpkgs#gnused -- 's/\x1b\[[0-9;]*m//g'

• defaultPackage.${system}.${package} (or packages.${system}.${package}) is mainly expected for packages. This allows for easy building — e.g., nix build nixpkgs#hello will refer to defaultPackage.${system}.hello. Another command that expects this is nix run ${PACKAGE} (e.g., nix run nixpkgs#hello).

• nixosConfigurations.${host} is a NixOS host configuration. Each attribute contain a set similar to the traditional set from /etc/nixos/configuration.nix. This is very beneficial for quickly installing only with flakes — e.g., nixos-install --flake github:foo-dogsquared/nixos-config#zilch will install with nixosConfigurations.zilch. However, attributes should be created with lib.nixosSystem from nixpkgs flake.

• nixosModules.${module} is a roam:NixOS modules, allowing you to extend NixOS further. These are expected to be similar NixOS modules from nixpkgs.

• templates.${name} is a template that has the attribute path and description. See Flake templates for more details about how it's used.

• devShell.${system} is expected to be a derivation (mostly with mkShell). This is the default development environment to be used. This is mostly expected for projects providing an easy way to bootstrap for development (e.g., with nix develop ${FLAKE}).

• devShells.${system}.${name} is an attribute set of derivations (mostly from mkShell). This is similar to devShell except this is where nix develop subcommand finds if an attribute name is given.

Flake templates

• Flakes can have templates to get started with. They can be used with nix flake init ${TEMPLATE}.

• You can export it in your flakes through the templates attribute. templates is expected to be an attribute set with each attribute representing a template.

• By default, we have the templates flake from the global registry pointed to NixOS/templates Git repo.

Nix registry

Per the Nix manual:

Flake registries are a convenience feature that allows you to refer to flakes using symbolic identifiers such as nixpkgs, rather than full URLs such as git://github.com/NixOS/nixpkgs.

Here's an example of the registry list with some overriden flakes such as the nixpkgs flake following from my NixOS configuration.

nix registry list

So how does a flake registry work?

• It is managed through nix registry subcommand or set nix.registry in your system configuration.

• Registries are primarily written as JSON files in certain files (e.g., $XDG_CONFIG_HOME/nix/registry, /etc/nix/registry.json). For more information, see the registry format from the manual. Unlike the traditional Nix channels, the inclusion of arbitrary files and their locations doesn't seem to affect the reproducibility since it is mostly used as a convenience feature after all.

• The flakes from default registry are mostly getting the latest revisions of the flake per invocation so it is best practice to pin them (e.g., nix registry pin, through nix.registry while setting the NixOS systems in flake.nix).

• There are primarily three registries to worry about: user, system, and global.

• This is also the reason it downloads something why each time you invoke a Nix-related command (e.g., nix search, nix edit).

More information about flakes

• We can modify our inputs. In the above example, we made home-manager to use our version of nixpkgs which will make it easier to sync.