NixOS Wiki

Flakes: Difference between revisions

← Older edit
Visual
imported>NobbZ
→Super fast nix-shell: Use `devShells.default` instead
Marked this version for translation
 
(141 intermediate revisions by 67 users not shown)
Line 1: Line 1:
'''Nix Flakes''' are an upcoming feature of the Nix package manager.
<languages />


== See also ==
<translate>
<!--T:1-->
{{Cleanup}}


* [https://xeiaso.net/blog/nix-flakes-1-2022-02-21 Nix Flakes: an Introduction] 2022
<!--T:182-->
* [https://serokell.io/blog/practical-nix-flakes Practical Nix Flakes] - 2021: Intro article on working with Nix and Flakes
'''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.
* [https://github.com/numtide/flake-utils flake-utils: Library to avoid some boiler-code when writing flakes]
 
* [https://zimbatm.com/NixFlakes/#direnv-integration zimbat's direnv article]
<!--T:183-->
* [https://www.tweag.io/blog/2020-05-25-flakes/ Nix Flakes, Part 1: An introduction and tutorial]
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>.
* [https://www.tweag.io/blog/2020-06-25-eval-cache/ Nix Flakes, Part 2: Evaluation caching]
* [https://www.tweag.io/blog/2020-07-31-nixos-flakes/ Nix Flakes, Part 3: Managing NixOS systems]
* [https://www.youtube.com/watch?v=QXUlhnhuRX4&list=PLgknCdxP89RcGPTjngfNR9WmBgvD_xW0l Nix flakes 101: Introduction to nix flakes]
* [https://github.com/nix-community/todomvc-nix building Rust and Haskell flakes]


== Introduction ==
<!--T:184-->
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}}


Flakes allow you to specify your code's dependencies (e.g. remote Git repositories) in a declarative way, simply by listing them inside a <code>flake.nix</code> file:
<!--T:185-->
== Flake file structure ==
Minimally, a flake file contains a description of the flake, a set of input dependencies and an output. You can generate a very basic flake file at any time using nix flake init. This will populate the current directory with a file called flake.nix that will contain something akin to:
{{File|3=<nowiki>{
  description = "A very basic flake";


<syntaxHighlight lang=nix>
  <!--T:186-->
{
inputs = {
  inputs = {
     nixpkgs.url = "github:nixos/nixpkgs?ref=nixos-unstable";
     home-manager.url = "github:nix-community/home-manager";
   };
   };
}
</syntaxHighlight>


Each dependency gets then pinned, that is: its commit hash gets automatically stored into a file - named <code>flake.lock</code> - making it easy to, say, upgrade it:
  <!--T:187-->
outputs = { self, nixpkgs }: {
 
    <!--T:188-->
packages.x86_64-linux.hello = nixpkgs.legacyPackages.x86_64-linux.hello;
 
    <!--T:189-->
packages.x86_64-linux.default = self.packages.x86_64-linux.hello;
 
  <!--T:190-->
};
}</nowiki>|name=flake.nix|lang=nix}}
In the example above, you can see the description, the input specified as a GitHub repository with a specific branch (here <code>nixos/nixpkgs</code> on the <code>nixos-unstable</code> branch), and an output that makes use of the input. The output simply specifies that the flake contains one package for the x86_64 architecture called <code>hello</code>. Even if your flake's output wouldn't use its input (however, in practice, that is highly unlikely), the output still needs to be a Nix function.
{{Note|Flakes require you to specify its outputs for each architecture separately. For more information, read the related section below.}}
 
<!--T:191-->
=== Nix configuration ===
It is possible to override the global Nix configuration set in your <code>nix.conf</code> file for the purposes of evaluating a flake. This can be useful, for example, for setting up binary caches specific to certain projects, while keeping the global configuration untouched. The flake file can contain a nixConfig attribute with any relevant configuration settings supplied. For example, enabling the nix-community binary cache would be achieved by:
{{File|3=<nowiki>{
  ...
  nixConfig = {
    extra-substituters = [
      "https://nix-community.cachix.org"
    ];
    extra-trusted-public-keys = [
      "nix-community.cachix.org-1:...="
    ];
  }
}</nowiki>|name=flake.nix|lang=nix}}{{Note|If you are used to configuring your Nix settings via the NixOS configuration, these options are under <code>nix.settings</code> and not <code>nix</code>. For example, you cannot specify the automatic storage optimisation under <code>nix.optimisation.enable</code>.}}


<syntaxHighlight lang=console>
== Setup == <!--T:192-->
$ nix flake lock --update-input home-manager
</syntaxHighlight>


''(if you're familiar with modern packages managers like <code>cargo</code> or <code>npm</code>, then the overall mechanism shouldn't surprise you - Nix works in a similar way, although without a centralized repository.)''
=== Enabling flakes temporarily === <!--T:5-->


Flakes replace the nix-channels command and things like ad-hoc invocations of <code>builtins.fetchgit</code> - no more worrying about keeping your channels in sync, no more worrying about forgetting about a dependency deep down in your tree: everything's at hand right inside <code>flake.lock</code>.
<!--T:6-->
When using any [[Nix command|<code>nix</code> command]], add the following command-line options:
</translate>
<syntaxhighlight lang="shell">
--experimental-features 'nix-command flakes'
</syntaxhighlight>
<translate>
=== Enabling flakes permanently === <!--T:193-->


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


=== NixOS ===
<!--T:8-->
In NixOS this can be achieved with the following options in <code>configuration.nix</code>.
Add the following to the [[Overview_of_the_NixOS_Linux_distribution#Declarative_Configuration system configuration |NixOS configuration]]:


==== System-wide installation ====
</translate>
<syntaxHighlight lang=nix>
<syntaxHighlight lang=nix>
{ pkgs, ... }: {
   nix.settings.experimental-features = [ "nix-command" "flakes" ];
   nix = {
    package = pkgs.nixFlakes; # or versioned attributes like nixVersions.nix_2_8
    extraOptions = ''
      experimental-features = nix-command flakes
    '';
  };
}
</syntaxHighlight>
</syntaxHighlight>
<translate>


==== Installation as an extra command ====
====Home Manager==== <!--T:10-->
Add command <code>nixFlakes</code> that serves as a flakes-enabled alias to the <code>nix</code> command.


<syntaxHighlight lang=nix>
<!--T:11-->
{ pkgs, ... }: {
Add the following to your [[Home Manager|home manager]] config:
  environment.systemPackages = [
    (pkgs.writeShellScriptBin "nixFlakes" ''
      exec ${pkgs.nixFlakes}/bin/nix --experimental-features "nix-command flakes" "$@"
    '')
  ];
}


</syntaxHighlight>
</translate>
<syntaxhighlight lang="nix">
  nix.settings.experimental-features = [ "nix-command" "flakes" ];
</syntaxhighlight>
<translate>


=== Non-NixOS ===
====Nix standalone==== <!--T:13-->
On non-nixos systems, install <code>nixFlakes</code> in your environment:


<syntaxHighlight lang=console>
<!--T:14-->
$ nix-env -iA nixpkgs.nixFlakes
{{Note | The  [https://github.com/DeterminateSystems/nix-installer Determinate Nix Installer] enables flakes by default.}}
</syntaxHighlight>


Edit either <code>~/.config/nix/nix.conf</code> or <code>/etc/nix/nix.conf</code> and add:
<!--T:15-->
Add the following to <code>~/.config/nix/nix.conf</code> or <code>/etc/nix/nix.conf</code>:


</translate>
<syntaxHighlight lang=text>
<syntaxHighlight lang=text>
experimental-features = nix-command flakes  
experimental-features = nix-command flakes
</syntaxHighlight>
</syntaxHighlight>
<translate>
== Usage == <!--T:17-->
<!--T:20-->
{{Warning | Since contents of flake files are copied to the world-readable [[Nix_package_manager#Nix_store|Nix store]] folder, do not put any unencrypted secrets in flake files. You should instead use a [[Comparison of secret managing schemes|secret managing scheme]].}}
<!--T:146-->
{{Note | For flakes in [[git]] repositories, only files in the working tree will be copied to the store.


This is needed to expose the Nix 2.0 CLI and flakes support that are hidden behind feature-flags.
<!--T:22-->
Therefore, if you use <code>git</code> for your flake, ensure to <code>git add</code> any project files after you first create them.}}


Finally, if the Nix installation is in multi-user mode, don’t forget to restart the nix-daemon.
<!--T:64-->
=== The nix flakes command ===
{{Main|Nix (command)}}


== Basic project usage ==
<!--T:65-->
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}}.


{{warning | All files tracked by the version control system (e.g. git or mercurial) will be copied to the nix store when the flake is evaluated. So be careful when putting secrets in version control (which is not optimal by itself) around a flake.}}
<!--T:194-->
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:


In your repo, run <code>nix flake init</code> to generate the flake.nix file. Then run <code>git add flake.nix</code> to add it to the git staging area, otherwise nix will not recognize that the file exists.
<!--T:195-->
<syntaxhighlight lang="console">
$ nix flake show
└───packages
    └───x86_64-linux
        ├───default: package 'hello-2.12.2'
        └───hello: package 'hello-2.12.2'
</syntaxhighlight>


See also https://www.tweag.io/blog/2020-05-25-flakes/
==== Development shells ==== <!--T:196-->


To install a flake when using nix outside of nixOS, use <code>nix profile install /path/to/flake</code>. The path may also be an URL (e.g.: <code>nix profile install git+https://example.com/my-repo?dir=subdirectory</code>).
<!--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>.


== Flake schema ==
<!--T:198-->
<syntaxhighlight lang="nix">
{
  description = "Example flake with a devShell";


  <!--T:199-->
inputs.nixpkgs.url = "github:nixos/nixpkgs?ref=nixos-unstable";
  <!--T:200-->
outputs = { self, nixpkgs}:
    let
      system = "x86_64-linux";
      pkgs = import nixpkgs { inherit system; };
    in {
      devShells.x86_64-linux.default = pkgs.mkShell {
        buildInputs = with pkgs; [
          hello
        ];
        shellHook = ''
          echo "Welcome to the devShell!"
        '';
      };
    };
}
</syntaxhighlight>
<!--T:201-->
To enter the development shell environment:
<!--T:202-->
<syntaxhighlight lang="console">
$ nix develop
</syntaxhighlight>
<!--T:203-->
{{note|You don’t need to define a devShell to enter a development shell using nix develop.
If no devShell is defined, nix develop will drop you into an environment containing the default build dependencies of the flake (if any).}}
==== Build specific attributes in a flake repository ==== <!--T:102-->
<!--T:103-->
Running <code>nix build</code> will look in the <code>legacyPackages</code> and <code>packages</code> output attributes for the corresponding [[derivation]] and then your system architecture and build the default output. If you want to specify a build attribute in a flake repository, you can run <code>nix build .#<attr></code>. In the example above, if you wanted to build the <code>packages.x86_64-linux.hello</code> attribute, run:
<!--T:204-->
<syntaxHighlight lang=console>
$ nix build .#hello
</syntaxHighlight>
<!--T:205-->
Likewise, you can specify an attribute with the run command: <code>nix run .#hello</code> and the develop command: <code>nix develop .#hello</code>.
== Flake schema == <!--T:27-->
<!--T:28-->
The flake.nix file is a Nix file but that has special restrictions (more on that later).
The flake.nix file is a Nix file but that has special restrictions (more on that later).


It has 3 top-level attributes:
<!--T:29-->
It has 4 top-level attributes:


<!--T:30-->
* <code>description</code> is a string describing the flake.
* <code>description</code> is a string describing the flake.
<!--T:147-->
* <code>inputs</code> is an attribute set of all the dependencies of the flake. The schema is described below.
* <code>inputs</code> is an attribute set of all the dependencies of the flake. The schema is described below.
* <code>outputs</code> 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 ===
<!--T:148-->
* <code>outputs</code> is a function of one argument that takes an attribute set of all the realized inputs, and outputs another attribute set whose schema is described below.


This is not a complete schema but should be enough to get you started:
<!--T:149-->
* <code>nixConfig</code> is an attribute set of values which reflect the [https://nixos.org/manual/nix/stable/command-ref/conf-file.html values given to nix.conf]. This can extend the normal behavior of a user's nix experience by adding flake-specific configuration, such as a [[Binary Cache|binary cache]].


<syntaxHighlight lang=nix>
=== Input schema === <!--T:31-->
{
 
  inputs = {
<!--T:32-->
    # github example, also supported gitlab:
[https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-flake.html#flake-inputs The nix flake inputs manual].
    nixpkgs.url = "github:Mic92/nixpkgs/master";
 
    # git urls
<!--T:150-->
    git-example.url = "git+https://git.somehost.tld/user/path";
[https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-flake.html#flake-references The nix flake references manual].
    # local directories (for absolute paths you can omit 'path:')
 
    directory-example.url = "path:/path/to/repo";
<!--T:33-->
    # Use this for non-flakes
The inputs attribute defines the dependencies of the flake. For example, nixpkgs has to be defined as a dependency for a system flake in order for the system to build properly.
    bar.url = "github:foo/bar/branch";
 
    bar.flake = false;
<!--T:34-->
    # Overwrite inputs in a flake
[[Nixpkgs]] can be defined using the following code:
    # This is useful to use the same nixpkgs version in both flakes
 
    sops-nix.url = "github:Mic92/sops-nix";
</translate>
    sops-nix.inputs.nixpkgs.follows = "nixpkgs";
<code>inputs.nixpkgs.url = "github:NixOS/nixpkgs/<branch name>";</code>
    # Pin flakes to a specific revision
 
    nix-doom-emacs.url = "github:vlaci/nix-doom-emacs?rev=238b18d7b2c8239f676358634bfb32693d3706f3";
Nixpkgs can alternatively also point to an url cached by the NixOS organization:
    nix-doom-emacs.flake = false;
 
     # To use a subdirectory of a repo, pass dir=
<code>inputs.nixpkgs.url = "<nowiki>https://nixos.org/channels/nixpkgs-unstable/nixexprs.tar.xz</nowiki>";</code>
     nixpkgs.url = "github:foo/bar?dir=shu";
 
   }
In this example the input would point to the `nixpkgs-unstable` channel.
}
 
</syntaxHighlight>
<translate>
Also see [https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-flake.html#flake-references the nix flake manual].
 
<!--T:36-->
For any repository with its own flake.nix file, the website must also be defined. Nix knows where the nixpkgs repository is, so stating that it's on GitHub is unnecessary.
 
<!--T:37-->
For example, adding [[Hyprland]] as an input would look something like this:
 
</translate>
<code>inputs.hyprland.url = "github:hyprwm/Hyprland";</code>
<translate>
 
<!--T:39-->
If you want to make Hyprland follow the nixpkgs input to avoid having multiple versions of nixpkgs, this can be done using the following code:
 
</translate>
<code>inputs.hyprland.inputs.nixpkgs.follows = "nixpkgs";</code>
<translate>
 
<!--T:41-->
Using curly brackets({}), we can shorten all of this and put it in a table. The code will look something like this:
 
</translate>
<syntaxhighlight lang="nix">
inputs = {
  nixpkgs.url = "github:NixOS/nixpkgs/<branch name>";
  hyprland = {
     url = "github:hyprwm/Hyprland";
     inputs.nixpkgs.follows = "nixpkgs";
   };
};
</syntaxhighlight>
<translate>
 
<!--T:206-->
By default, Git submodules in package <code>src</code>'s won't get copied to the nix store, this may cause the build to fail. Flakes in Git repositories can declare that they need Git submodules to be enabled. Since Nix version [https://discourse.nixos.org/t/nix-2-27-0-released/62003 2.27], you can enable submodules by:
 
<!--T:207-->
<syntaxhighlight lang="nix">
  inputs.self.submodules = true;
</syntaxhighlight>


The bar input is then passed to the output schema
=== Output schema === <!--T:42-->


=== Output schema ===
<!--T:151-->
This is described in the nix package manager [https://github.com/NixOS/nix/blob/master/src/nix/flake-check.md src/nix/flake-check.md].


This is described in the nix package manager [https://github.com/NixOS/nix/blob/master/src/nix/flake.cc src/nix/flake.cc] in CmdFlakeCheck.
<!--T:43-->
Once the inputs are resolved, they're passed to the function `outputs` along with with `self`, which is the directory of this flake in the store. `outputs` returns the outputs of the flake, according to the following schema.


<!--T:44-->
Where:
Where:
 
<!--T:45-->
* <code><system></code> is something like "x86_64-linux", "aarch64-linux", "i686-linux", "x86_64-darwin"
* <code><system></code> is something like "x86_64-linux", "aarch64-linux", "i686-linux", "x86_64-darwin"
* <code><attr></code> is an attribute name like "hello".
 
<!--T:152-->
* <code><name></code> is an attribute name like "hello".
 
<!--T:153-->
* <code><flake></code> is a flake name like "nixpkgs".
* <code><flake></code> is a flake name like "nixpkgs".
<!--T:154-->
* <code><store-path></code> is a <code>/nix/store..</code> path
* <code><store-path></code> is a <code>/nix/store..</code> path


</translate>
<syntaxHighlight lang=nix>
<syntaxHighlight lang=nix>
{ self, ... }@inputs:
{ self, ... }@inputs:
Line 163: Line 315:
   apps."<system>".default = { type = "app"; program = "..."; };
   apps."<system>".default = { type = "app"; program = "..."; };


  # Formatter (alejandra, nixfmt or nixpkgs-fmt)
  formatter."<system>" = derivation;
   # Used for nixpkgs packages, also accessible via `nix build .#<name>`
   # Used for nixpkgs packages, also accessible via `nix build .#<name>`
   legacyPackages."<system>"."<name>" = derivation;
   legacyPackages."<system>"."<name>" = derivation;
Line 168: Line 322:
   overlays."<name>" = final: prev: { };
   overlays."<name>" = final: prev: { };
   # Default overlay
   # Default overlay
   overlays.default = {};
   overlays.default = final: prev: { };
   # Nixos module, consumed by other flakes
   # Nixos module, consumed by other flakes
   nixosModules."<name>" = { config }: { options = {}; config = {}; };
   nixosModules."<name>" = { config, ... }: { options = {}; config = {}; };
   # Default module
   # Default module
   nixosModules.default = {};
   nixosModules.default = { config, ... }: { options = {}; config = {}; };
   # Used with `nixos-rebuild --flake .#<hostname>`
   # Used with `nixos-rebuild switch --flake .#<hostname>`
   # nixosConfigurations."<hostname>".config.system.build.toplevel must be a derivation
   # nixosConfigurations."<hostname>".config.system.build.toplevel must be a derivation
   nixosConfigurations."<hostname>" = {};
   nixosConfigurations."<hostname>" = {};
Line 191: Line 345:
}
}
</syntaxHighlight>
</syntaxHighlight>
<translate>


<!--T:48-->
You can also define additional arbitrary attributes, but these are the outputs that Nix knows about.
You can also define additional arbitrary attributes, but these are the outputs that Nix knows about.


== Using flakes project from a legacy Nix ==
== Core usage patterns == <!--T:208-->
There is a [https://github.com/edolstra/flake-compat flake-compat] library you can use to shim legacy <code>default.nix</code> and <code>shell.nix</code> files. It will download the inputs of the flake, pass them to the flake’s <code>outputs</code> function and return an attribute set containing <code>defaultNix</code> and <code>shellNix</code> attributes. The attributes will contain the output attribute set with an extra <code>default</code> attribute pointing to current platform’s <code>defaultPackage</code> (resp. <code>devShell</code> for <code>shellNix</code>).


Place the following into <code>default.nix</code> (for <code>shell.nix</code>, replace <code>defaultNix</code> with <code>shellNix</code>) to use the shim:
=== Making your evaluations pure === <!--T:60-->


<syntaxHighlight lang=nix>
<!--T:61-->
(import (
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:
  fetchTarball {
    url = "https://github.com/edolstra/flake-compat/archive/12c64ca55c1014cdc1b16ed5a804aa8576601ff2.tar.gz";
    sha256 = "0jm6nzb83wa6ai17ly9fzpqc40wg1viib8klq8lby54agpl213w5"; }
) {
  src =  ./.;
}).defaultNix
</syntaxHighlight>


You can also use the lockfile to make updating the hashes easier using <code>nix flake lock --update-input flake-compat</code>. Add the following to your <code>flake.nix</code>:
<!--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.


<syntaxHighlight lang=nix>
<!--T:156-->
  inputs.flake-compat = {
* <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.
    url = "github:edolstra/flake-compat";
    flake = false;
  };
</syntaxHighlight>


and add <code>flake-compat</code> to the arguments of <code>outputs</code> attribute. Then you will be able to use <code>default.nix</code> like the following:
<!--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.


<syntaxHighlight lang=nix>
=== Defining a flake for multiple architectures === <!--T:210-->
(import (
  let
    lock = builtins.fromJSON (builtins.readFile ./flake.lock);
  in fetchTarball {
    url = "https://github.com/edolstra/flake-compat/archive/${lock.nodes.flake-compat.locked.rev}.tar.gz";
    sha256 = lock.nodes.flake-compat.locked.narHash; }
) {
  src =  ./.;
}).defaultNix
</syntaxHighlight>


== Making your evaluations pure ==
<!--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.


Nix flakes run in pure evaluation mode, which is underdocumented. Some tips for now:
<!--T:212-->
<syntaxhighlight lang="nix">
{
  description = "A flake targeting multiple architectures";


* fetchurl and fetchtar [https://github.com/NixOS/nix/blob/36c4d6f59247826dde32ad2e6b5a9471a9a1c911/src/libexpr/primops/fetchTree.cc#L201 require] a sha256 argument to be considered pure.
  <!--T:213-->
* builtins.currentSystem is non-hermetic and impure. This can usually be avoided by passing the system (i.e., x86_64-linux) explicitly to derivations requiring it.
inputs = {
* Imports from channels like <code><nixpkgs></code> can be made pure by instead importing from the <code>output</code> function in <code>flake.nix</code>, where the arguments provide the store path to the flake's inputs:
    nixpkgs.url = "github:nixos/nixpkgs?ref=nixos-unstable";
  };


<syntaxHighlight lang=nix>
  <!--T:214-->
outputs = { self, nixpkgs, ... }:
outputs = { self, nixpkgs }: let
  {
    systems = [ "x86_64-linux" "aarch64-linux" ];
     nixosConfigurations.machine = nixpkgs.lib.nixosSystem {
     forAllSystems = f: builtins.listToAttrs (map (system: {
       system = "x86_64-linux";
       name = system;
       modules = [
       value = f system;
        (nixpkgs + "/nixos/modules/<some-module>.nix")
    }) systems);
        ./machine.nix
  in {
       ];
    packages = forAllSystems (system: let
     };
      pkgs = nixpkgs.legacyPackages.${system};
    in {
      hello = pkgs.hello;
       default = pkgs.hello;
     });
   };
   };
</syntaxHighlight>
}
</syntaxhighlight>


== The nix flakes command ==
<!--T:215-->
You can also use third-parties projects like [[Flake Utils|flake-utils]] or [[Flake Parts|flake-parts]] that automatically provide code to avoid this boilerplate. To avoid re-defining the program multiple times, refer to [[Flake Utils#Defining a flake for multiple architectures]]


The {{ic|nix flake}} subcommand is described in [https://nixos.org/manual/nix/unstable/command-ref/new-cli/nix3-flake.html command reference page of the unstable manual] and here in the [[Nix command/flake]] article.
=== Using overlays === <!--T:216-->


== Using nix flakes with NixOS ==
<!--T:217-->
To use [[Overlays]] with flakes, refer to [[Overlays#In a Nix flake]] page.


nixos-rebuild switch will read its configuration from <code>/etc/nixos/flake.nix</code> if it is present.
=== Enable unfree software === <!--T:129-->


A basic nixos flake.nix could look like this:
<!--T:218-->
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.


<syntaxHighlight lang=nix>
<!--T:219-->
<syntaxhighlight lang="nix">
{
{
   outputs = { self, nixpkgs }: {
  inputs.nixpkgs.url = "github:nixos/nixpkgs?ref=nixos-unstable";
     # replace 'joes-desktop' with your hostname here.
   outputs = { self, nixpkgs, flake-compat }:
    nixosConfigurations.joes-desktop = nixpkgs.lib.nixosSystem {
     let
       system = "x86_64-linux";
       system = "x86_64-linux";
       modules = [ ./configuration.nix ];
       pkgs = import nixpkgs { inherit system; config.allowUnfree = true;};
    in {
      ...
     };
     };
  };
}
}
</syntaxHighlight>
</syntaxhighlight>  
If you want to pass on the flake inputs to external configuration files, you can use the <code>specialArgs</code> attribute:
<syntaxHighlight lang=nix>
{
  inputs.nixpkgs.url = github:NixOS/nixpkgs;
  inputs.home-manager.url = github:nix-community/home-manager;
 
  outputs = { self, nixpkgs, ... }@attrs: {
    nixosConfigurations.fnord = nixpkgs.lib.nixosSystem {
      system = "x86_64-linux";
      specialArgs = attrs;
      modules = [ ./configuration.nix ];
    };
  };
}
</syntaxHighlight>
Then, you can access the flake inputs from the file <code>configuration.nix</code> like this:
<syntaxHighlight lang=nix>
{ config, lib, nixpkgs, home-manager, ... }: {
  # do something with home-manager here, for instance:
  imports = [ home-manager.nixosModule ];
  ...
}
</syntaxHighlight>


nixos-rebuild also allows to specify different flake using the <code>--flake</code> flag (# is optional):
== NixOS configuration with flakes == <!--T:220-->


<syntaxHighlight lang=console>
<!--T:221-->
$ sudo nixos-rebuild switch --flake '.#'
It is possible to manage a [[NixOS]] system configuration using flakes, gaining the benefits of reproducible, declarative inputs and streamlined updates.
</syntaxHighlight>


By default nixos-rebuild will use the currents system hostname to lookup the right nixos configuration in <code>nixosConfigurations</code>. You can also override this by using appending it to the flake parameter:
<!--T:222-->
For details and examples, see [[NixOS system configuration#Defining NixOS as a flake]].


<syntaxHighlight lang=console>
== Development tricks == <!--T:131-->
$ sudo nixos-rebuild switch --flake '/etc/nixos#joes-desktop'
</syntaxHighlight>
 
To switch a remote configuration, use:
<syntaxHighlight lang=console>
$ nixos-rebuild --flake .#mymachine \
  --target-host mymachine-hostname --build-host localhost \
  switch
</syntaxHighlight>
{{warning|Remote building seems to be broken at the moment, which is why the build host is set to “localhost”.}}


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


One of the nix feature of the Flake edition is that Nix evaluations are cached.
<!--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].


Let’s say that your project has a <code>shell.nix</code> file that looks like this:
=== Pushing Flakes to Cachix === <!--T:99-->


<syntaxHighlight lang=nix>
</translate>
{ pkgs ? import <nixpkgs> { } }:
https://docs.cachix.org/pushing#flakes
with pkgs;
<translate>
mkShell {
  buildInputs = [
    nixpkgs-fmt
  ];
 
  shellHook = ''
    # ...
  '';
}
</syntaxHighlight>
 
Running nix-shell can be a bit slow and take 1-3 seconds.
 
Now create a <code>flake.nix</code> file in the same repository:
 
<syntaxHighlight lang=nix>
{
  description = "my project description";


  inputs.flake-utils.url = "github:numtide/flake-utils";
=== Flake support in projects without flakes === <!--T:50-->


  outputs = { self, nixpkgs, flake-utils }:
<!--T:51-->
    flake-utils.lib.eachDefaultSystem
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.
      (system:
        let pkgs = nixpkgs.legacyPackages.${system}; in
        {
          devShells.default = import ./shell.nix { inherit pkgs; };
        }
      );
}
</syntaxHighlight>


Run git add flake.nix so that Nix recognizes it.
<!--T:223-->
Another project that allows consuming flakes from non-flake projects is [https://github.com/fricklerhandwerk/flake-inputs flake-inputs].


And finally, run <code>nix develop</code>. This is what replaces the old nix-shell invocation.
=== Accessing flakes from Nix expressions === <!--T:58-->


Exit and run again, this command should now be super fast.
<!--T:59-->
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>.


{{warning|TODO: there is an alternative version where the defaultPackage is a pkgs.buildEnv that contains all the dependencies. And then nix shell is used to open the environment.}}
=== Efficiently build multiple flake outputs === <!--T:224-->


=== Direnv integration ===
<!--T:101-->
To push ''all'' flake outputs automatically, checkout [https://github.com/srid/devour-flake#usage devour-flake].


Assuming that the flake defines a <code>devShell</code> output attribute and that you are using direnv. Here is how to replace the old use nix stdlib function with the faster flake version:
=== Build a package added in a PR === <!--T:161-->


<syntaxHighlight lang=sh>
</translate>
use_flake() {
<syntaxHighlight>
  watch_file flake.nix
nix build github:nixos/nixpkgs?ref=pull/<PR_NUMBER>/head#<PACKAGE>
  watch_file flake.lock
  eval "$(nix print-dev-env --profile "$(direnv_layout_dir)/flake-profile")"
}
</syntaxHighlight>
</syntaxHighlight>
<translate>


Copy this in <code>~/.config/direnv/lib/use_flake.sh</code> or in <code>~/.config/direnv/direnvrc</code>
<!--T:162-->
or directly in your project specific <code>.envrc</code>.
this allows building a package that has not yet been added to nixpkgs.


Note: You may not need to create <code>use_flake()</code> yourself; as of [https://github.com/direnv/direnv/releases/tag/v2.29.0#:~:text=add%20use_flake%20function direnv 2.29,] <code>use flake</code> is part of direnv's standard library.
<!--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:


With this in place, you can now replace the use nix invocation in the <code>.envrc</code> file with <code>use flake</code>:
</translate>
 
<syntaxHighlight>
<syntaxHighlight lang=text>
git fetch upstream pull/<PR_NUMBER>/head && git checkout FETCH_HEAD && nix build .#PACKAGE
# .envrc
use flake
</syntaxHighlight>
</syntaxHighlight>
<translate>


The nice thing about this approach is that evaluation is cached.
<!--T:163-->
 
this allows building a package that has not yet been added to nixpkgs.
==== Optimize the reloads ====


Nix Flakes has a Nix evaluation caching mechanism. Is it possible to expose that somehow to automatically trigger direnv reloads?
=== How to add a file locally in git but not include it in commits === <!--T:164-->


With the previous solution, direnv would only reload if the flake.nix or flake.lock files have changed. This is not completely precise as the flake.nix file might import other files in the repository.
<!--T:133-->
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>):


==== Setting the bash prompt like nix-shell ====
</translate>
 
<syntaxHighlight>
A [https://github.com/NixOS/nix/pull/4189 new experimental feature of flakes] allow to setup a bash-prompt per flake:
git add --intent-to-add extra/flake.nix
<syntaxHighlight lang=nix>
git update-index --skip-worktree --assume-unchanged extra/flake.nix
{
  description = "...";
  nixConfig.bash-prompt = "\[nix-develop\]$ ";
  ...
}
</syntaxHighlight>
</syntaxHighlight>
<translate>


Otherwise it's also possible to set the <code>nix develop</code> bash prompt system wide using the [https://nixos.org/manual/nix/unstable/command-ref/conf-file.html nix.conf option bash-prompt]. (On nixos I think it is set in <code>nix.extraOptions</code>)
=== Rapid iteration of a direct dependency === <!--T:135-->


== Pushing Flakes to Cachix ==
<!--T:165-->
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.


https://docs.cachix.org/pushing#flakes
<!--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:


== Build specific attributes in a flake repository ==
</translate>
 
<syntaxHighlight lang=bash>
When in the repository top-level, run <code>nix build .#<attr></code>. It will look in the <code>legacyPackages</code> and <code>packages</code> output attributes for the corresponding derivation.
cd ~/libdep-src-checkout/
 
nix develop # Or `nix-shell` if applicable.
Eg, in nixpkgs:
export prefix="./install" # configure nix to install it here
 
buildPhase  # build it like nix does
<syntaxHighlight lang=console>
installPhase # install it like nix does
$ nix build .#hello
</syntaxHighlight>
</syntaxHighlight>
<translate>


=== Building flakes from a Git repo url with submodules ===
<!--T:166-->
Now that you've built the dependency, <code>consumexe</code> can take it as an input. '''In another terminal''':


As per nix 2.9.1, git submodules in package <code>src</code>s won't get copied to the nix store, this may cause the build to fail.  To workaround this, use:
</translate>
 
<syntaxHighlight lang=bash>
<syntaxHighlight lang=console>
cd ~/consumexe-src-checkout/
$ nix build .?submodules=1#hello
nix develop --redirect libdep ~/libdep-src-checkout/install
echo $buildInputs | tr " " "\n" | grep libdep
# Output should show ~/libdep-src-checkout/ so you know it worked
</syntaxHighlight>
</syntaxHighlight>
<translate>


See: https://github.com/NixOS/nix/pull/5434
<!--T:167-->
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.


== Importing packages from multiple channels ==
== See also == <!--T:138-->


You can import packages from different channels by creating an overlay on the ''pkgs'' attribute :
=== Official sources === <!--T:225-->
<syntaxHighlight lang=nix>
let
  overlay-unstable = final: prev: {
    unstable = nixpkgs-unstable.legacyPackages.${prev.system}; # considering nixpkgs-unstable is an input registered before.
  };
in nixpkgs.overlays = [ overlay-unstable ]; # we assign the overlay created before to the overlays of nixpkgs.
</syntaxHighlight>
should make a package accessible through <code>pkgs.unstable.package</code>
For example, a NixOS config flake skeleton could be as follows:
<syntaxHighlight lang=nix>
{
  description = "NixOS configuration with two or more channels";


  inputs = {
<!--T:139-->
    nixpkgs.url = "nixpkgs/nixos-21.11";
* [https://nix.dev/concepts/flakes Flakes] - nix.dev
    nixpkgs-unstable.url = "nixpkgs/nixos-unstable";
  };


  outputs = { self, nixpkgs, nixpkgs-unstable }:
<!--T:176-->
    let
* [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.
      system = "x86_64-linux";
      overlay-unstable = final: prev: {
        unstable = nixpkgs-unstable.legacyPackages.${prev.system};
        # use this variant if unfree packages are needed:
        # unstable = import nixpkgs-unstable {
        #  inherit system;
        #  config.allowUnfree = true;
        # };


      };
<!--T:178-->
    in {
* [https://github.com/NixOS/nix/blob/master/src/nix/flake.md spec describing flake inputs in more detail]
      nixosConfigurations."<hostname>" = nixpkgs.lib.nixosSystem {
        inherit system;
        modules = [
          # Overlays-module makes "pkgs.unstable" available in configuration.nix
          ({ config, pkgs, ... }: { nixpkgs.overlays = [ overlay-unstable ]; })
          ./configuration.nix
        ];
      };
    };
}
 
# NixOS configuration.nix, can now use "pkgs.package" or "pkgs.unstable.package"
{ config, pkgs, ... }: {
  environment.systemPackages = [pkgs.firefox pkgs.unstable.chromium];
  # ...
}
</syntaxHighlight>
Same can be done with the NURs, as it already has an ''overlay'' attribute in the flake.nix of the project, you can just add <syntaxHighlight lang=nix>nixpkgs.overlays = [ nur.overlay ];</syntaxHighlight>
 
If the variable <code>nixpkgs</code> points to the flake, you can also define <code>pkgs</code> with overlays with:
 
<syntaxHighlight lang=nix>
pkgs = import nixpkgs { overlays = [ /*the overlay in question*/ ]; };
</syntaxHighlight>


== Getting ''Instant'' System Flakes Repl ==
<!--T:168-->
* [https://github.com/NixOS/rfcs/pull/49 RFC 49] (2019) - Original flakes specification


How to get a nix repl out of your system flake:
=== Guides === <!--T:226-->


<syntaxHighlight lang=text>
<!--T:169-->
# nix repl
* [https://jade.fyi/blog/flakes-arent-real/ Flakes aren't real and can't hurt you] (Jade Lovelace, 2024)
>> :lf /etc/nixos
>> nixosConfigurations.myhost.config
{ ... }
</syntaxHighlight>


Or out of your current flake:
<!--T:170-->
<syntaxHighlight lang=text>
* [https://github.com/ryan4yin/nixos-and-flakes-book NixOS & Flakes Book](Ryan4yin, 2023) - 🛠️ ❤️ An unofficial NixOS & Flakes book for beginners.
# nix repl
>> :lf .#
</syntaxHighlight>


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


However, this won't be instant upon evaluation if any file changes have been done since your last configuration rebuild. Instead, if one puts:
<!--T:172-->
* [https://serokell.io/blog/practical-nix-flakes Practical Nix Flakes] (Alexander Bantyev, 2021) - Intro article on working with Nix and Flakes


<syntaxHighlight lang=nix>
<!--T:173-->
nix.nixPath = let path = toString ./.; in [ "repl=${path}/repl.nix" "nixpkgs=${inputs.nixpkgs}" ];
* [https://www.tweag.io/blog/2020-05-25-flakes/ Nix Flakes, Part 1: An introduction and tutorial] (Eelco Dolstra, 2020)
</syntaxHighlight>


In their system <code>flake.nix</code> configuration file, and includes the following file in their root directory flake as <code>repl.nix</code>:
<!--T:174-->
* [https://www.tweag.io/blog/2020-06-25-eval-cache/ Nix Flakes, Part 2: Evaluation caching] (Eelco Dolstra, 2020)


<syntaxHighlight lang=nix>
<!--T:175-->
let
* [https://www.tweag.io/blog/2020-07-31-nixos-flakes/ Nix Flakes, Part 3: Managing NixOS systems] (Eelco Dolstra, 2020)
  flake = builtins.getFlake (toString ./.);
  nixpkgs = import <nixpkgs> { };
in
{ inherit flake; }
// flake
// builtins
// nixpkgs
// nixpkgs.lib
// flake.nixosConfigurations
</syntaxHighlight>


(Don't forget to <code>git add repl.nix && nixos-rebuild  switch --flake "/etc/nixos"</code>)
<!--T:177-->
Then one can run (or bind a shell alias):
* [https://www.youtube.com/watch?v=QXUlhnhuRX4&list=PLgknCdxP89RcGPTjngfNR9WmBgvD_xW0l Nix flakes 101: Introduction to nix flakes] (Jörg Thalheim, 2020) YouTube video


<syntaxHighlight lang=bash>
=== Useful flake modules === <!--T:227-->  
source /etc/set-environment && nix repl $(echo $NIX_PATH | perl -pe 's|.*(/nix/store/.*-source/repl.nix).*|\1|')</syntaxHighlight>


This will launch a repl with access to <code>nixpkgs</code>, <code>lib</code>, and the <code>flake</code> options in a split of a second.
<!--T:179-->
* [[Flake Utils|flake-utils]]: Library to avoid some boiler-code when writing flakes


== Enable unfree software ==
<!--T:228-->
* [[Flake Parts|flake-parts]]: Library to help write modular and organized flakes


Because flake evalutations are hermetic, they will ignore the system configuration on nonfree software and the <code>NIXPKGS_ALLOW_UNFREE</code> environment variable by default.
<!--T:229-->
* [[Flake Compat|flake-compat]]: A compatibility layer for flakes


To use nonfree software with CLI tools like <code>nix shell</code> or <code>nix run</code>, the <code>--impure</code> flag must be used for Nixpkgs to access the current environment variables:
<!--T:181-->
<syntaxHighlight lang=console>
* [https://github.com/nix-community/todomvc-nix building Rust and Haskell flakes]
$ NIXPKGS_ALLOW_UNFREE=1 nix run --impure nixpkgs#discord
</syntaxHighlight>


To use nonfree software in a flake, add <code>nixpkgs</code> as an input in your flake and import it with the <code>allowUnfree</code> option:
<!--T:230-->
<syntaxHighlight lang=nix>
{{references}}
pkgs = import nixpkgs { config = { allowUnfree = true; }; };
</syntaxHighlight>
 
=== Enable unfree software in home-manager ===
 
If you want to install software using home-manager via nix flakes in non NixOS systems (like darwin) you can use the home-manager <code>nixpkgs.config</code> option for example
 
<syntaxHighlight lang=nix>
nixpkgs.config.allowUnfree = true;
</syntaxHighlight>
 
== Official Nix links ==
 
These are links out to information from official Nix sources on Flakes.
 
* [https://github.com/NixOS/rfcs/pull/49 Eelco Dolstra's RFC #49] - This is the initial RFC for Flakes to be included in NixOS, from July 2019
* [https://github.com/NixOS/nix/blob/master/src/nix/flake.md spec describing flake inputs in more detail]


</translate>
[[Category:Software]]
[[Category:Software]]
[[Category:Nix]]
[[Category:Nix]]
[[Category:Nix Language]]
[[Category:Flakes]]
[[Category:Flakes]]
Retrieved from "https://wiki.nixos.org/wiki/Flakes"