Flakes/en - Revision history

FuzzyBot: Updating to match new version of source page

2026-03-03T15:37:46Z

Updating to match new version of source page

← Older revision		Revision as of 15:37, 3 March 2026
Line 3:		Line 3:
	{{Cleanup}}		{{Cleanup}}

	'''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.		'''Nix flakes''' are an [https://nix.dev/manual/nix/stable/contributing/experimental-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.

	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>.		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>.
Line 80:		Line 80:
	====Nix standalone====		====Nix standalone====

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

	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>:
Line 120:		Line 120:
	description = "Example flake with a devShell";		description = "Example flake with a devShell";

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

	outputs = { self, nixpkgs}:		outputs = { self, nixpkgs }:
	let		let
	system = "x86_64-linux";		system = "x86_64-linux";
Line 150:		Line 150:
	==== Build specific attributes in a flake repository ====		==== Build specific attributes in a flake repository ====

	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:		Running <code>nix build</code> will look in the <code>legacyPackages</code> and <code>packages</code> output attributes for the corresponding [[derivations\|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:

	<syntaxHighlight lang=console>		<syntaxHighlight lang=console>
Line 220:		Line 220:
	=== 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~~].		The output schema is described the [https://nix.dev/manual/nix/2.33/command-ref/new-cli/nix3-flake-check.html#evaluation-checks nix flake check manual page].

	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.		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.
Line 293:		Line 293:
	* {{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.		* {{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.

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

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

FuzzyBot: Updating to match new version of source page

2025-11-20T14:23:06Z

Updating to match new version of source page

← Older revision		Revision as of 14:23, 20 November 2025
Line 16:		Line 16:
	description = "A very basic flake";		description = "A very basic flake";

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

	outputs = { self, nixpkgs }: {		outputs = { self, nixpkgs }: {
			packages.x86_64-linux = {
	packages.x86_64-linux~~.hello~~ = ~~nixpkgs~~.~~legacyPackages~~.x86_64-linux.hello;		default = self.packages.x86_64-linux.hello;
			hello = nixpkgs.legacyPackages.x86_64-linux.hello;
	~~packages.x86_64-linux.default~~ = ~~self~~.~~packages~~.x86_64-linux.hello;		};

	};		};
	}</nowiki>\|name=flake.nix\|lang=nix}}		}</nowiki>\|name=flake.nix\|lang=nix}}

FuzzyBot: Updating to match new version of source page

2025-10-31T19:10:14Z

Updating to match new version of source page

← Older revision		Revision as of 19:10, 31 October 2025
Line 10:		Line 10:

	== Flake file structure ==		== Flake file structure ==

	Minimally, a flake file contains a description of the flake, a set of input dependencies and an output. You can generate a very basic flake file at any time using nix flake init. This will populate the current directory with a file called flake.nix that will contain something akin to:		Minimally, a flake file contains a description of the flake, a set of input dependencies and an output. You can generate a very basic flake file at any time using nix flake init. This will populate the current directory with a file called flake.nix that will contain something akin to:

	{{File\|3=<nowiki>{		{{File\|3=<nowiki>{
	description = "A very basic flake";		description = "A very basic flake";

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

	outputs = { self, nixpkgs }: {		outputs = { self, nixpkgs }: {

	packages.x86_64-linux.hello = nixpkgs.legacyPackages.x86_64-linux.hello;		packages.x86_64-linux.hello = nixpkgs.legacyPackages.x86_64-linux.hello;

	packages.x86_64-linux.default = self.packages.x86_64-linux.hello;		packages.x86_64-linux.default = self.packages.x86_64-linux.hello;

	};		};
	}</nowiki>\|name=flake.nix\|lang=nix}}		}</nowiki>\|name=flake.nix\|lang=nix}}

	In the example above, you can see the description, the input specified as a GitHub repository with a specific branch (here <code>nixos/nixpkgs</code> on the <code>nixos-unstable</code> branch), and an output that makes use of the input. The output simply specifies that the flake contains one package for the x86_64 architecture called <code>hello</code>. Even if your flake's output wouldn't use its input (however, in practice, that is highly unlikely), the output still needs to be a Nix function.		In the example above, you can see the description, the input specified as a GitHub repository with a specific branch (here <code>nixos/nixpkgs</code> on the <code>nixos-unstable</code> branch), and an output that makes use of the input. The output simply specifies that the flake contains one package for the x86_64 architecture called <code>hello</code>. Even if your flake's output wouldn't use its input (however, in practice, that is highly unlikely), the output still needs to be a Nix function.

	{{Note\|Flakes require you to specify its outputs for each architecture separately. For more information, read the related section below.}}		{{Note\|Flakes require you to specify its outputs for each architecture separately. For more information, read the related section below.}}

	=== Nix configuration ===		=== Nix configuration ===

	It is possible to override the global Nix configuration set in your <code>nix.conf</code> file for the purposes of evaluating a flake. This can be useful, for example, for setting up binary caches specific to certain projects, while keeping the global configuration untouched. The flake file can contain a nixConfig attribute with any relevant configuration settings supplied. For example, enabling the nix-community binary cache would be achieved by:		It is possible to override the global Nix configuration set in your <code>nix.conf</code> file for the purposes of evaluating a flake. This can be useful, for example, for setting up binary caches specific to certain projects, while keeping the global configuration untouched. The flake file can contain a nixConfig attribute with any relevant configuration settings supplied. For example, enabling the nix-community binary cache would be achieved by:

	{{File\|3=<nowiki>{		{{File\|3=<nowiki>{
	...		...
Line 41:		Line 47:
	];		];
	}		}
	}</nowiki>\|name=flake.nix\|lang=nix}}{{Note\|If you are used to configuring your Nix settings via the NixOS configuration, these options are under <code>nix.settings</code> and not <code>nix</code>. For example, you cannot specify the automatic storage optimisation under <code>nix.optimisation.enable</code>.}}		}</nowiki>\|name=flake.nix\|lang=nix}}

			{{Note\|If you are used to configuring your Nix settings via the NixOS configuration, these options are under <code>nix.settings</code> and not <code>nix</code>. For example, you cannot specify the automatic storage optimisation under <code>nix.optimisation.enable</code>.}}

	== Setup ==		== Setup ==
Line 48:		Line 56:

	When using any [[Nix command\|<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:

	<syntaxhighlight lang="shell">		<syntaxhighlight lang="shell">
	--experimental-features 'nix-command flakes'		--experimental-features 'nix-command flakes'
	</syntaxhighlight>		</syntaxhighlight>

	=== Enabling flakes permanently ===		=== Enabling flakes permanently ===

Line 78:		Line 88:
	experimental-features = nix-command flakes		experimental-features = nix-command flakes
	</syntaxHighlight>		</syntaxHighlight>

	== Usage ==		== Usage ==

Line 87:		Line 98:

	=== The nix flakes command ===		=== The nix flakes command ===

	{{Main\|Nix (command)}}		{{Main\|Nix (command)}}

Line 109:		Line 121:
	description = "Example flake with a devShell";		description = "Example flake with a devShell";

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

	outputs = { self, nixpkgs}:		outputs = { self, nixpkgs}:
	let		let
	system = "x86_64-linux";		system = "x86_64-linux";
Line 178:		Line 190:

	In this example the input would point to the `nixpkgs-unstable` channel.		In this example the input would point to the `nixpkgs-unstable` channel.


	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 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.
Line 295:		Line 306:
	description = "A flake targeting multiple architectures";		description = "A flake targeting multiple architectures";

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

	outputs = { self, nixpkgs }: let		outputs = { self, nixpkgs }: let
	systems = [ "x86_64-linux" "aarch64-linux" ];		systems = [ "x86_64-linux" "aarch64-linux" ];
	forAllSystems = f: builtins.listToAttrs (map (system: {		forAllSystems = f: builtins.listToAttrs (map (system: {
Line 416:		Line 427:
	# Output should show ~/libdep-src-checkout/ so you know it worked		# Output should show ~/libdep-src-checkout/ so you know it worked
	</syntaxHighlight>		</syntaxHighlight>


	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 461:		Line 473:
	{{references}}		{{references}}

	[[Category:Software]]		[[Category:Software\|Software]]
	[[Category:Nix]]		[[Category:Nix\|Nix]]
	[[Category:Nix Language]]		[[Category:Nix Language\|Nix Language]]
	[[Category:Flakes]]		[[Category:Flakes\|Flakes]]

FuzzyBot: Updating to match new version of source page

2025-10-31T18:43:24Z

Updating to match new version of source page

← Older revision		Revision as of 18:43, 31 October 2025
Line 224:		Line 224:
	* <code><store-path></code> is a <code>/nix/store..</code> path		* <code><store-path></code> is a <code>/nix/store..</code> path

	<~~syntaxHighlight~~ lang=nix>		<syntaxhighlight lang="nix">
	{ self, ... }@inputs:		{ self, ... }@inputs:
	{		{
Line 237:		Line 237:
	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 271:
	templates.default = { path = "<store-path>"; description = ""; };		templates.default = { path = "<store-path>"; description = ""; };
	}		}
	</~~syntaxHighlight~~>		</syntaxhighlight>

	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.

FuzzyBot: Updating to match new version of source page

2025-10-07T20:51:21Z

Updating to match new version of source page

← Older revision		Revision as of 20:51, 7 October 2025
Line 190:		Line 190:
	<code>inputs.hyprland.inputs.nixpkgs.follows = "nixpkgs";</code>		<code>inputs.hyprland.inputs.nixpkgs.follows = "nixpkgs";</code>

	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:

	<syntaxhighlight lang="nix">		<syntaxhighlight lang="nix">

FuzzyBot: Updating to match new version of source page

2025-07-24T12:07:12Z

Updating to match new version of source page

Show changes

FuzzyBot: Updating to match new version of source page

2024-07-30T12:36:34Z

Updating to match new version of source page

Show changes

FuzzyBot: Updating to match new version of source page

2024-07-30T09:45:17Z

Updating to match new version of source page

New page

'''Nix flakes''' is an [https://nixos.org/manual/nix/stable/contributing/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]).

====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 [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.
* 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.
* 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.

====Enable flakes temporarily====

When using any <code>nix</code> command, add the following command-line options:
<syntaxhighlight lang="shell">
--experimental-features 'nix-command flakes'
</syntaxhighlight>

====Enable flakes permanently in NixOS====

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

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

=====Other Distros, with Home-Manager=====

Add the following to your home-manager config:

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

=====Other Distros, without Home-Manager=====

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

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

<syntaxHighlight lang=text>
experimental-features = nix-command flakes
</syntaxHighlight>

===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 [[Comparison of secret managing schemes|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 <code>git</code> for your flake, ensure to <code>git add</code> 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:

<syntaxHighlight lang=text>
nix flake init
</syntaxHighlight>

== 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:

* <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>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.

=== Input schema ===

[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].

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:

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

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:

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

<code>inputs.hyprland.inputs.nixpkgs.follows = "nixpkgs";</code>

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">
inputs = {
nixpkgs.url = "github:NixOS/nixpkgs/<branch name>";
hyprland = {
url = "github:hyprwm/Hyprland";
inputs.nixpkgs.follows = "nixpkgs";
};
};
</syntaxhighlight>

=== 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].

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:

* <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><flake></code> is a flake name like "nixpkgs".
* <code><store-path></code> is a <code>/nix/store..</code> path

<syntaxHighlight lang=nix>
{ 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 = ""; };
}
</syntaxHighlight>

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

==== 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>

== Using flakes with stable Nix ==

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

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

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

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

<syntaxHighlight lang=nix>
inputs.flake-compat = {
url = "github:edolstra/flake-compat";
flake = false;
};
</syntaxHighlight>

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

<syntaxhighlight lang="nix">
(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
</syntaxhighlight>

== 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 <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 ==

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

* 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.
* 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:

<syntaxhighlight lang="nix">
outputs = { self, nixpkgs, ... }:
{
nixosConfigurations.machine = nixpkgs.lib.nixosSystem {
modules = [
"${nixpkgs}/nixos/modules/<some-module>.nix"
./machine.nix
];
};
};
</syntaxhighlight>

== The nix flakes command ==

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` ==

[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 ==

{{Ic|nixos-rebuild switch}} will read its configuration from <code>/etc/nixos/flake.nix</code> if it is present.

A basic nixos flake.nix could look like this:

<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>
If you want to pass on the flake inputs to external configuration files, you can use the <code>specialArgs</code> attribute:
<syntaxhighlight lang="nix">
{
inputs.nixpkgs.url = github:NixOS/nixpkgs/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 ];
};
};
}
</syntaxhighlight>
Then, you can access the flake inputs from the file <code>configuration.nix</code> like this:
<syntaxhighlight lang="nix">
{ config, lib, inputs, ... }: {
# do something with home-manager here, for instance:
imports = [ inputs.home-manager.nixosModules.default ];
...
}
</syntaxhighlight>

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

<syntaxhighlight lang="console">
$ sudo nixos-rebuild switch --flake .
</syntaxhighlight>

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

<syntaxhighlight lang="console">
$ sudo nixos-rebuild switch --flake /etc/nixos#joes-desktop
</syntaxhighlight>

To switch a remote host you can use:
<syntaxhighlight lang="bash">
$ nixos-rebuild --flake .#mymachine \
--target-host mymachine-hostname \
--build-host mymachine-hostname --fast \
switch
</syntaxhighlight>

{{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 ==

<syntaxhighlight lang="nix">
{ inputs, ... }:
{
nix.registry = {
nixpkgs.flake = inputs.nixpkgs;
};
}
</syntaxhighlight>

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

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

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 ==

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

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

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

shellHook = ''
# ...
'';
}
</syntaxhighlight>

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

Now create a <code>flake.nix</code> file in the same repository:

<syntaxhighlight lang="nix">
{
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>

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

And finally, run <code>nix develop</code>. 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 [https://github.com/nix-community/nix-direnv nix-direnv].

== Pushing Flakes to Cachix ==

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

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

== Build specific attributes in a flake repository ==

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.

Eg, in nixpkgs:

<syntaxHighlight lang=console>
$ nix build .#hello
</syntaxHighlight>

=== Building flakes from a Git repo url with submodules ===

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:

<syntaxhighlight lang="console">
nix build '.?submodules=1#hello'
</syntaxhighlight>

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

== Importing packages from multiple nixpkgs branches ==

A NixOS config flake could be as follows:
<syntaxhighlight lang="nix">
{
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
];
};
};
}
</syntaxhighlight>

<syntaxhighlight lang="nix">
# NixOS configuration.nix, can now use "pkgs.package" or "pkgs.unstable.package"
{ pkgs, ... }:
{
environment.systemPackages = [
pkgs.firefox
pkgs.unstable.chromium
];
# ...
}
</syntaxhighlight>If the variable <code>nixpkgs</code> points to the flake, you can also define <code>pkgs</code> with overlays with:

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

== Getting ''Instant'' System Flakes Repl ==

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

<syntaxhighlight lang="text">
$ nix repl

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

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

</syntaxhighlight>

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

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

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

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

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

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

An alternative approach to the above shell alias is omitting <code>repl</code> from <code>nix.nixPath</code> and creating a shell script:
<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>

== Enable unfree software ==

Refer to [[Unfree software|Unfree Software]].

== Development tricks ==
=== Build a package added in a PR ===
<syntaxHighlight>
nix build github:nixos/nixpkgs?ref=pull/<PR_NUMBER>/head#<PACKAGE>
</syntaxHighlight>
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:
<syntaxHighlight>
git fetch upstream pull/<PR_NUMBER>/head && git checkout FETCH_HEAD && nix build .#PACKAGE
</syntaxHighlight>
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 [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>):

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

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

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:

<syntaxHighlight lang=bash>
cd ~/libdep-src-checkout/
nix develop # Or `nix-shell` if applicable.
export prefix="./install" # configure nix to install it here
buildPhase # build it like nix does
installPhase # install it like nix does
</syntaxHighlight>
Now that you've built the dependency, <code>consumexe</code> can take it as an input. '''In another terminal''':
<syntaxHighlight lang=bash>
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
</syntaxHighlight>
If Nix warns you that your redirected flake isn't actually used as an input to the evaluated flake, try using the <code>--inputs-from .</code> flag. If all worked well you should be able to <code>buildPhase && installPhase</code> when the dependency changes and rebuild your consumer with the new version ''without'' exiting the development shell.

== See also ==

* [https://nix.dev/concepts/flakes Flakes] - nix.dev
* [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://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://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-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://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://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://zimbatm.com/NixFlakes/#direnv-integration zimbat's direnv article]
* [https://github.com/nix-community/todomvc-nix building Rust and Haskell flakes]

[[Category:Software]]
[[Category:Nix]]
[[Category:Flakes]]