Flakes: Difference between revisions

<languages />

'''Nix flakes''' are an [[Experimental Nix features|experimental feature]] first introduced in the 2.4 [[Nix]] release,{{Cite manual|nix|development/experimental-features|number=13.8|title=Experimental Features|subsection=xp-feature-flakes|subtitle=flakes}}{{Cite manual|nix|release-notes/rl-2.4|number=14.27|title=Release 2.4 (2021-11-01)}} aiming to address a number of areas of improvement for the Nix ecosystem: they provide a uniform structure for Nix projects, allow for pinning specific versions of each dependencies, and sharing these dependencies via lock files, and overall make it more convenient to write reproducible Nix expressions.

<!--T:183-->

A flake is a directory which directly contains a Nix file called <code>flake.nix</code>, that follows a very specific structure. Flakes introduce a URL-like syntax{{Cite manual|nix|command-ref/new-cli/nix3-flake|number=8.5.17|title=nix flake|subsection=url-like-syntax|subtitle=URL-like syntax}} for specifying remote resources. To simplify the URL syntax, flakes use a registry of symbolic identifiers,{{Cite manual|nix|command-ref/new-cli/nix3-registry|number=8.5.62|title=nix registry}} allowing the direct specification of resources through syntax such as <code>github:NixOS/nixpkgs</code>.

Flakes also allow for locking references and versions, which can then be queried and updated programatically via the inputs {{cite manual|nix|command-ref/new-cli/nix3-flake-lock|number=7.5.19|title=nix flake lock}}{{cite manual|nix|command-ref/new-cli/nix3-flake-info|number=7.5.17|title=nix flake info}}. Additionally, an experimental CLI utility accepts flake references for expressions that build, run, and deploy packages.{{Cite manual|nix|command-ref/new-cli/nix|number=8.5.1|title=nix}}

 

 

 

 

 

 

 

 

 

When using any [[Nix command|<code>nix</code> command]], add the following command-line options:

</translate>

<syntaxhighlight lang="shell">

</syntaxhighlight>

=== Enabling flakes permanently === <!--T:193-->

==== NixOS ==== <!--T:7-->

Add the following to the [[Overview_of_the_NixOS_Linux_distribution#Declarative_Configuration system configuration |NixOS configuration]]:

====Home Manager==== <!--T:10-->

Add the following to your [[Home Manager|home manager]] config:

</translate>

<syntaxhighlight lang="nix">

   nix.settings.experimental-features = [ "nix-command" "flakes" ];

<translate>

====Nix standalone==== <!--T:13-->

{{Note | The  [https://github.com/DeterminateSystems/nix-installer Determinate Nix Installer] enables flakes by default.}}

=== The nix flakes command ===

The {{ic|nix flake}} subcommand is described in {{Nix Manual|name=command reference page of the Nix manual|anchor=command-ref/new-cli/nix3-flake}}.

This flake produces a single flake output <code>packages</code>. And within that, <code>x86_64-linux</code> is a system-specifc attribute set. And within that, two package [[derivations]] <code>default</code> and <code>hello</code>. You can find outputs with the {{Nix Manual|name=show command|anchor=command-ref/new-cli/nix3-flake-show}} of a flake as shown below:

<syntaxhighlight lang="console">

        └───hello: package 'hello-2.12.2'

==== Development shells ==== <!--T:196-->

<!--T:197-->

A <code>devShell</code> is a Nix-provided [[Development_environment_with_nix-shell#nix develop|development environment]] defined within a flake. It lets you declare a reproducible shell environment with the tools, libraries, and environment variables you need for the development of a specific project. This is flake equivalent to defining a <code>nix-shell</code>.

<syntaxhighlight lang="nix">

  description = "Example flake with a devShell";

  <!--T:199-->

 

 

 

 

 

 

<syntaxHighlight lang=console>

$ nix build .#hello

 

== Flake schema == <!--T:27-->

 

=== Input schema === <!--T:31-->

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

=== Output schema === <!--T:42-->

 

<!--T:44-->

   nixosModules."<name>" = { config, ... }: { options = {}; config = {}; };

   nixosModules.default = { config, ... }: { options = {}; config = {}; };

== Core usage patterns == <!--T:208-->

=== Making your evaluations pure === <!--T:60-->

<!--T:61-->

Nix flakes are evaluated in a pure evaluation mode, meaning that access to the external environment is restricted to ensure reproducibility. To maintain purity when working with flakes, consider the following:

<!--T:62-->

* {{Nixpkgs Manual|name=fetchurl|anchor=#sec-pkgs-fetchers-fetchurl-inputs}} and {{Nixpkgs Manual|name=fetchzip|anchor=#sec-pkgs-fetchers-fetchzip-inputs}} require a <code>sha256</code> argument to be considered pure.

<!--T:156-->

* <code>builtins.currentSystem</code> is non-hermetic and impure as it reflects the host system performing the evauluation. This can usually be avoided by passing the system (i.e., x86_64-linux) explicitly to derivations requiring it.

<!--T:209-->

*  <code>builtins.getEnv</code> is also impure. Avoid reading from environment variables and likewise, do not reference files outside of the flake's directory.

=== Defining a flake for multiple architectures === <!--T:210-->

<!--T:211-->

Flakes force you to specify a program for each supported architecture. An example below shows how to write a flake that targets multiple architectures.

<!--T:212-->

<syntaxhighlight lang="nix">

   description = "A flake targeting multiple architectures";

inputs = {

    nixpkgs.url = "github:nixos/nixpkgs?ref=nixos-unstable";

  <!--T:214-->

outputs = { self, nixpkgs }: let

    systems = [ "x86_64-linux" "aarch64-linux" ];

    forAllSystems = f: builtins.listToAttrs (map (system: {

      value = f system;

    }) systems);

   in {

     packages = forAllSystems (system: let

      pkgs = nixpkgs.legacyPackages.${system};

    in {

       hello = pkgs.hello;

       default = pkgs.hello;

     });

</syntaxhighlight>

=== Using overlays === <!--T:216-->

To use [[Overlays]] with flakes, refer to [[Overlays#In a Nix flake]] page.

=== Enable unfree software === <!--T:129-->

To allow for [[Unfree software|unfree software]] in a flake project, you need to explicitly allow it by setting <code>config.allowUnree = true;</code> when importing Nixpkgs.

<!--T:219-->

<syntaxhighlight lang="nix">

   outputs = { self, nixpkgs, flake-compat }:

     let

       pkgs = import nixpkgs { inherit system; config.allowUnfree = true;};

      ...

</syntaxhighlight>  

== NixOS configuration with flakes == <!--T:220-->

<!--T:221-->

It is possible to manage a [[NixOS]] system configuration using flakes, gaining the benefits of reproducible, declarative inputs and streamlined updates.

<!--T:222-->

For details and examples, see [[NixOS system configuration#Defining NixOS as a flake]].

== Development tricks == <!--T:131-->

=== Automatically switch nix shells with direnv === <!--T:97-->

<!--T:98-->

It is possible to automatically activate different Nix shells when navigating between project directories by using [[Direnv]]. Additional Nix integration with Direnv can be achieved with [https://github.com/nix-community/nix-direnv nix-direnv].

=== Pushing Flakes to Cachix === <!--T:99-->

</translate>

https://docs.cachix.org/pushing#flakes

<translate>

=== Flake support in projects without flakes === <!--T:50-->

The [https://github.com/edolstra/flake-compat flake-compat] library provides a compatibility layer that allows projects using traditional <code>default.nix</code> and <code>shell.nix</code> files to operate with flakes. For more details and usage examples, see the [[Flake Compat]] page.

<!--T:223-->

Another project that allows consuming flakes from non-flake projects is [https://github.com/fricklerhandwerk/flake-inputs flake-inputs].

=== Accessing flakes from Nix expressions === <!--T:58-->

If you want to access a flake from within a regular Nix expression on a system that has flakes enabled, you can use something like <code>(builtins.getFlake "/path/to/directory").packages.x86_64-linux.default</code>, where 'directory' is the directory that contains your <code>flake.nix</code>.

=== Efficiently build multiple flake outputs === <!--T:224-->

<!--T:101-->

To push ''all'' flake outputs automatically, checkout [https://github.com/srid/devour-flake#usage devour-flake].

=== Build a package added in a PR === <!--T:161-->

</translate>

nix build github:nixos/nixpkgs?ref=pull/<PR_NUMBER>/head#<PACKAGE>

this allows building a package that has not yet been added to nixpkgs.

<!--T:132-->

note that this will download a full source tarball of nixpkgs. if you already have a local clone, using that may be faster due to delta compression:

</translate>

git fetch upstream pull/<PR_NUMBER>/head && git checkout FETCH_HEAD && nix build .#PACKAGE

<!--T:163-->

this allows building a package that has not yet been added to nixpkgs.

=== How to add a file locally in git but not include it in commits === <!--T:164-->

When a [[git]] folder exists, flake will only copy files added in git to maximize reproducibility (this way if you forgot to add a local file in your repo, you will directly get an error when you try to compile it). However, for development purpose you may want to create an alternative flake file, for instance containing configuration for your preferred editors as described [https://discourse.nixos.org/t/local-personal-development-tools-with-flakes/22714/8 here]… of course without committing this file since it contains only your own preferred tools. You can do so by doing something like that (say for a file called <code>extra/flake.nix</code>):

</translate>

git add --intent-to-add extra/flake.nix

git update-index --skip-worktree --assume-unchanged extra/flake.nix

=== Rapid iteration of a direct dependency === <!--T:135-->

One common pain point with using Nix as a development environment is the need to completely rebuild dependencies and re-enter the dev shell every time they are updated. The <code>nix develop --redirect <flake> <directory></code> command allows you to provide a mutable dependency to your shell as if it were built by Nix.

<!--T:136-->

Consider a situation where your executable, <code>consumexe</code>, depends on a library, <code>libdep</code>. You're trying to work on both at the same time, where changes to <code>libdep</code> are reflected in real time for <code>consumexe</code>. This workflow can be achieved like so:

</translate>

<syntaxHighlight lang=bash>

cd ~/libdep-src-checkout/

nix develop # Or `nix-shell` if applicable.

export prefix="./install" # configure nix to install it here

buildPhase   # build it like nix does

installPhase # install it like nix does

<!--T:166-->

Now that you've built the dependency, <code>consumexe</code> can take it as an input. '''In another terminal''':

</translate>

<syntaxHighlight lang=bash>

nix develop --redirect libdep ~/libdep-src-checkout/install

# Output should show ~/libdep-src-checkout/ so you know it worked

If Nix warns you that your redirected flake isn't actually used as an input to the evaluated flake, try using the <code>--inputs-from .</code> flag. If all worked well you should be able to <code>buildPhase && installPhase</code> when the dependency changes and rebuild your consumer with the new version ''without'' exiting the development shell.

== See also == <!--T:138-->

=== Official sources === <!--T:225-->

<!--T:139-->

* [https://nix.dev/concepts/flakes Flakes] - nix.dev

<!--T:176-->

* [https://nixos.org/manual/nix/unstable/command-ref/new-cli/nix3-flake.html Nix flake command reference manual] - Many additional details about flakes, and their parts.

* [https://github.com/NixOS/nix/blob/master/src/nix/flake.md spec describing flake inputs in more detail]

<!--T:168-->

* [https://github.com/NixOS/rfcs/pull/49 RFC 49] (2019) - Original flakes specification

=== Guides === <!--T:226-->

<!--T:169-->

* [https://jade.fyi/blog/flakes-arent-real/ Flakes aren't real and can't hurt you] (Jade Lovelace, 2024)

<!--T:170-->

* [https://github.com/ryan4yin/nixos-and-flakes-book NixOS & Flakes Book](Ryan4yin, 2023) - 🛠️ ❤️ An unofficial NixOS & Flakes book for beginners.

<!--T:171-->

* [https://xeiaso.net/blog/nix-flakes-1-2022-02-21 Nix Flakes: an Introduction] (Xe Iaso, 2022)

<!--T:172-->

* [https://serokell.io/blog/practical-nix-flakes Practical Nix Flakes] (Alexander Bantyev, 2021) - Intro article on working with Nix and Flakes

<!--T:173-->

* [https://www.tweag.io/blog/2020-05-25-flakes/ Nix Flakes, Part 1: An introduction and tutorial] (Eelco Dolstra, 2020)

* [https://www.tweag.io/blog/2020-07-31-nixos-flakes/ Nix Flakes, Part 3: Managing NixOS systems] (Eelco Dolstra, 2020)

* [https://www.youtube.com/watch?v=QXUlhnhuRX4&list=PLgknCdxP89RcGPTjngfNR9WmBgvD_xW0l Nix flakes 101: Introduction to nix flakes] (Jörg Thalheim, 2020) YouTube video

=== Useful flake modules === <!--T:227-->  

<!--T:179-->

* [[Flake Utils|flake-utils]]: Library to avoid some boiler-code when writing flakes

<!--T:228-->

* [[Flake Parts|flake-parts]]: Library to help write modular and organized flakes

<!--T:181-->