Official NixOS Wiki

Flakes: Difference between revisions

← Older edit
VisualWikitext
Pigs (talk | contribs)
260 edits
m Link to direnv page
m Fixed indentation in the example flake.nix
 
(19 intermediate revisions by 9 users not shown)
Line 1: Line 1:
<languages />
<languages />
{{Cleanup}}
<translate>
<translate>
<!--T:1-->
<!--T:182-->
'''Nix flakes''' is an [https://nixos.org/manual/nix/stable/development/experimental-features.html experimental feature] that was introduced with Nix 2.4 ([https://nixos.org/manual/nix/unstable/release-notes/rl-2.4.html see release notes]).
'''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>.
 
<!--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}}
 
== Flake file structure == <!--T:185-->
 
<!--T:231-->
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:
</translate>


====Introduction==== <!--T:2-->
{{File|3=<nowiki>{
  description = "A very basic flake";
 
  inputs = {
    nixpkgs.url = "github:nixos/nixpkgs?ref=nixos-unstable";
  };


<!--T:3-->
  outputs = { self, nixpkgs }: {
Nix flakes enforce a uniform structure for Nix projects, pin versions of their dependencies in a lock file, and make it more convenient to write reproducible Nix expressions.
    packages.x86_64-linux = {
      default = self.packages.x86_64-linux.hello;
      hello = nixpkgs.legacyPackages.x86_64-linux.hello;
    };
  };
}</nowiki>|name=flake.nix|lang=nix}}


<!--T:4-->
<translate>
* A [https://nixos.org/manual/nix/unstable/command-ref/new-cli/nix3-flake.html#description flake] refers to a file-system tree whose root directory contains the Nix file specification called <code>flake.nix</code>.
<!--T:190-->
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.


<!--T:141-->
<!--T:232-->
* The contents of <code>flake.nix</code> file follow a uniform naming schema for declaring packages and their dependencies in the Nix language.
{{Note|Flakes require you to specify its outputs for each architecture separately. For more information, read the related section below.}}


<!--T:142-->
=== Nix configuration === <!--T:191-->
*  Flakes introduce a [https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-flake.html#flake-references URL-like syntax] for specifying remote sources.


<!--T:143-->
<!--T:233-->
* To simplify the long URL syntax with shorter names, [https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-registry.html flakes uses a registry] of symbolic identifiers.
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:
</translate>


<!--T:144-->
{{File|3=<nowiki>{
* Flakes also allow for locking references and versions that can then be queried and updated programmatically.
  ...
  nixConfig = {
    extra-substituters = [
      "https://nix-community.cachix.org"
    ];
    extra-trusted-public-keys = [
      "nix-community.cachix.org-1:...="
    ];
  }
}</nowiki>|name=flake.nix|lang=nix}}


<!--T:145-->
<translate>
* An [https://nixos.org/manual/nix/stable/command-ref/new-cli/nix.html experimental command-line interface] accepts flake references for expressions that build, run, and deploy packages.
<!--T:234-->
{{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>.}}


=== Enabling flakes ===
== Setup == <!--T:192-->


====Enable flakes temporarily==== <!--T:5-->
=== Enabling flakes temporarily === <!--T:5-->


<!--T:6-->
<!--T:6-->
When using any <code>nix</code> command, add the following command-line options:
When using any [[Nix command|<code>nix</code> command]], add the following command-line options:
</translate>
</translate>
<syntaxhighlight lang="shell">
<syntaxhighlight lang="shell">
  --experimental-features 'nix-command flakes'
  --experimental-features 'nix-command flakes'
</syntaxhighlight>
</syntaxhighlight>
<translate>
<translate>
=== Enabling flakes permanently === <!--T:193-->


====Enable flakes permanently in NixOS==== <!--T:7-->
==== NixOS ==== <!--T:7-->


<!--T:8-->
<!--T:8-->
Add the following to the [[Overview_of_the_NixOS_Linux_distribution#Declarative_Configuration system configuration |NixOS configuration]]:
Add the following to the [[Overview_of_the_NixOS_Linux_distribution#Declarative_Configuration system configuration |NixOS configuration]]:
</translate>


</translate>
<syntaxHighlight lang=nix>
<syntaxHighlight lang=nix>
   nix.settings.experimental-features = [ "nix-command" "flakes" ];
   nix.settings.experimental-features = [ "nix-command" "flakes" ];
</syntaxHighlight>
</syntaxHighlight>
<translate>
<translate>
 
====Home Manager==== <!--T:10-->
====With Home Manager==== <!--T:10-->


<!--T:11-->
<!--T:11-->
Add the following to your [[Home Manager|home manager]] config:
Add the following to your [[Home Manager|home manager]] config:
</translate>


</translate>
<syntaxhighlight lang="nix">
<syntaxhighlight lang="nix">
   nix.settings.experimental-features = [ "nix-command" "flakes" ];
   nix.settings.experimental-features = [ "nix-command" "flakes" ];
</syntaxhighlight>
</syntaxhighlight>
<translate>
<translate>
 
====Nix standalone==== <!--T:13-->
====Other Distros, without Home Manager==== <!--T:13-->


<!--T:14-->
<!--T:14-->
Line 68: Line 107:
<!--T:15-->
<!--T:15-->
Add the following to <code>~/.config/nix/nix.conf</code> or <code>/etc/nix/nix.conf</code>:
Add the following to <code>~/.config/nix/nix.conf</code> or <code>/etc/nix/nix.conf</code>:
</translate>


</translate>
<syntaxHighlight lang=text>
<syntaxHighlight lang=text>
experimental-features = nix-command flakes
experimental-features = nix-command flakes
</syntaxHighlight>
</syntaxHighlight>
<translate>
<translate>
 
== Usage == <!--T:17-->
===Basic Usage of Flake=== <!--T:17-->


<!--T:20-->
<!--T:20-->
{{Warning | Since contents of flake files are copied to the world-readable 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]].}}
{{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-->
<!--T:146-->
Line 86: Line 125:
Therefore, if you use <code>git</code> for your flake, ensure to <code>git add</code> any project files after you first create them.}}
Therefore, if you use <code>git</code> for your flake, ensure to <code>git add</code> any project files after you first create them.}}


====Generate flake.nix file==== <!--T:24-->
=== The nix flakes command === <!--T:64-->
</translate>
 
{{Main|Nix (command)}}


<!--T:25-->
<translate>
To initialize a flake, run the following flake command in the project directory:
<!--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}}.


<!--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:
</translate>
</translate>
<syntaxhighlight lang="console">
<syntaxhighlight lang="console">
$ nix flake init
$ nix flake show
└───packages
    └───x86_64-linux
        ├───default: package 'hello-2.12.2'
        └───hello: package 'hello-2.12.2'
</syntaxhighlight>
</syntaxhighlight>
<translate>
<translate>
==== Development shells ==== <!--T:196-->


====Common structure====
<!--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>.
</translate>


The above command will provide a very simple flake file looking like:
<syntaxhighlight lang="nix">
{
  description = "Example flake with a devShell";
 
inputs.nixpkgs.url = "github:nixos/nixpkgs?ref=nixos-unstable";
 
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>


<translate>
<!--T:201-->
To enter the development shell environment:
</translate>
</translate>
<syntaxHighlight lang=nix>
{
  description = "A very basic flake";


  inputs = {
<syntaxhighlight lang="console">
    nixpkgs.url = "github:nixos/nixpkgs?ref=nixos-unstable";
$ nix develop
  };
</syntaxhighlight>


  outputs = { self, nixpkgs }: {
<translate>
<!--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).}}


    packages.x86_64-linux.hello = nixpkgs.legacyPackages.x86_64-linux.hello;
==== Build specific attributes in a flake repository ==== <!--T:102-->


    packages.x86_64-linux.default = self.packages.x86_64-linux.hello;
<!--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:
</translate>


  };
<syntaxHighlight lang=console>
}
$ nix build .#hello
</syntaxHighlight>
</syntaxHighlight>
<translate>
<translate>
 
<!--T:205-->
Flakes force you to specify a program for each supported architecture. To avoid this, third-parties projects like [[Flake Utils|flake-utils]] or [[Flake Parts|flake-parts]] 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]]
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-->
== Flake schema == <!--T:27-->
Line 141: Line 222:


<!--T:149-->
<!--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.
* <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]].


=== Input schema === <!--T:31-->
=== Input schema === <!--T:31-->
Line 155: Line 236:


<!--T:34-->
<!--T:34-->
Nixpkgs can be defined using the following code:
[[Nixpkgs]] can be defined using the following code:
</translate>


</translate>
<code>inputs.nixpkgs.url = "github:NixOS/nixpkgs/<branch name>";</code>
<code>inputs.nixpkgs.url = "github:NixOS/nixpkgs/<branch name>";</code>


<translate>
<!--T:235-->
Nixpkgs can alternatively also point to an url cached by the NixOS organization:
Nixpkgs can alternatively also point to an url cached by the NixOS organization:
</translate>


<code>inputs.nixpkgs.url = "<nowiki>https://nixos.org/channels/nixpkgs-unstable/nixexprs.tar.xz</nowiki>";</code>
<code>inputs.nixpkgs.url = "<nowiki>https://nixos.org/channels/nixpkgs-unstable/nixexprs.tar.xz</nowiki>";</code>


<translate>
<!--T:236-->
In this example the input would point to the `nixpkgs-unstable` channel.
In this example the input would point to the `nixpkgs-unstable` channel.
<translate>


<!--T:36-->
<!--T:36-->
Line 173: Line 257:
<!--T:37-->
<!--T:37-->
For example, adding [[Hyprland]] as an input would look something like this:
For example, adding [[Hyprland]] as an input would look something like this:
</translate>


</translate>
<code>inputs.hyprland.url = "github:hyprwm/Hyprland";</code>
<code>inputs.hyprland.url = "github:hyprwm/Hyprland";</code>
<translate>
<translate>
<!--T:39-->
<!--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:
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>


</translate>
<code>inputs.hyprland.inputs.nixpkgs.follows = "nixpkgs";</code>
<code>inputs.hyprland.inputs.nixpkgs.follows = "nixpkgs";</code>
<translate>
<translate>
<!--T:41-->
<!--T:41-->
Using curly brackets({}), we can shorten all of this and put it in a table. The code will look something like this:
Using curly brackets (<code>{}</code>), we can shorten all of this and put it in a table. The code will look something like this:
</translate>


</translate>
<syntaxhighlight lang="nix">
<syntaxhighlight lang="nix">
inputs = {
inputs = {
Line 198: Line 282:
};
};
</syntaxhighlight>
</syntaxhighlight>
<translate>
<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:
</translate>
<syntaxhighlight lang="nix">
  inputs.self.submodules = true;
</syntaxhighlight>


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


Line 222: Line 315:
<!--T:154-->
<!--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>


</translate>
<syntaxhighlight lang="nix">
<syntaxHighlight lang=nix>
{ self, ... }@inputs:
{ self, ... }@inputs:
{
{
Line 237: Line 330:
     type = "app";
     type = "app";
     program = "<store-path>";
     program = "<store-path>";
    meta = {description = "..."; inherit otherMetaAttrs; };
   };
   };
   # Executed by `nix run . -- <args?>`
   # Executed by `nix run . -- <args?>`
   apps."<system>".default = { type = "app"; program = "..."; };
   apps."<system>".default = { type = "app"; program = "..."; meta = {description = "..."; inherit otherMetaAttrs; }; };


   # Formatter (alejandra, nixfmt or nixpkgs-fmt)
   # Formatter (alejandra, nixfmt, treefmt-nix or nixpkgs-fmt)
   formatter."<system>" = derivation;
   formatter."<system>" = derivation;
   # Used for nixpkgs packages, also accessible via `nix build .#<name>`
   # Used for nixpkgs packages, also accessible via `nix build .#<name>`
Line 270: Line 364:
   templates.default = { path = "<store-path>"; description = ""; };
   templates.default = { path = "<store-path>"; description = ""; };
}
}
</syntaxHighlight>
</syntaxhighlight>
 
<translate>
<translate>
<!--T:48-->
<!--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.


==== nix run ==== <!--T:49-->
== Core usage patterns == <!--T:208-->
 
<!--T:155-->
When output <code>apps.<system>.myapp</code> is not defined, <code>nix run myapp</code> runs <code><packages or legacyPackages.<system>.myapp>/bin/<myapp.meta.mainProgram or myapp.pname or myapp.name (the non-version part)></code>
 
== Flake support in projects without flakes == <!--T:50-->
 
<!--T:51-->
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.
 
== Accessing flakes from Nix expressions == <!--T:58-->


<!--T:59-->
=== Making your evaluations pure === <!--T:60-->
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>.
 
== Making your evaluations pure == <!--T:60-->


<!--T:61-->
<!--T:61-->
Nix flakes run in pure evaluation mode, which is underdocumented. Some tips for now:
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-->
<!--T:62-->
* fetchurl and fetchtar [https://github.com/NixOS/nix/blob/36c4d6f59247826dde32ad2e6b5a9471a9a1c911/src/libexpr/primops/fetchTree.cc#L201 require] a sha256 argument to be considered pure.
* {{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-->
<!--T:156-->
* 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.
* <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:157-->
* 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:
 
</translate>
<syntaxhighlight lang="nix">
outputs = { self, nixpkgs, ... }:
  {
    nixosConfigurations.machine = nixpkgs.lib.nixosSystem {
      modules = [
        "${nixpkgs}/nixos/modules/<some-module>.nix"
        ./machine.nix
      ];
    };
  };
</syntaxhighlight>
<translate>


== The nix flakes command == <!--T:64-->
<!--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.


<!--T:65-->
=== Defining a flake for multiple architectures === <!--T:210-->
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].
 
== Install packages with `nix profile` == <!--T:66-->
 
<!--T:67-->
[https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-profile-install.html <code>nix profile install</code> in the manual]
 
== Using nix flakes with NixOS == <!--T:68-->
 
<!--T:69-->
<code>nixos-rebuild switch</code> will read its configuration from <code>/etc/nixos/flake.nix</code> if it is present.
 
<!--T:70-->
A basic nixos flake.nix could look like this:


<!--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.
</translate>
</translate>
<syntaxhighlight lang="nix">
{
  inputs.nixpkgs.url = github:NixOS/nixpkgs/nixos-unstable;
  outputs = { self, nixpkgs }: {
    # replace 'joes-desktop' with your hostname here.
    nixosConfigurations.joes-desktop = nixpkgs.lib.nixosSystem {
      modules = [ ./configuration.nix ];
    };
  };
}
</syntaxhighlight>
<translate>


<!--T:158-->
If you want to pass on the flake inputs to external configuration files, you can use the <code>specialArgs</code> attribute:
</translate>
<syntaxhighlight lang="nix">
<syntaxhighlight lang="nix">
{
{
   inputs.nixpkgs.url = github:NixOS/nixpkgs/nixos-unstable;
   description = "A flake targeting multiple architectures";
  inputs.home-manager.url = github:nix-community/home-manager;


  outputs = { self, nixpkgs, ... }@inputs: {
inputs = {
     nixosConfigurations.fnord = nixpkgs.lib.nixosSystem {
     nixpkgs.url = "github:nixos/nixpkgs?ref=nixos-unstable";
      specialArgs = { inherit inputs; };
      modules = [ ./configuration.nix ];
    };
   };
   };
}
</syntaxhighlight>
<translate>


<!--T:159-->
outputs = { self, nixpkgs }: let
Then, you can access the flake inputs from the file <code>configuration.nix</code> like this:
    systems = [ "x86_64-linux" "aarch64-linux" ];
 
    forAllSystems = f: builtins.listToAttrs (map (system: {
</translate>
      name = system;
<syntaxhighlight lang="nix">
      value = f system;
{ config, lib, inputs, ... }: {
    }) systems);
  # do something with home-manager here, for instance:
  in {
  imports = [ inputs.home-manager.nixosModules.default ];
    packages = forAllSystems (system: let
   ...
      pkgs = nixpkgs.legacyPackages.${system};
    in {
      hello = pkgs.hello;
      default = pkgs.hello;
    });
   };
}
}
</syntaxhighlight>
</syntaxhighlight>
<translate>


<!--T:73-->
<code>nixos-rebuild</code> also allows to specify different flake using the <code>--flake</code> flag (# is optional):
</translate>
<syntaxhighlight lang="console">
$ sudo nixos-rebuild switch --flake .
</syntaxhighlight>
<translate>
<translate>
<!--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]]


<!--T:75-->
=== Using overlays === <!--T:216-->  
By default <code>nixos-rebuild</code> will use the current system hostname to look up the right NixOS configuration in <code>nixosConfigurations</code>. You can also override this by using appending it to the flake parameter:


</translate>
<!--T:217-->
<syntaxhighlight lang="console">
To use [[Overlays]] with flakes, refer to [[Overlays#In a Nix flake]] page.
$ sudo nixos-rebuild switch --flake /etc/nixos#joes-desktop
</syntaxhighlight>
<translate>


<!--T:77-->
=== Enable unfree software === <!--T:129-->
To switch a remote host you can use:


<!--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.
</translate>
</translate>
<syntaxhighlight lang="bash">
$ nixos-rebuild --flake .#mymachine \
  --target-host mymachine-hostname \
  --build-host mymachine-hostname --fast \
  switch
</syntaxhighlight>
<translate>
<!--T:78-->
{{warning|Remote building seems to have an issue that's [https://github.com/NixOS/nixpkgs/issues/134952#issuecomment-1367056358 resolved by setting the <code>--fast</code> flag].}}
== Pinning the registry on NixOS == <!--T:79-->


</translate>
<syntaxhighlight lang="nix">
<syntaxhighlight lang="nix">
{ inputs, ... }:
{
{
nix.registry = {
  inputs.nixpkgs.url = "github:nixos/nixpkgs?ref=nixos-unstable";
    nixpkgs.flake = inputs.nixpkgs;
   outputs = { self, nixpkgs, flake-compat }:
  };
     let
}
       system = "x86_64-linux";
</syntaxhighlight>
       pkgs = import nixpkgs { inherit system; config.allowUnfree = true;};
<translate>
    in {
 
      ...
<!--T:81-->
To make sure the registry entry is "locked", use the following:
 
</translate>
<syntaxHighlight lang=nix>
   nix.registry = {
     nixpkgs.to = {
       type = "path";
       path = pkgs.path;
      narHash = builtins.readFile
          (pkgs.runCommandLocal "get-nixpkgs-hash"
            { nativeBuildInputs = [ pkgs.nix ]; }
            "nix-hash --type sha256 --sri ${pkgs.path} > $out");
     };
     };
  };
</syntaxHighlight>
<translate>
<!--T:83-->
This has the unfortunate side-effect of requiring import-from-derivation and slowing down build times, however it may greatly speed up almost every eval. Full-time flakes users may be able to just use <code>narHash = pkgs.narHash</code>.
== Super fast nix-shell == <!--T:84-->
<!--T:85-->
A feature of the nix Flake edition is that Nix evaluations are cached.
<!--T:86-->
Let’s say that your project has a <code>shell.nix</code> file that looks like this:
</translate>
<syntaxhighlight lang="nix">
{
  pkgs ? import <nixpkgs> { },
}:
pkgs.mkShell {
  packages = [ pkgs.nixfmt ];
  shellHook = ''
    # ...
  '';
}
}
</syntaxhighlight>
</syntaxhighlight>  
<translate>
 
<!--T:89-->
Running nix-shell can be a bit slow and take 1-3 seconds.
 
<!--T:90-->
Now create a <code>flake.nix</code> file in the same repository:
 
</translate>
<syntaxhighlight lang="nix">
{
  inputs.nixpkgs.url = "github:NixOS/nixpkgs/nixpkgs-unstable";


  outputs =
    { nixpkgs, ... }:
    {
      /*
        This example assumes your system is x86_64-linux
        change as neccesary
      */
      devShells.x86_64-linux =
        let
          pkgs = nixpkgs.legacyPackages.x86_64-linux;
        in
        {
          default = pkgs.mkShell {
            packages = [ pkgs.hello ];
          };
        };
    };
}
}
</syntaxhighlight>
<translate>
<translate>
== NixOS configuration with flakes == <!--T:220-->


<!--T:93-->
<!--T:221-->
( If you're in a git repository run `git add flake.nix` so that Nix recognizes it. )
It is possible to manage a [[NixOS]] system configuration using flakes, gaining the benefits of reproducible, declarative inputs and streamlined updates.


<!--T:94-->
<!--T:222-->
And finally, run <code>nix develop</code>. This is what replaces the old nix-shell invocation.
For details and examples, see [[NixOS system configuration#Defining NixOS as a flake]].


<!--T:95-->
== Development tricks == <!--T:131-->
Exit and run again, this command should now be super fast.


<!--T:96-->
=== Automatically switch nix shells with direnv === <!--T:97-->
{{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.}}
 
== Automatically switch nix shells with direnv == <!--T:97-->


<!--T:98-->
<!--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].
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-->
=== Pushing Flakes to Cachix === <!--T:99-->
</translate>


</translate>
https://docs.cachix.org/pushing#flakes
https://docs.cachix.org/pushing#flakes
<translate>


<!--T:101-->
To push ''all'' flake outputs automatically, checkout [https://github.com/srid/devour-flake#usage devour-flake].
== Build specific attributes in a flake repository == <!--T:102-->
<!--T:103-->
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.
<!--T:104-->
Eg, in nixpkgs:
</translate>
<syntaxHighlight lang=console>
$ nix build .#hello
</syntaxHighlight>
<translate>
<translate>
=== Flake support in projects without flakes === <!--T:50-->


=== Building flakes from a Git repo url with submodules === <!--T:106-->
<!--T:51-->
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:107-->
<!--T:223-->
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:
Another project that allows consuming flakes from non-flake projects is [https://github.com/fricklerhandwerk/flake-inputs flake-inputs].


</translate>
=== Accessing flakes from Nix expressions === <!--T:58-->
<syntaxhighlight lang="console">
nix build '.?submodules=1#hello'
</syntaxhighlight>
<translate>


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


== Importing packages from multiple nixpkgs branches == <!--T:110-->
=== Efficiently build multiple flake outputs === <!--T:224-->


<!--T:111-->
<!--T:101-->
A NixOS config flake could be as follows (replace <hostname> with your hostname):
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>
</translate>
<syntaxhighlight lang="nix">
{
  description = "NixOS configuration with two or more channels";
inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-24.11";
    nixpkgs-unstable.url = "github:NixOS/nixpkgs/nixos-unstable";
  };
  outputs =
    { nixpkgs, nixpkgs-unstable, ... }:
    {
      nixosConfigurations."<hostname>" = nixpkgs.lib.nixosSystem {
        modules = [
          {
            nixpkgs.overlays = [
              (final: prev: {
                unstable = nixpkgs-unstable.legacyPackages.${prev.system};
                # use this variant if unfree packages are needed:
                # unstable = import nixpkgs-unstable {
                #  inherit prev;
                #  system = prev.system;
                #  config.allowUnfree = true;
                # };
              })
            ];
          }
          ./configuration.nix
        ];
      };
    };
}
</syntaxhighlight>
<translate>


</translate>
<syntaxhighlight lang="nix">
# NixOS configuration.nix, can now use "pkgs.package" or "pkgs.unstable.package"
{ pkgs, ... }:
{
  environment.systemPackages = [
    pkgs.firefox
    pkgs.unstable.chromium
  ];
  # ...
}
</syntaxhighlight>
<translate>
<!--T:160-->
If the variable <code>nixpkgs</code> points to the flake, you can also define <code>pkgs</code> with overlays with:
</translate>
<syntaxhighlight lang="nix">
pkgs = import nixpkgs { system = "x86_64-linux"; overlays = [ /*the overlay in question*/ ]; };
</syntaxhighlight>
<translate>
== Getting ''Instant'' System Flakes Repl == <!--T:116-->
<!--T:117-->
How to get a nix repl out of your system flake:
</translate>
<syntaxhighlight lang="text">
$ nix repl
nix-repl> :lf /path/to/flake
Added 18 variables.
nix-repl> nixosConfigurations.myHost.config.networking.hostName
"myHost"
</syntaxhighlight>
<translate>
<!--T:122-->
However, this won't be instant upon evaluation if any file changes have been done since your last configuration rebuild. Instead, if one puts:
</translate>
<syntaxHighlight lang=nix>
nix.nixPath = let path = toString ./.; in [ "repl=${path}/repl.nix" "nixpkgs=${inputs.nixpkgs}" ];
</syntaxHighlight>
<translate>
<!--T:123-->
In their system <code>flake.nix</code> configuration file, and includes the following file in their root directory flake as <code>repl.nix</code>:
</translate>
<syntaxHighlight lang=nix>
let
  flake = builtins.getFlake (toString ./.);
  nixpkgs = import <nixpkgs> { };
in
{ inherit flake; }
// flake
// builtins
// nixpkgs
// nixpkgs.lib
// flake.nixosConfigurations
</syntaxHighlight>
<translate>
<!--T:125-->
(Don't forget to <code>git add repl.nix && nixos-rebuild  switch --flake "/etc/nixos"</code>)
Then one can run (or bind a shell alias):
</translate>
<syntaxHighlight lang=bash>
source /etc/set-environment && nix repl $(echo $NIX_PATH | perl -pe 's|.*(/nix/store/.*-source/repl.nix).*|\1|')</syntaxHighlight>
<translate>
<!--T:127-->
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:128-->
An alternative approach to the above shell alias is omitting <code>repl</code> from <code>nix.nixPath</code> and creating a shell script:
</translate>
<syntaxHighlight lang=nix>
nix.nixPath = [ "nixpkgs=${inputs.nixpkgs}" ];
environment.systemPackages = let
  repl_path = toString ./.;
  my-nix-fast-repl = pkgs.writeShellScriptBin "my-nix-fast-repl" ''
    source /etc/set-environment
    nix repl "${repl_path}/repl.nix" "$@"
  '';
in [
  my-nix-fast-repl
];
</syntaxHighlight>
<translate>
== Enable unfree software == <!--T:129-->
<!--T:130-->
Refer to [[Unfree software|Unfree Software]].
== Development tricks == <!--T:131-->
=== Build a package added in a PR === <!--T:161-->
</translate>
<syntaxHighlight>
<syntaxHighlight>
nix build github:nixos/nixpkgs?ref=pull/<PR_NUMBER>/head#<PACKAGE>
nix build github:nixos/nixpkgs?ref=pull/<PR_NUMBER>/head#<PACKAGE>
</syntaxHighlight>
</syntaxHighlight>
<translate>
<translate>
<!--T:162-->
<!--T:162-->
this allows building a package that has not yet been added to nixpkgs.
this allows building a package that has not yet been added to nixpkgs.
Line 720: Line 498:
<!--T:132-->
<!--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:
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>


</translate>
<syntaxHighlight>
<syntaxHighlight>
git fetch upstream pull/<PR_NUMBER>/head && git checkout FETCH_HEAD && nix build .#PACKAGE
git fetch upstream pull/<PR_NUMBER>/head && git checkout FETCH_HEAD && nix build .#PACKAGE
</syntaxHighlight>
</syntaxHighlight>
<translate>
<translate>
<!--T:163-->
<!--T:163-->
this allows building a package that has not yet been added to nixpkgs.
this allows building a package that has not yet been added to nixpkgs.
Line 733: Line 511:


<!--T:133-->
<!--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>):
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>


</translate>
<syntaxHighlight>
<syntaxHighlight>
git add --intent-to-add extra/flake.nix
git add --intent-to-add extra/flake.nix
git update-index --skip-worktree --assume-unchanged extra/flake.nix
git update-index --skip-worktree --assume-unchanged extra/flake.nix
</syntaxHighlight>
</syntaxHighlight>
<translate>
<translate>
=== Rapid iteration of a direct dependency === <!--T:135-->
=== Rapid iteration of a direct dependency === <!--T:135-->


Line 749: Line 527:
<!--T:136-->
<!--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:
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>


</translate>
<syntaxHighlight lang=bash>
<syntaxHighlight lang=bash>
cd ~/libdep-src-checkout/
cd ~/libdep-src-checkout/
Line 758: Line 536:
installPhase # install it like nix does
installPhase # install it like nix does
</syntaxHighlight>
</syntaxHighlight>
<translate>
<translate>
<!--T:166-->
<!--T:166-->
Now that you've built the dependency, <code>consumexe</code> can take it as an input. '''In another terminal''':
Now that you've built the dependency, <code>consumexe</code> can take it as an input. '''In another terminal''':
</translate>


</translate>
<syntaxHighlight lang=bash>
<syntaxHighlight lang=bash>
cd ~/consumexe-src-checkout/
cd ~/consumexe-src-checkout/
Line 770: Line 548:
# Output should show ~/libdep-src-checkout/ so you know it worked
# Output should show ~/libdep-src-checkout/ so you know it worked
</syntaxHighlight>
</syntaxHighlight>
<translate>
<translate>


Line 776: Line 555:


== See also == <!--T:138-->
== See also == <!--T:138-->
=== Official sources === <!--T:225-->


<!--T:139-->
<!--T:139-->
* [https://nix.dev/concepts/flakes Flakes] - nix.dev
* [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.
<!--T:178-->
* [https://github.com/NixOS/nix/blob/master/src/nix/flake.md spec describing flake inputs in more detail]


<!--T:168-->
<!--T:168-->
* [https://github.com/NixOS/rfcs/pull/49 RFC 49] (2019) - Original flakes specification
* [https://github.com/NixOS/rfcs/pull/49 RFC 49] (2019) - Original flakes specification
=== Guides === <!--T:226-->


<!--T:169-->
<!--T:169-->
Line 803: Line 592:
<!--T:175-->
<!--T:175-->
* [https://www.tweag.io/blog/2020-07-31-nixos-flakes/ Nix Flakes, Part 3: Managing NixOS systems] (Eelco Dolstra, 2020)
* [https://www.tweag.io/blog/2020-07-31-nixos-flakes/ Nix Flakes, Part 3: Managing NixOS systems] (Eelco Dolstra, 2020)
<!--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.


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


<!--T:178-->
=== Useful flake modules === <!--T:227-->  
* [https://github.com/NixOS/nix/blob/master/src/nix/flake.md spec describing flake inputs in more detail]


<!--T:179-->
<!--T:179-->
* [https://github.com/numtide/flake-utils flake-utils: Library to avoid some boiler-code when writing flakes]
* [[Flake Utils|flake-utils]]: Library to avoid some boiler-code when writing flakes


<!--T:180-->
<!--T:228-->
* [https://zimbatm.com/NixFlakes/#direnv-integration zimbat's direnv article]
* [[Flake Parts|flake-parts]]: Library to help write modular and organized flakes
 
<!--T:229-->
* [[Flake Compat|flake-compat]]: A compatibility layer for flakes


<!--T:181-->
<!--T:181-->
* [https://github.com/nix-community/todomvc-nix building Rust and Haskell flakes]
* [https://github.com/nix-community/todomvc-nix building Rust and Haskell flakes]
</translate>
{{references}}


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