Flakes: Difference between revisions

From NixOS Wiki
Natsukium (talk | contribs)
No edit summary
Jopejoe1 (talk | contribs)
Improve translation support
Line 11: Line 11:
<!--T:4-->
<!--T:4-->
* 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>.
* 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>.
* The contents of <code>flake.nix</code> file follow a uniform naming schema for declaring packages and their dependencies in the Nix language.
* The contents of <code>flake.nix</code> file follow a uniform naming schema for declaring packages and their dependencies in the Nix language.
*  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.  
 
*  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.
 
* 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.
* 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.
* Flakes also allow for locking references and versions that can then be queried and updated programmatically.
* Flakes also allow for locking references and versions that can then be queried and updated programmatically.
* 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.
* 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.


Line 21: Line 26:
<!--T:6-->
<!--T:6-->
When using any <code>nix</code> command, add the following command-line options:
When using any <code>nix</code> command, add the following command-line options:
</translate>
<syntaxhighlight lang="shell">
<syntaxhighlight lang="shell">
  --experimental-features 'nix-command flakes'
  --experimental-features 'nix-command flakes'
</syntaxhighlight>
</syntaxhighlight>
<translate>


====Enable flakes permanently in NixOS==== <!--T:7-->
====Enable flakes permanently in NixOS==== <!--T:7-->
Line 30: Line 37:
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]]:


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


=====Other Distros, with Home-Manager===== <!--T:10-->
=====Other Distros, with Home-Manager===== <!--T:10-->
Line 40: Line 48:
Add the following to your home-manager config:
Add the following to your home-manager config:


<!--T:12-->
</translate>
<syntaxhighlight lang="nix">
<syntaxhighlight lang="nix">
   nix.settings.experimental-features = [ "nix-command" "flakes" ];
   nix.settings.experimental-features = [ "nix-command" "flakes" ];
</syntaxhighlight>
</syntaxhighlight>
<translate>


=====Other Distros, without Home-Manager===== <!--T:13-->
=====Other Distros, without Home-Manager===== <!--T:13-->
Line 53: Line 62:
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>:


<!--T:16-->
</translate>
<syntaxHighlight lang=text>
<syntaxHighlight lang=text>
experimental-features = nix-command flakes
experimental-features = nix-command flakes
</syntaxHighlight>
</syntaxHighlight>
<translate>


===Basic Usage of Flake=== <!--T:17-->
===Basic Usage of Flake=== <!--T:17-->
Line 70: Line 80:
<!--T:21-->
<!--T:21-->
====Git WARNING====
====Git WARNING====
For flakes in git repos, only files in the working tree will be copied to the store.
For flakes in git repos, only files in the working tree will be copied to the store.


Line 83: Line 94:
To start the basic usage of flake, run the flake command in the project directory:
To start the basic usage of flake, run the flake command in the project directory:


<!--T:26-->
</translate>
<syntaxHighlight lang=text>
<syntaxHighlight lang=text>
nix flake init
nix flake init
</syntaxHighlight>
</syntaxHighlight>
<translate>


== Flake schema == <!--T:27-->
== Flake schema == <!--T:27-->
Line 98: Line 110:
<!--T:30-->
<!--T:30-->
* <code>description</code> is a string describing the flake.
* <code>description</code> is a string describing the flake.
* <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 whose 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 whose schema is described below.
* <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.


Line 106: Line 121:
<!--T:32-->
<!--T:32-->
[https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-flake.html#flake-inputs The nix flake inputs manual].
[https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-flake.html#flake-inputs The nix flake inputs manual].
[https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-flake.html#flake-references The nix flake references manual].
[https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-flake.html#flake-references The nix flake references manual].


<!--T:33-->
<!--T:33-->
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.  
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.


<!--T:34-->
<!--T:34-->
Nixpkgs can be defined using the following code:
Nixpkgs can be defined using the following code:


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


<!--T:36-->
<!--T:36-->
Line 123: Line 140:
For example, adding [[Hyprland]] as an input would look something like this:
For example, adding [[Hyprland]] as an input would look something like this:


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


<!--T:40-->
</translate>
<code>inputs.hyprland.inputs.nixpkgs.follows = "nixpkgs";</code>
<code>inputs.hyprland.inputs.nixpkgs.follows = "nixpkgs";</code>
<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:<syntaxhighlight lang="nix">
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 = {
inputs = {
   nixpkgs.url = "github:NixOS/nixpkgs/<branch name>";
   nixpkgs.url = "github:NixOS/nixpkgs/<branch name>";
Line 142: Line 164:
};
};
</syntaxhighlight>
</syntaxhighlight>
<translate>


<!--T:42-->
<!--T:42-->
=== Output schema ===
=== Output schema ===
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-check.md src/nix/flake-check.md].


Line 155: Line 179:
<!--T:45-->
<!--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><name></code> is an attribute name like "hello".
* <code><name></code> is an attribute name like "hello".
* <code><flake></code> is a flake name like "nixpkgs".
* <code><flake></code> is a flake name like "nixpkgs".
* <code><store-path></code> is a <code>/nix/store..</code> path
* <code><store-path></code> is a <code>/nix/store..</code> path


<!--T:46-->
</translate>
<syntaxHighlight lang=nix>
<syntaxHighlight lang=nix>
{ self, ... }@inputs:
{ self, ... }@inputs:
Line 177: Line 204:
   apps."<system>".default = { type = "app"; program = "..."; };
   apps."<system>".default = { type = "app"; program = "..."; };


   <!--T:47-->
   # Formatter (alejandra, nixfmt or nixpkgs-fmt)
# Formatter (alejandra, nixfmt 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 208: Line 234:
}
}
</syntaxHighlight>
</syntaxHighlight>
<translate>


<!--T:48-->
<!--T:48-->
Line 214: Line 241:
<!--T:49-->
<!--T:49-->
==== nix run ====
==== nix run ====
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>
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>


Line 224: Line 252:
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:
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:


<!--T:53-->
</translate>
<syntaxHighlight lang=nix>
<syntaxHighlight lang=nix>
(import (
(import (
Line 234: Line 262:
}).defaultNix
}).defaultNix
</syntaxHighlight>
</syntaxHighlight>
<translate>


<!--T:54-->
<!--T:54-->
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>:
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:55-->
</translate>
<syntaxHighlight lang=nix>
<syntaxHighlight lang=nix>
   inputs.flake-compat = {
   inputs.flake-compat = {
Line 245: Line 274:
   };
   };
</syntaxHighlight>
</syntaxHighlight>
<translate>


<!--T:56-->
<!--T:56-->
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:
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:57-->
</translate>
<syntaxhighlight lang="nix">
<syntaxhighlight lang="nix">
(import (
(import (
Line 264: Line 294:
) { src = ./.; }).defaultNix
) { src = ./.; }).defaultNix
</syntaxhighlight>
</syntaxhighlight>
<translate>


== Accessing flakes from Nix expressions == <!--T:58-->
== Accessing flakes from Nix expressions == <!--T:58-->
Line 277: Line 308:
<!--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.
* fetchurl and fetchtar [https://github.com/NixOS/nix/blob/36c4d6f59247826dde32ad2e6b5a9471a9a1c911/src/libexpr/primops/fetchTree.cc#L201 require] a sha256 argument to be considered pure.
* 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.
* 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.
* 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:
* 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:


<!--T:63-->
</translate>
<syntaxhighlight lang="nix">
<syntaxhighlight lang="nix">
  outputs = { self, nixpkgs, ... }:
  outputs = { self, nixpkgs, ... }:
Line 292: Line 325:
   };
   };
</syntaxhighlight>
</syntaxhighlight>
<translate>


== The nix flakes command == <!--T:64-->
== The nix flakes command == <!--T:64-->
Line 311: Line 345:
A basic nixos flake.nix could look like this:
A basic nixos flake.nix could look like this:


<!--T:71-->
</translate>
<syntaxhighlight lang="nix">
<syntaxhighlight lang="nix">
{
{
Line 323: Line 357:
}
}
</syntaxhighlight>
</syntaxhighlight>
<translate>
If you want to pass on the flake inputs to external configuration files, you can use the <code>specialArgs</code> attribute:
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">
{
{
Line 329: Line 367:
   inputs.home-manager.url = github:nix-community/home-manager;
   inputs.home-manager.url = github:nix-community/home-manager;


   <!--T:72-->
   outputs = { self, nixpkgs, ... }@inputs: {
outputs = { self, nixpkgs, ... }@inputs: {
     nixosConfigurations.fnord = nixpkgs.lib.nixosSystem {
     nixosConfigurations.fnord = nixpkgs.lib.nixosSystem {
       specialArgs = { inherit inputs; };
       specialArgs = { inherit inputs; };
Line 338: Line 375:
}
}
</syntaxhighlight>
</syntaxhighlight>
<translate>
Then, you can access the flake inputs from the file <code>configuration.nix</code> like this:
Then, you can access the flake inputs from the file <code>configuration.nix</code> like this:
</translate>
<syntaxhighlight lang="nix">
<syntaxhighlight lang="nix">
{ config, lib, inputs, ... }: {
{ config, lib, inputs, ... }: {
Line 346: Line 387:
}
}
</syntaxhighlight>
</syntaxhighlight>
<translate>


<!--T:73-->
<!--T:73-->
{{Ic|nixos-rebuild}} also allows to specify different flake using the <code>--flake</code> flag (# is optional):
{{Ic|nixos-rebuild}} also allows to specify different flake using the <code>--flake</code> flag (# is optional):


<!--T:74-->
</translate>
<syntaxhighlight lang="console">
<syntaxhighlight lang="console">
$ sudo nixos-rebuild switch --flake .
$ sudo nixos-rebuild switch --flake .
</syntaxhighlight>
</syntaxhighlight>
<translate>


<!--T:75-->
<!--T:75-->
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:
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:76-->
</translate>
<syntaxhighlight lang="console">
<syntaxhighlight lang="console">
$ sudo nixos-rebuild switch --flake /etc/nixos#joes-desktop
$ sudo nixos-rebuild switch --flake /etc/nixos#joes-desktop
</syntaxhighlight>
</syntaxhighlight>
<translate>


<!--T:77-->
<!--T:77-->
To switch a remote host you can use:
To switch a remote host you can use:
</translate>
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
$ nixos-rebuild --flake .#mymachine \
$ nixos-rebuild --flake .#mymachine \
Line 371: Line 418:
   switch
   switch
</syntaxhighlight>
</syntaxhighlight>
<translate>


<!--T:78-->
<!--T:78-->
Line 377: Line 425:
== Pinning the registry on NixOS == <!--T:79-->
== Pinning the registry on NixOS == <!--T:79-->


<!--T:80-->
</translate>
<syntaxhighlight lang="nix">
<syntaxhighlight lang="nix">
{ inputs, ... }:
{ inputs, ... }:
Line 386: Line 434:
}
}
</syntaxhighlight>
</syntaxhighlight>
<translate>


<!--T:81-->
<!--T:81-->
To make sure the registry entry is "locked", use the following:
To make sure the registry entry is "locked", use the following:


<!--T:82-->
</translate>
<syntaxHighlight lang=nix>
<syntaxHighlight lang=nix>
   nix.registry = {
   nix.registry = {
Line 403: Line 452:
   };
   };
</syntaxHighlight>
</syntaxHighlight>
<translate>


<!--T:83-->
<!--T:83-->
Line 415: Line 465:
Let’s say that your project has a <code>shell.nix</code> file that looks like this:
Let’s say that your project has a <code>shell.nix</code> file that looks like this:


<!--T:87-->
</translate>
<syntaxhighlight lang="nix">
<syntaxhighlight lang="nix">
{
{
Line 423: Line 473:
   packages = [ pkgs.nixfmt ];
   packages = [ pkgs.nixfmt ];


   <!--T:88-->
   shellHook = ''
shellHook = ''
     # ...
     # ...
   '';
   '';
}
}
</syntaxhighlight>
</syntaxhighlight>
<translate>


<!--T:89-->
<!--T:89-->
Line 436: Line 486:
Now create a <code>flake.nix</code> file in the same repository:
Now create a <code>flake.nix</code> file in the same repository:


<!--T:91-->
</translate>
<syntaxhighlight lang="nix">
<syntaxhighlight lang="nix">
{
{
   inputs.nixpkgs.url = "github:NixOS/nixpkgs/nixpkgs-unstable";
   inputs.nixpkgs.url = "github:NixOS/nixpkgs/nixpkgs-unstable";


   <!--T:92-->
   outputs =
outputs =
     { nixpkgs, ... }:
     { nixpkgs, ... }:
     {
     {
       /*  
       /*
         This example assumes your system is x86_64-linux
         This example assumes your system is x86_64-linux
         change as neccesary
         change as neccesary
Line 462: Line 511:
}
}
</syntaxhighlight>
</syntaxhighlight>
<translate>


<!--T:93-->
<!--T:93-->
Line 482: Line 532:
== Pushing Flakes to Cachix == <!--T:99-->
== Pushing Flakes to Cachix == <!--T:99-->


<!--T:100-->
</translate>
https://docs.cachix.org/pushing#flakes
https://docs.cachix.org/pushing#flakes
<translate>


<!--T:101-->
<!--T:101-->
Line 496: Line 547:
Eg, in nixpkgs:
Eg, in nixpkgs:


<!--T:105-->
</translate>
<syntaxHighlight lang=console>
<syntaxHighlight lang=console>
$ nix build .#hello
$ nix build .#hello
</syntaxHighlight>
</syntaxHighlight>
<translate>


=== Building flakes from a Git repo url with submodules === <!--T:106-->
=== Building flakes from a Git repo url with submodules === <!--T:106-->
Line 506: Line 558:
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:
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:


<!--T:108-->
</translate>
<syntaxhighlight lang="console">
<syntaxhighlight lang="console">
nix build '.?submodules=1#hello'
nix build '.?submodules=1#hello'
</syntaxhighlight>
</syntaxhighlight>
<translate>


<!--T:109-->
<!--T:109-->
Line 518: Line 571:
<!--T:111-->
<!--T:111-->
A NixOS config flake could be as follows:
A NixOS config flake could be as follows:
</translate>
<syntaxhighlight lang="nix">
<syntaxhighlight lang="nix">
{
{
   description = "NixOS configuration with two or more channels";
   description = "NixOS configuration with two or more channels";


  <!--T:112-->
inputs = {
inputs = {
     nixpkgs.url = "github:NixOS/nixpkgs/nixos-23.11";
     nixpkgs.url = "github:NixOS/nixpkgs/nixos-23.11";
     nixpkgs-unstable.url = "github:NixOS/nixpkgs/nixos-unstable";
     nixpkgs-unstable.url = "github:NixOS/nixpkgs/nixos-unstable";
   };
   };


   <!--T:113-->
   outputs =
outputs =
     { nixpkgs, nixpkgs-unstable, ... }:
     { nixpkgs, nixpkgs-unstable, ... }:
     {
     {
Line 552: Line 605:
}
}
</syntaxhighlight>
</syntaxhighlight>
<translate>


<!--T:114-->
</translate>
<syntaxhighlight lang="nix">
<syntaxhighlight lang="nix">
# NixOS configuration.nix, can now use "pkgs.package" or "pkgs.unstable.package"
# NixOS configuration.nix, can now use "pkgs.package" or "pkgs.unstable.package"
Line 564: Line 618:
   # ...
   # ...
}
}
</syntaxhighlight>If the variable <code>nixpkgs</code> points to the flake, you can also define <code>pkgs</code> with overlays with:
</syntaxhighlight>
<translate>


<!--T:115-->
If the variable <code>nixpkgs</code> points to the flake, you can also define <code>pkgs</code> with overlays with:
 
</translate>
<syntaxhighlight lang="nix">
<syntaxhighlight lang="nix">
pkgs = import nixpkgs { system = "x86_64-linux"; overlays = [ /*the overlay in question*/ ]; };
pkgs = import nixpkgs { system = "x86_64-linux"; overlays = [ /*the overlay in question*/ ]; };
</syntaxhighlight>
</syntaxhighlight>
<translate>


== Getting ''Instant'' System Flakes Repl == <!--T:116-->
== Getting ''Instant'' System Flakes Repl == <!--T:116-->
Line 576: Line 634:
How to get a nix repl out of your system flake:
How to get a nix repl out of your system flake:


<!--T:118-->
</translate>
<syntaxhighlight lang="text">
<syntaxhighlight lang="text">
$ nix repl
$ nix repl


<!--T:119-->
nix-repl> :lf /path/to/flake
nix-repl> :lf /path/to/flake
Added 18 variables.
Added 18 variables.


<!--T:120-->
nix-repl> nixosConfigurations.myHost.config.networking.hostName
nix-repl> nixosConfigurations.myHost.config.networking.hostName
"myHost"
"myHost"


<!--T:121-->
</syntaxhighlight>
</syntaxhighlight>
<translate>


<!--T:122-->
<!--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:<syntaxHighlight lang=nix>
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}" ];
nix.nixPath = let path = toString ./.; in [ "repl=${path}/repl.nix" "nixpkgs=${inputs.nixpkgs}" ];
</syntaxHighlight>
</syntaxHighlight>
<translate>


<!--T:123-->
<!--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>:
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:124-->
</translate>
<syntaxHighlight lang=nix>
<syntaxHighlight lang=nix>
let
let
Line 613: Line 672:
// flake.nixosConfigurations
// flake.nixosConfigurations
</syntaxHighlight>
</syntaxHighlight>
<translate>


<!--T:125-->
<!--T:125-->
Line 618: Line 678:
Then one can run (or bind a shell alias):
Then one can run (or bind a shell alias):


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


<!--T:127-->
<!--T:127-->
Line 627: Line 688:
<!--T:128-->
<!--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:
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>
<syntaxHighlight lang=nix>
nix.nixPath = [ "nixpkgs=${inputs.nixpkgs}" ];
nix.nixPath = [ "nixpkgs=${inputs.nixpkgs}" ];
Line 639: Line 702:
];
];
</syntaxHighlight>
</syntaxHighlight>
<translate>


== Enable unfree software == <!--T:129-->
== Enable unfree software == <!--T:129-->
Line 647: Line 711:
<!--T:131-->
<!--T:131-->
== Development tricks ==
== Development tricks ==
=== Build a package added in a PR ===
=== Build a package added in a PR ===
</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>
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.


<!--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>
<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>
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.
=== How to add a file locally in git but not include it in commits ===
=== How to add a file locally in git but not include it in commits ===


Line 664: Line 738:
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>):


<!--T:134-->
</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>


<!--T:135-->
<!--T:135-->
=== Rapid iteration of a direct dependency ===
=== Rapid iteration of a direct dependency ===
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.
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.


Line 677: Line 753:
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:


<!--T:137-->
</translate>
<syntaxHighlight lang=bash>
<syntaxHighlight lang=bash>
cd ~/libdep-src-checkout/
cd ~/libdep-src-checkout/
Line 685: Line 761:
installPhase # install it like nix does
installPhase # install it like nix does
</syntaxHighlight>
</syntaxHighlight>
<translate>
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>
<syntaxHighlight lang=bash>
<syntaxHighlight lang=bash>
cd ~/consumexe-src-checkout/
cd ~/consumexe-src-checkout/
Line 692: Line 772:
# 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>
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.
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.


Line 698: Line 780:
<!--T:139-->
<!--T:139-->
* [https://nix.dev/concepts/flakes Flakes] - nix.dev
* [https://nix.dev/concepts/flakes Flakes] - nix.dev
* [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
* [https://jade.fyi/blog/flakes-arent-real/ Flakes aren't real and can't hurt you] (Jade Lovelace, 2024)
* [https://jade.fyi/blog/flakes-arent-real/ Flakes aren't real and can't hurt you] (Jade Lovelace, 2024)
* [https://github.com/ryan4yin/nixos-and-flakes-book NixOS & Flakes Book](Ryan4yin, 2023) - 🛠️ ❤️ An unofficial NixOS & Flakes book for beginners.
* [https://github.com/ryan4yin/nixos-and-flakes-book NixOS & Flakes Book](Ryan4yin, 2023) - 🛠️ ❤️ An unofficial NixOS & Flakes book for beginners.
* [https://xeiaso.net/blog/nix-flakes-1-2022-02-21 Nix Flakes: an Introduction] (Xe Iaso, 2022)
* [https://xeiaso.net/blog/nix-flakes-1-2022-02-21 Nix Flakes: an Introduction] (Xe Iaso, 2022)
* [https://serokell.io/blog/practical-nix-flakes Practical Nix Flakes] (Alexander Bantyev, 2021) - Intro article on working with Nix and Flakes
* [https://serokell.io/blog/practical-nix-flakes Practical Nix Flakes] (Alexander Bantyev, 2021) - Intro article on working with Nix and Flakes
* [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-05-25-flakes/ Nix Flakes, Part 1: An introduction and tutorial] (Eelco Dolstra, 2020)
* [https://www.tweag.io/blog/2020-06-25-eval-cache/ Nix Flakes, Part 2: Evaluation caching] (Eelco Dolstra, 2020)
* [https://www.tweag.io/blog/2020-06-25-eval-cache/ Nix Flakes, Part 2: Evaluation caching] (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.tweag.io/blog/2020-07-31-nixos-flakes/ Nix Flakes, Part 3: Managing NixOS systems] (Eelco Dolstra, 2020)
* [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://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://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)
* [https://github.com/NixOS/nix/blob/master/src/nix/flake.md spec describing flake inputs in more detail]
* [https://github.com/NixOS/nix/blob/master/src/nix/flake.md spec describing flake inputs in more detail]
* [https://github.com/numtide/flake-utils flake-utils: Library to avoid some boiler-code when writing flakes]
* [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]
* [https://zimbatm.com/NixFlakes/#direnv-integration zimbat's direnv article]
* [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>
<!--T:140-->
[[Category:Software]]
[[Category:Software]]
[[Category:Nix]]
[[Category:Nix]]
[[Category:Flakes]]
[[Category:Flakes]]
</translate>

Revision as of 12:33, 30 July 2024

Nix flakes is an experimental feature that was introduced with Nix 2.4 (see release notes).

Introduction

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.

  • A flake refers to a file-system tree whose root directory contains the Nix file specification called flake.nix.
  • The contents of flake.nix file follow a uniform naming schema for declaring packages and their dependencies in the Nix language.
  • Flakes also allow for locking references and versions that can then be queried and updated programmatically.

Enable flakes temporarily

When using any nix command, add the following command-line options:

 --experimental-features 'nix-command flakes'

Enable flakes permanently in NixOS

Add the following to the NixOS configuration:

  nix.settings.experimental-features = [ "nix-command" "flakes" ];
Other Distros, with Home-Manager

Add the following to your home-manager config:

  nix.settings.experimental-features = [ "nix-command" "flakes" ];
Other Distros, without Home-Manager
Note: The Determinate Nix Installer enables flakes by default.

Add the following to ~/.config/nix/nix.conf or /etc/nix/nix.conf:

experimental-features = nix-command flakes

Basic Usage of Flake

Before running any nix commands at this point, please note the two warnings below: one for encryption and the other for git.

Encryption WARNING

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 secret managing scheme.

Git WARNING

For flakes in git repos, only files in the working tree will be copied to the store.

Therefore, if you use git for your flake, ensure to git add any project files after you first create them.

See also https://www.tweag.io/blog/2020-05-25-flakes/

Generate flake.nix file

To start the basic usage of flake, run the flake command in the project directory:

nix flake init

Flake schema

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

It has 4 top-level attributes:

  • description is a string describing the flake.
  • inputs is an attribute set of all the dependencies of the flake. The schema is described below.
  • outputs 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.
  • nixConfig is an attribute set of values which reflect the 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.

Input schema

The nix flake inputs manual.

The nix flake references manual.

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.

Nixpkgs can be defined using the following code:

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

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.

For example, adding Hyprland as an input would look something like this:

inputs.hyprland.url = "github:hyprwm/Hyprland";

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:

inputs.hyprland.inputs.nixpkgs.follows = "nixpkgs";

Using curly brackets({}), we can shorten all of this and put it in a table. The code will look something like this:

inputs = {
  nixpkgs.url = "github:NixOS/nixpkgs/<branch name>";
  hyprland = {
    url = "github:hyprwm/Hyprland";
    inputs.nixpkgs.follows = "nixpkgs";
  };
};

Output schema

This is described in the nix package manager src/nix/flake-check.md.

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.

Where:

  • <system> is something like "x86_64-linux", "aarch64-linux", "i686-linux", "x86_64-darwin"
  • <name> is an attribute name like "hello".
  • <flake> is a flake name like "nixpkgs".
  • <store-path> is a /nix/store.. path
{ self, ... }@inputs:
{
  # Executed by `nix flake check`
  checks."<system>"."<name>" = derivation;
  # Executed by `nix build .#<name>`
  packages."<system>"."<name>" = derivation;
  # Executed by `nix build .`
  packages."<system>".default = derivation;
  # Executed by `nix run .#<name>`
  apps."<system>"."<name>" = {
    type = "app";
    program = "<store-path>";
  };
  # Executed by `nix run . -- <args?>`
  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>`
  legacyPackages."<system>"."<name>" = derivation;
  # Overlay, consumed by other flakes
  overlays."<name>" = final: prev: { };
  # Default overlay
  overlays.default = final: prev: { };
  # Nixos module, consumed by other flakes
  nixosModules."<name>" = { config, ... }: { options = {}; config = {}; };
  # Default module
  nixosModules.default = { config, ... }: { options = {}; config = {}; };
  # Used with `nixos-rebuild switch --flake .#<hostname>`
  # nixosConfigurations."<hostname>".config.system.build.toplevel must be a derivation
  nixosConfigurations."<hostname>" = {};
  # Used by `nix develop .#<name>`
  devShells."<system>"."<name>" = derivation;
  # Used by `nix develop`
  devShells."<system>".default = derivation;
  # Hydra build jobs
  hydraJobs."<attr>"."<system>" = derivation;
  # Used by `nix flake init -t <flake>#<name>`
  templates."<name>" = {
    path = "<store-path>";
    description = "template description goes here?";
  };
  # Used by `nix flake init -t <flake>`
  templates.default = { path = "<store-path>"; description = ""; };
}

You can also define additional arbitrary attributes, but these are the outputs that Nix knows about.

nix run

When output apps.<system>.myapp is not defined, nix run myapp runs <packages or legacyPackages.<system>.myapp>/bin/<myapp.meta.mainProgram or myapp.pname or myapp.name (the non-version part)>

Using flakes with stable Nix

There exists the flake-compat library that you can use to shim default.nix and shell.nix files. It will download the inputs of the flake, pass them to the flake’s outputs function and return an attribute set containing defaultNix and shellNix attributes. The attributes will contain the output attribute set with an extra default attribute pointing to current platform’s defaultPackage (resp. devShell for shellNix).

Place the following into default.nix (for shell.nix, replace defaultNix with shellNix) to use the shim:

(import (
  fetchTarball {
    url = "https://github.com/edolstra/flake-compat/archive/12c64ca55c1014cdc1b16ed5a804aa8576601ff2.tar.gz";
    sha256 = "0jm6nzb83wa6ai17ly9fzpqc40wg1viib8klq8lby54agpl213w5"; }
) {
  src =  ./.;
}).defaultNix

You can also use the lockfile to make updating the hashes easier using nix flake lock --update-input flake-compat. Add the following to your flake.nix:

  inputs.flake-compat = {
    url = "github:edolstra/flake-compat";
    flake = false;
  };

and add flake-compat to the arguments of outputs attribute. Then you will be able to use default.nix like the following:

(import (
  let
    lock = builtins.fromJSON (builtins.readFile ./flake.lock);
    nodeName = lock.nodes.root.inputs.flake-compat;
  in
  fetchTarball {
    url =
      lock.nodes.${nodeName}.locked.url
        or "https://github.com/edolstra/flake-compat/archive/${lock.nodes.${nodeName}.locked.rev}.tar.gz";
    sha256 = lock.nodes.${nodeName}.locked.narHash;
  }
) { src = ./.; }).defaultNix

Accessing flakes from Nix expressions

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 (builtins.getFlake "/path/to/directory").packages.x86_64-linux.default, where 'directory' is the directory that contains your flake.nix.

Making your evaluations pure

Nix flakes run in pure evaluation mode, which is underdocumented. Some tips for now:

  • fetchurl and fetchtar require a sha256 argument to be considered pure.
  • 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.
  • Imports from channels like <nixpkgs> can be made pure by instead importing from the output function in flake.nix, where the arguments provide the store path to the flake's inputs:
 outputs = { self, nixpkgs, ... }:
  {
    nixosConfigurations.machine = nixpkgs.lib.nixosSystem {
      modules = [
        "${nixpkgs}/nixos/modules/<some-module>.nix"
        ./machine.nix
      ];
    };
  };

The nix flakes command

The nix flake subcommand is described in command reference page of the unstable manual.

Install packages with `nix profile`

nix profile install in the manual

Using nix flakes with NixOS

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

A basic nixos flake.nix could look like this:

{
  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 ];
    };
  };
}

If you want to pass on the flake inputs to external configuration files, you can use the specialArgs attribute:

{
  inputs.nixpkgs.url = github:NixOS/nixpkgs/nixos-unstable;
  inputs.home-manager.url = github:nix-community/home-manager;

  outputs = { self, nixpkgs, ... }@inputs: {
    nixosConfigurations.fnord = nixpkgs.lib.nixosSystem {
      specialArgs = { inherit inputs; };
      modules = [ ./configuration.nix ];
    };
  };
}

Then, you can access the flake inputs from the file configuration.nix like this:

{ config, lib, inputs, ... }: {
  # do something with home-manager here, for instance:
  imports = [ inputs.home-manager.nixosModules.default ];
  ...
}


nixos-rebuild also allows to specify different flake using the --flake flag (# is optional):

$ sudo nixos-rebuild switch --flake .

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

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

To switch a remote host you can use:

$ nixos-rebuild --flake .#mymachine \
  --target-host mymachine-hostname \
  --build-host mymachine-hostname --fast \
  switch
Warning: Remote building seems to have an issue that's resolved by setting the --fast flag.

Pinning the registry on NixOS

{ inputs, ... }:
{
 nix.registry = {
    nixpkgs.flake = inputs.nixpkgs;
  };
}

To make sure the registry entry is "locked", use the following:

  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");
    };
  };

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 narHash = pkgs.narHash.

Super fast nix-shell

A feature of the nix Flake edition is that Nix evaluations are cached.

Let’s say that your project has a shell.nix file that looks like this:

{
  pkgs ? import <nixpkgs> { },
}:
pkgs.mkShell {
  packages = [ pkgs.nixfmt ];

  shellHook = ''
    # ...
  '';
}

Running nix-shell can be a bit slow and take 1-3 seconds.

Now create a flake.nix file in the same repository:

{
  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 ];
          };
        };
    };
}
}

( If you're in a git repository run `git add flake.nix` so that Nix recognizes it. )

And finally, run nix develop. This is what replaces the old nix-shell invocation.

Exit and run again, this command should now be super fast.

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 nix-direnv

You can easily switch nix shells when you cd into different projects with nix-direnv.

Pushing Flakes to Cachix

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

To push all flake outputs automatically, checkout devour-flake.

Build specific attributes in a flake repository

When in the repository top-level, run nix build .#<attr>. It will look in the legacyPackages and packages output attributes for the corresponding derivation.

Eg, in nixpkgs:

$ nix build .#hello

Building flakes from a Git repo url with submodules

As per nix 2.9.1, git submodules in package src's won't get copied to the nix store, this may cause the build to fail. To workaround this, use:

nix build '.?submodules=1#hello'

See: https://github.com/NixOS/nix/pull/5434

Importing packages from multiple nixpkgs branches

A NixOS config flake could be as follows:

{
  description = "NixOS configuration with two or more channels";

 inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-23.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 system;
                #   config.allowUnfree = true;
                # };
              })
            ];
          }
          ./configuration.nix
        ];
      };
    };
}
# NixOS configuration.nix, can now use "pkgs.package" or "pkgs.unstable.package"
{ pkgs, ... }:
{
  environment.systemPackages = [
    pkgs.firefox
    pkgs.unstable.chromium
  ];
  # ...
}

If the variable nixpkgs points to the flake, you can also define pkgs with overlays with:

pkgs = import nixpkgs { system = "x86_64-linux"; overlays = [ /*the overlay in question*/ ]; };

Getting Instant System Flakes Repl

How to get a nix repl out of your system flake:

$ nix repl

nix-repl> :lf /path/to/flake
Added 18 variables.

nix-repl> nixosConfigurations.myHost.config.networking.hostName
"myHost"

However, this won't be instant upon evaluation if any file changes have been done since your last configuration rebuild. Instead, if one puts:

nix.nixPath = let path = toString ./.; in [ "repl=${path}/repl.nix" "nixpkgs=${inputs.nixpkgs}" ];

In their system flake.nix configuration file, and includes the following file in their root directory flake as repl.nix:

let
  flake = builtins.getFlake (toString ./.);
  nixpkgs = import <nixpkgs> { };
in
{ inherit flake; }
// flake
// builtins
// nixpkgs
// nixpkgs.lib
// flake.nixosConfigurations

(Don't forget to git add repl.nix && nixos-rebuild switch --flake "/etc/nixos") Then one can run (or bind a shell alias):

source /etc/set-environment && nix repl $(echo $NIX_PATH | perl -pe 's|.*(/nix/store/.*-source/repl.nix).*|\1|')

This will launch a repl with access to nixpkgs, lib, and the flake options in a split of a second.

An alternative approach to the above shell alias is omitting repl from nix.nixPath and creating a shell script:

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
];

Enable unfree software

Refer to Unfree Software.

Development tricks

Build a package added in a PR

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

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

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:

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

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

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 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 extra/flake.nix):

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

Rapid iteration of a direct dependency

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 nix develop --redirect <flake> <directory> command allows you to provide a mutable dependency to your shell as if it were built by Nix.

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

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

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

cd ~/consumexe-src-checkout/
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

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

See also

  • RFC 49 (2019) - Original flakes specification
  • NixOS & Flakes Book(Ryan4yin, 2023) - 🛠️ ❤️ An unofficial NixOS & Flakes book for beginners.