Official NixOS Wiki - User contributions [en]

Flakes

2026-01-22T16:47:33Z

Pigs: Update link to manual to use stable instead of hard coded version

<languages />

{{Cleanup}}

<translate>

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


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

== Flake file structure == 


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

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

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

outputs = { self, nixpkgs }: {
packages.x86_64-linux = {
default = self.packages.x86_64-linux.hello;
hello = nixpkgs.legacyPackages.x86_64-linux.hello;
};
};
}</nowiki>|name=flake.nix|lang=nix}}

<translate>

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

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

{{File|3=<nowiki>{
...
nixConfig = {
extra-substituters = [
"https://nix-community.cachix.org"
];
extra-trusted-public-keys = [
"nix-community.cachix.org-1:...="
];
}
}</nowiki>|name=flake.nix|lang=nix}}

<translate>

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

=== Enabling flakes temporarily === 


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

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

<translate>
=== Enabling flakes permanently === 

==== NixOS ==== 


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

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

<translate>
====Home Manager==== 


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

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

<translate>
====Nix standalone==== 


{{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>:
</translate>

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

<translate>
== Usage == 


{{Warning | Since contents of flake files are copied to the world-readable [[Nix_package_manager#Nix_store|Nix store]] folder, do not put any unencrypted secrets in flake files. You should instead use a [[Comparison of secret managing schemes|secret managing scheme]].}}


{{Note | For flakes in [[git]] repositories, 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.}}

=== The nix flakes command === 
</translate>

{{Main|Nix (command)}}

<translate>

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


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

<syntaxhighlight lang="console">
$ nix flake show
└───packages
└───x86_64-linux
├───default: package 'hello-2.12.2'
└───hello: package 'hello-2.12.2'
</syntaxhighlight>

<translate>
==== Development shells ==== 


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

<syntaxhighlight lang="nix">
{
description = "Example flake with a devShell";

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

outputs = { self, nixpkgs }:
let
system = "x86_64-linux";
pkgs = import nixpkgs { inherit system; };
in {
devShells.x86_64-linux.default = pkgs.mkShell {
buildInputs = with pkgs; [
hello
];
shellHook = ''
echo "Welcome to the devShell!"
'';
};
};
}
</syntaxhighlight>

<translate>

To enter the development shell environment:
</translate>

<syntaxhighlight lang="console">
$ nix develop
</syntaxhighlight>

<translate>

{{note|You don’t need to define a devShell to enter a development shell using nix develop.
If no devShell is defined, nix develop will drop you into an environment containing the default build dependencies of the flake (if any).}}

==== Build specific attributes in a flake repository ==== 


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:
</translate>

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

<translate>

Likewise, you can specify an attribute with the run command: <code>nix run .#hello</code> and the develop command: <code>nix develop .#hello</code>.

== Flake schema == 


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|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:
</translate>

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

<translate>

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

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

<translate>

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 example, adding [[Hyprland]] as an input would look something like this:
</translate>

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

<translate>

If you want to make Hyprland follow the nixpkgs input to avoid having multiple versions of nixpkgs, this can be done using the following code:
</translate>

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

<translate>

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

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

<translate>

By default, Git submodules in package <code>src</code>'s won't get copied to the nix store, this may cause the build to fail. Flakes in Git repositories can declare that they need Git submodules to be enabled. Since Nix version [https://discourse.nixos.org/t/nix-2-27-0-released/62003 2.27], you can enable submodules by:
</translate>

<syntaxhighlight lang="nix">
inputs.self.submodules = true;
</syntaxhighlight>

<translate>
=== Output schema === 


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.


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

<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>";
meta = {description = "..."; inherit otherMetaAttrs; };
};
# Executed by `nix run . -- <args?>`
apps."<system>".default = { type = "app"; program = "..."; meta = {description = "..."; inherit otherMetaAttrs; }; };

# Formatter (alejandra, nixfmt, treefmt-nix 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>

<translate>

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

== Core usage patterns == 

=== Making your evaluations pure === 


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


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

=== Defining a flake for multiple architectures === 


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

<syntaxhighlight lang="nix">
{
description = "A flake targeting multiple architectures";

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

outputs = { self, nixpkgs }: let
systems = [ "x86_64-linux" "aarch64-linux" ];
forAllSystems = f: builtins.listToAttrs (map (system: {
name = system;
value = f system;
}) systems);
in {
packages = forAllSystems (system: let
pkgs = nixpkgs.legacyPackages.${system};
in {
hello = pkgs.hello;
default = pkgs.hello;
});
};
}
</syntaxhighlight>

<translate>

You can also use third-parties projects like [[Flake Utils|flake-utils]] or [[Flake Parts|flake-parts]] that automatically provide code to avoid this boilerplate. To avoid re-defining the program multiple times, refer to [[Flake Utils#Defining a flake for multiple architectures]]

=== Using overlays === 


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

=== Enable unfree software === 


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

<syntaxhighlight lang="nix">
{
inputs.nixpkgs.url = "github:nixos/nixpkgs?ref=nixos-unstable";
outputs = { self, nixpkgs, flake-compat }:
let
system = "x86_64-linux";
pkgs = import nixpkgs { inherit system; config.allowUnfree = true;};
in {
...
};
}
</syntaxhighlight>

<translate>
== NixOS configuration with flakes == 


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


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

== Development tricks == 

=== Automatically switch nix shells with direnv === 


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

=== Pushing Flakes to Cachix === 
</translate>

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

<translate>
=== Flake support in projects without flakes === 


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


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

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

=== Efficiently build multiple flake outputs === 


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

=== Build a package added in a PR === 
</translate>

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

<translate>

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:
</translate>

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

<translate>

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>):
</translate>

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

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

<syntaxHighlight lang=bash>
cd ~/libdep-src-checkout/
nix develop # Or `nix-shell` if applicable.
export prefix="./install" # configure nix to install it here
buildPhase # build it like nix does
installPhase # install it like nix does
</syntaxHighlight>

<translate>

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

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

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

== See also == 

=== Official sources === 


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


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


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


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

=== Guides === 


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

=== Useful flake modules === 


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


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


* [[Flake Compat|flake-compat]]: A compatibility layer for flakes


* [https://github.com/nix-community/todomvc-nix building Rust and Haskell flakes]
</translate>

{{references}}

<translate>

[[Category:Software|Software]]
[[Category:Nix|Nix]]
[[Category:Nix Language|Nix Language]]
[[Category:Flakes|Flakes]]
</translate>

Emacs

2026-01-09T23:24:42Z

Pigs: /* Configuration */ provide a clearer list of possible ways to configure emacs

{{application infobox
|name=GNU Emacs
|image=EmacsIcon.svg
|type=Text Editor
|firstRelease=1985; 40 years ago
|license=[https://www.gnu.org/licenses/gpl.html GNU General Public License]
|os=Cross-platform
|website=[https://www.gnu.org/software/emacs gnu.org/emacs]
|github=
}}
Emacs is a free and open-source text editor known for its exceptional extensibility and adaptability. It can be customized into anything from a simple editor to a full development environment or productivity tool. Emacs features built-in self-documentation, syntax-aware editing, and a vast ecosystem of community-developed packages.<ref>https://www.gnu.org/software/emacs/</ref>

For an easier introduction, [https://doomemacs.org Doom Emacs] offers a pre-configured Emacs framework with modern defaults and features like IDE tools, note-taking, and task management.

There is an official Matrix room for Nix/Emacs: [https://matrix.to/#/#emacs:nixos.org #emacs:nixos.org].

== Installation ==

==== Shell ====

To temporarily use Emacs in a shell environment without modifying your system configuration, you can run:
{{Commands|
<nowiki>
$ nix-shell -p emacs
</nowiki>
}}
This makes the Emacs editor available in your current shell. You can then launch Emacs by typing <code>emacs</code>.

==== System setup ====

To install Emacs system-wide, making it available to all users, add the following to your configuration:

{{file|/etc/nixos/configuration.nix|nix|
<nowiki>
environment.systemPackages = [
pkgs.emacs
];
</nowiki>
}}

Alternatively, Emacs can be installed specific to a user via [[Home Manager]]:

{{file|home.nix|nix|<nowiki>
home.packages = [
pkgs.emacs
];
</nowiki>
}}

After rebuilding your system with <code>nixos-rebuild switch</code> or <code>home-manager switch</code>, Emacs will be installed and accessible.

== Configuration ==

==== NixOS System Configuration ====

System wide configuration of Emacs is limited to only the [https://www.gnu.org/software/emacs/manual/html_node/emacs/Emacs-Server.html Emacs daemon]. To enable Emacs daemon user services system-wide and set as default editor:

{{file|/etc/nixos/configuration.nix|nix|<nowiki>
services.emacs = {
enable = true;
defaultEditor = true;
};
</nowiki>
}}

Use <code>emacsclient</code> to connect to the daemon. For a full list of module configuration options, see {{nixos:option|services.emacs}}.

==== Home Manager ====

[[Home Manager]] provides a larger set of user-specific configuration options for Emacs.

A minimal configuration that installs Emacs alongside <code>nix-mode</code> and <code>nixfmt</code> packages:

{{file|home.nix|nix|<nowiki>
programs.emacs = {
enable = true;
package = pkgs.emacs; # replace with pkgs.emacs-gtk if desired
extraPackages = epkgs: [
epkgs.nix-mode
epkgs.nixfmt
];
extraConfig = ''
(setq standard-indent 2)
'';
};
</nowiki>
}}

{{note| An alternative option to setting the config inside a Nix string, you can load the config file by <code>extraConfig <nowiki>=</nowiki> builtins.readFile ./emacs_config.el</code>.}}

To search for Emacs plugins within the package set, see {{nixos:package|emacsPackages.*}}. A full list of Home Manager configuration module options can be found [https://home-manager-options.extranix.com/?query=programs.emacs here].

Home Manager also provides a configuration module for enabling the Emacs daemon:

{{file|home.nix|nix|<nowiki>
# Emacs is running as a daemon here, accesible via the "emacsclient" command
services.emacs = {
enable = true;
defaultEditor = true;
};
</nowiki>
}}

See [https://home-manager-options.extranix.com/?query=services.emacs the module options] for <code>services.emacs</code> configurations options.

== Tips and Tricks ==

==== Installing Packages ====
{{Note|Emacs, much like NixOS can rebuild and re-fetch all of its packages based on its initialization file alone, if one chooses to use an extension called "use-package". Such a configuration file can be version controlled and used in all compatible operating systems.}}
One can mix and match whether Emacs packages are installed by Nix or Emacs. This can be particularly useful for Emacs packages that need to be built, such as vterm. One way to install Emacs packages through Nix is by the following, replacing {{ic|emacs-pgtk}} with the variant in use:<syntaxhighlight lang="nix">
environment.systemPackages = with pkgs;
[ ...
((emacsPackagesFor emacs-pgtk).emacsWithPackages (
epkgs: [ epkgs.vterm ]
))
...
];

# To make the packages available to emacsclient, one can do the following:
services.emacs.package = with pkgs; (
(emacsPackagesFor emacs-pgtk).emacsWithPackages (
epkgs: [ epkgs.vterm ]
)
);

# Some packages have characters like + that Nix considers a syntax error.
# To fix this, write the package name in quotes and specify the package set, even if using with epkgs;.
# For example, use epkgs."ido-completing-read+".

</syntaxhighlight>Note that if the expression <code>(emacsPackagesFor emacs-pgtk)</code> is present, <code>emacs-pgtk</code> need not be listed separately in the list <code>environment.systemPackages</code>. Indeed, if one does that, <code>nixos-rebuild</code> will warn about link collisions when the configuration is rebuilt.

====== Alternative way of installation to ensuring consistent package management for emacs and emacsclient ======
If you plan to use the same packages for both emacs and emacsclient, you can define a custom emacs like this:
{{file|/etc/nixos/configuration.nix|nix|<nowiki>
nixpkgs.config.packageOverrides = pkgs: rec {
myEmacs = pkgs.emacs.pkgs.withPackages (epkgs: with epkgs; [
org
nixmode
... # list all your desired emacsPackages here
]);
};
</nowiki>}}

You may then reference it twice:

{{file|/etc/nixos/configuration.nix|nix|<nowiki>
## if you want it per-user instead of system-wide use 'users.users.<name>.packages = with pkgs; [' instead
environment.systemPackages = with pkgs; [
myEmacs
];

## enabling emacsclient and making all the packages available
services.emacs = {
enable = true;
package = pkgs.myEmacs;
};
</nowiki>}}

Using this approach, there is no need to keep two lists of emacsPackages in sync.

==== Tree-sitter ====
[[Emacs]] 29 [[emacswiki:Tree-sitter|supports Tree-sitter parsers]] when built with the <code>--with-tree-sitter</code> option. The <code>emacsPackages.treesit-grammars</code> fake package makes them accessible to Emacs when using <code>emacs29.pkgs.withPackages</code>:<ref>https://github.com/NixOS/nixpkgs/pull/230751</ref><syntaxhighlight lang="nix">
{
pkgs ? import <nixpkgs> { },
}:
pkgs.emacs29.pkgs.withPackages (epkgs: [
(epkgs.treesit-grammars.with-grammars (grammars: [ grammars.tree-sitter-bash ]))
])
</syntaxhighlight>

When using Emacs with tree-sitter support, it's recommended to install both <code>epkgs.tree-sitter-langs</code> and <code>epkgs.treesit-grammars</code>. While <code>treesit-grammars</code> handles the registration of grammars with Emacs's native tree-sitter interface, the actual grammar files will come from <code>tree-sitter-langs</code>. <code>tree-sitter-langs</code> being a MELPA package means it receives regular updates when new grammar versions are released, whereas the grammars in the tree-sitter-grammars package may lag behind in nixpkgs. The combination ensures you get both up-to-date grammars and proper integration with Emacs's built-in tree-sitter support.

Bonus Tip:

<code>emacs.pkgs.pretty-sha-path</code> is quality of life improvement for Nix, Guix users.

Allows toggling Guix/Nix store paths by replacing SHA-sequences with ellipsis, i.e.:

<syntaxhighlight lang="bash">/gnu/store/72f54nfp6g1hz873w8z3gfcah0h4nl9p-foo-0.1 → /gnu/store/…-foo-0.1
/nix/store/nh4n4yzb1bx7nss2rg342dz44g14m06x-bar-0.2 → /nix/store/…-bar-0.2</syntaxhighlight>

located at https://github.com/alezost/pretty-sha-path.el

==== Automatic Package Management ====
If you use <code>use-package</code> or <code>leaf</code> in your configuration, the community overlay can manage your Emacs packages automatically by using <code>emacsWithPackagesFromUsePackage</code>. First, install the overlay (instructions above), then add the following to your <code>configuration.nix</code>:
<syntaxhighlight lang="nix">
{
environment.systemPackages = [
(pkgs.emacsWithPackagesFromUsePackage {
package = pkgs.emacsGit; # replace with pkgs.emacsPgtk, or another version if desired.
config = path/to/your/config.el;
# config = path/to/your/config.org; # Org-Babel configs also supported

# Optionally provide extra packages not in the configuration file.
extraEmacsPackages = epkgs: [
epkgs.use-package
];

# Optionally override derivations.
override = epkgs: epkgs // {
somePackage = epkgs.melpaPackages.somePackage.overrideAttrs(old: {
# Apply fixes here
});
};
})
];
}
</syntaxhighlight>

See the [https://github.com/nix-community/emacs-overlay#extra-library-functionality overlay README] for a full list of options.

==== Adding packages from outside ELPA/MELPA ====
Some packages may require more sophisticated derivation, but the following is a good starting point for adding external packages:

{{file|lambda-line.nix|nix|<nowiki>
{
melpaBuild,
fetchFromGitHub,
all-the-icons,
}:
melpaBuild {
pname = "lambda-line";
version = "0-unstable-2022-11-23";
src = fetchFromGitHub {
owner = "Lambda-Emacs";
repo = "lambda-line";
rev = "22186321a7442f1bd3b121f739007bd809cb38f8";
hash = "sha256-2tOXMqpmd14ohzmrRoV5Urf0HlnRPV1EVHm/d8OBSGE=";
};
# elisp dependencies
packageRequires = [
all-the-icons
];
}
</nowiki>}}

You can then use the new package with automatic package management like so:

{{file|configuration.nix|nix|<nowiki>
{
environment.systemPackages = [
(pkgs.emacsWithPackagesFromUsePackage {
...
override = epkgs: epkgs // {
lambda-line = callPackage ./lambda-line.nix {
inherit (pkgs) fetchFromGitHub;
inherit (epkgs) melpaBuild all-the-icons;
};
};
})
];
}
</nowiki>}}

or manual package management like so:

{{file|configuration.nix|nix|<nowiki>
{
environment.systemPackages = with pkgs;
[ ...
((emacsPackagesFor emacs-pgtk).emacsWithPackages (epkgs: [
epkgs.vterm
(callPackage ./lambda-line.nix {
inherit (pkgs) fetchFromGitHub;
inherit (epkgs) melpaBuild all-the-icons;
};)
]))
...
];
}</nowiki>}}

==== Packaging and testing Emacs nixpkgs ====
Emacs packages can be defined and tested like other nixpkgs.
They can be obtained from melpa, elpa or other sources such as github.

{{file|default.nix|nix|<nowiki>
{ melpaBuild
, lib
, fetchFromGitHub
...
}:

melpaBuild {
pname = "...";
version = "...";

src = fetchFromGitHub {
owner = "...";
repo = "...";
rev = "...";
hash = "...";
};

packageRequires = [ ... ];

patches = [ ... ];

meta = {
description = "...";
license = lib.licenses.gpl3Plus;
};
}
</nowiki>}}

They are located at <code>pkgs/applications/editors/emacs/elisp-packages/manual-packages/</code> [https://github.com/NixOS/nixpkgs/tree/master/pkgs/applications/editors/emacs/elisp-packages/manual-packages] and a new pkg must be added under <code>pkgs/applications/editors/elisp-packages/manual-packages.nix</code> [https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/editors/emacs/elisp-packages/manual-packages.nix]. Once the nixpkg is ready, it can be tested using the following command. This inserts the nixpkg into the load-path of Emacs.
{{Commands|
<nowiki>
$ nix-shell -I nixpkgs=<path_to_nixpkgs_copy> -p "(emacsPackagesFor pkgs.emacs28).emacsWithPackages (epkgs: [ epkgs.<package> ])"
</nowiki>
}}

==== Window Manager Integration ====
Out of the box, non-"Mac Port" versions of Emacs will not be picked up properly by window managers like [https://github.com/koekeishiya/yabai Yabai] because [https://github.com/koekeishiya/yabai/issues/86#issuecomment-507537023 Emacs does not set the correct macOS window role]. This can be fixed with a patch (e.g. the first patch in the example above). However, even with the patch, Yabai may not correctly pick up Emacs if you invoke the <code>emacs</code> binary directly from a shell. For Emacs to work properly with window managers you must invoke it by running the macOS app that is generated when you install Emacs with nix. You can setup an alias to do this like so (replace <code>pkgs.emacs</code> with the package you are using):<syntaxhighlight lang="nix">
programs.zsh = {
enable = true;
shellAliases = {
emacs = "${pkgs.emacs}/Applications/Emacs.app/Contents/MacOS/Emacs";
};
};
</syntaxhighlight>

==== Available Emacs Variants ====
{{warning| Certain issues are possible, when mixing different versions of Emacs, in particular a configuration file tailored towards emacs with native compilation, may misbehave on non-native compiling versions, unless only the emacs lisp code is shared between them.}}

===== Stable (nixpkgs) =====
Emacs is available in nixpkgs under the names <code>emacs</code> and <code>emacs-gtk</code>.

[https://github.com/NixOS/nixpkgs/pull/189543 Since 2022-09], the package called <code>emacs</code> now installs the lucid toolkit instead of gtk. The reason is that Emacs is less stable with gtk especially in daemon mode. However, the lucid flavor of Emacs will not take into account the GTK theme (since it is not even GTK) and looks quite… ugly (see comparisons [https://emacs.stackexchange.com/questions/33065/on-linux-why-should-one-choose-lucid-over-gtk-gui-for-emacs here]). If you still prefer the GTK version of Emacs, you can instead install <code>emacs-gtk</code> (before 2022-09 this package does not exist and Emacs defaults to the gtk version).

===== Unstable (community overlay) =====
The [https://github.com/nix-community/emacs-overlay community overlay] provides nightly versions of the Emacs unstable branches, ELPA/MELPA packages, and [https://github.com/ch11ng/exwm EXWM] + its dependencies. '''To use these, first apply the overlay (instructions below), which will make the packages available in nixpkgs.''' Then you can follow the normal nixpkgs installation instructions (above), but use your package of choice from the overlay (e.g. <code>pkgs.emacsGit</code>) in place of <code>pkgs.emacs</code>. See the [https://github.com/nix-community/emacs-overlay#emacs-overlay README] for a complete list of packages provided, and their differences.

====== With flakes ======
Using a system flake, one can specify the specific revision of the overlay as a flake input, for example:<syntaxhighlight lang="nix">
inputs.emacs-overlay.url = "github:nix-community/emacs-overlay/da2f552d133497abd434006e0cae996c0a282394";
</syntaxhighlight>This can then be used in the system configuration by using the {{ic|self}} argument:<syntaxhighlight lang="nix">
nixpkgs.overlays = [ (import self.inputs.emacs-overlay) ];
</syntaxhighlight>

====== Without flakes ======
For installing one of the unstable branches of Emacs, add the following lines to your configuration file:
{{file|configuration.nix|nix|<nowiki>
{
nixpkgs.overlays = [
(import (builtins.fetchGit {
url = "https://github.com/nix-community/emacs-overlay.git";
ref = "master";
rev = "bfc8f6edcb7bcf3cf24e4a7199b3f6fed96aaecf"; # change the revision
}))
];
}
</nowiki>}}

===== Darwin (macOS) =====
Nixpkgs provides several of the "Mac Port" versions of Emacs, which have been patched to provide better integration with macOS (see the [https://nixos.org/manual/nixos/stable/index.html#module-services-emacs-releases NixOS manual entry for a full list of packages]). However, those packages typically track the stable releases of Emacs.

If you would like to use the latest version of Emacs on Darwin, one option is to use a package like <code>emacsPgkt</code> from the community overlay (see above), and apply patches yourself via an override. For example, here is a derivation that applies the patches from the [https://github.com/d12frosted/homebrew-emacs-plus <code>emacs-plus</code> homebrew formula]:

<syntaxhighlight lang="nix">
pkgs.emacsPgtk.overrideAttrs (old: {
patches =
(old.patches or [])
++ [
# Fix OS window role (needed for window managers like yabai)
(fetchpatch {
url = "https://raw.githubusercontent.com/d12frosted/homebrew-emacs-plus/master/patches/emacs-28/fix-window-role.patch";
sha256 = "0c41rgpi19vr9ai740g09lka3nkjk48ppqyqdnncjrkfgvm2710z";
})
# Enable rounded window with no decoration
(fetchpatch {
url = "https://raw.githubusercontent.com/d12frosted/homebrew-emacs-plus/master/patches/emacs-29/round-undecorated-frame.patch";
sha256 = "111i0r3ahs0f52z15aaa3chlq7ardqnzpwp8r57kfsmnmg6c2nhf";
})
# Make Emacs aware of OS-level light/dark mode
(fetchpatch {
url = "https://raw.githubusercontent.com/d12frosted/homebrew-emacs-plus/master/patches/emacs-28/system-appearance.patch";
sha256 = "14ndp2fqqc95s70fwhpxq58y8qqj4gzvvffp77snm2xk76c1bvnn";
})
];
});
};
}
</syntaxhighlight>

== Troubleshooting ==

==== Plasma taskbar grouping ====
To fix/workaround [[KDE|Plasma]] grouping Emacs incorrectly (confusing emacs.desktop with emacsclient.desktop), perform the following:

* Open Emacs
* Right click title bar
* More Actions > Configure Special Window Settings
* Add Property > Desktop File Name
* Set desktop file name to "/home/<USERNAME>/.nix-profile/share/applications/emacs.desktop"
* Apply the changes
* Restart Emacs if need

All Emacs instances should now be grouped together, allowing you to pin it and reliably switch to it with Super+<number>

==== Spell checking ====
Because Emacs expects the dictionaries to be on the same directory as aspell, they won't be picked up. To fix it install the <code>aspellWithDicts</code> package, specifying the dictionaries you want to use:

{{file|configuration.nix|nix|<nowiki>
{
environment.systemPackages = with pkgs; [
(aspellWithDicts (dicts: with dicts; [ en en-computers en-science es]))
];
}
</nowiki>}}

A list of official dictionaries for aspell can be found on [https://ftp.gnu.org/gnu/aspell/dict/0index.html Aspell Website]

== See also ==

* [[Home Manager]] – For declarative Emacs configuration at the user level: [https://nix-community.github.io/home-manager/options.html#opt-programs.emacs.enable Emacs module in Home Manager]
* [https://www.gnu.org/software/emacs/manual/ Emacs Manuals] – Official Emacs documentation.
* [https://search.nixos.org/options?channel=unstable&query=services.emacs NixOS options for Emacs services] – System-level Emacs configuration.
* [https://discourse.nixos.org/search?q=emacs Emacs discussions on NixOS Discourse] – Community tips, troubleshooting, and use cases.
* [https://doomemacs.org Doom Emacs] – A popular Emacs configuration framework.
* [https://github.com/nix-community/emacs-overlay Emacs Overlay on Nixpkgs] – For nightly builds and additional Emacs packages.

== References ==
[[Category:Applications]]
[[Category:CLI Applications]]
[[Category:NixOS Manual]]
[[Category:Text Editor]]

Emacs

2026-01-09T22:31:25Z

Pigs: /* System setup */ make it clear the distinction between installing system wide vs home manager

{{application infobox
|name=GNU Emacs
|image=EmacsIcon.svg
|type=Text Editor
|firstRelease=1985; 40 years ago
|license=[https://www.gnu.org/licenses/gpl.html GNU General Public License]
|os=Cross-platform
|website=[https://www.gnu.org/software/emacs gnu.org/emacs]
|github=
}}
Emacs is a free and open-source text editor known for its exceptional extensibility and adaptability. It can be customized into anything from a simple editor to a full development environment or productivity tool. Emacs features built-in self-documentation, syntax-aware editing, and a vast ecosystem of community-developed packages.<ref>https://www.gnu.org/software/emacs/</ref>

For an easier introduction, [https://doomemacs.org Doom Emacs] offers a pre-configured Emacs framework with modern defaults and features like IDE tools, note-taking, and task management.

There is an official Matrix room for Nix/Emacs: [https://matrix.to/#/#emacs:nixos.org #emacs:nixos.org].

== Installation ==

==== Shell ====

To temporarily use Emacs in a shell environment without modifying your system configuration, you can run:
{{Commands|
<nowiki>
$ nix-shell -p emacs
</nowiki>
}}
This makes the Emacs editor available in your current shell. You can then launch Emacs by typing <code>emacs</code>.

==== System setup ====

To install Emacs system-wide, making it available to all users, add the following to your configuration:

{{file|/etc/nixos/configuration.nix|nix|
<nowiki>
environment.systemPackages = [
pkgs.emacs
];
</nowiki>
}}

Alternatively, Emacs can be installed specific to a user via [[Home Manager]]:

{{file|home.nix|nix|<nowiki>
home.packages = [
pkgs.emacs
];
</nowiki>
}}

After rebuilding your system with <code>nixos-rebuild switch</code> or <code>home-manager switch</code>, Emacs will be installed and accessible.

== Configuration ==
{{Note|Currently, configuring Emacs is possible by using Home Manager. A workaround for a global configuration is highlighted in the advanced section.}}

==== Basic ====
<syntaxhighlight lang="nix">
programs.emacs = {
enable = true;
defaultEditor = true;
};
</syntaxhighlight>

==== Advanced ====
<syntaxhighlight lang="nix">
# Global Configuration
# Emacs is running as a daemon here, accesible via the "emacsclient" command
services.emacs = {
enable = true;
package = pkgs.emacs;
};

# Home Configuration
programs.emacs = {
enable = true;
package = pkgs.emacs; # replace with pkgs.emacs-gtk if desired
extraConfig = ''
(setq standard-indent 2)
'';
};
</syntaxhighlight>

== Tips and Tricks ==

==== Installing Packages ====
{{Note|Emacs, much like NixOS can rebuild and re-fetch all of its packages based on its initialization file alone, if one chooses to use an extension called "use-package". Such a configuration file can be version controlled and used in all compatible operating systems.}}
One can mix and match whether Emacs packages are installed by Nix or Emacs. This can be particularly useful for Emacs packages that need to be built, such as vterm. One way to install Emacs packages through Nix is by the following, replacing {{ic|emacs-pgtk}} with the variant in use:<syntaxhighlight lang="nix">
environment.systemPackages = with pkgs;
[ ...
((emacsPackagesFor emacs-pgtk).emacsWithPackages (
epkgs: [ epkgs.vterm ]
))
...
];

# To make the packages available to emacsclient, one can do the following:
services.emacs.package = with pkgs; (
(emacsPackagesFor emacs-pgtk).emacsWithPackages (
epkgs: [ epkgs.vterm ]
)
);

# Some packages have characters like + that Nix considers a syntax error.
# To fix this, write the package name in quotes and specify the package set, even if using with epkgs;.
# For example, use epkgs."ido-completing-read+".

</syntaxhighlight>Note that if the expression <code>(emacsPackagesFor emacs-pgtk)</code> is present, <code>emacs-pgtk</code> need not be listed separately in the list <code>environment.systemPackages</code>. Indeed, if one does that, <code>nixos-rebuild</code> will warn about link collisions when the configuration is rebuilt.

====== Alternative way of installation to ensuring consistent package management for emacs and emacsclient ======
If you plan to use the same packages for both emacs and emacsclient, you can define a custom emacs like this:
{{file|/etc/nixos/configuration.nix|nix|<nowiki>
nixpkgs.config.packageOverrides = pkgs: rec {
myEmacs = pkgs.emacs.pkgs.withPackages (epkgs: with epkgs; [
org
nixmode
... # list all your desired emacsPackages here
]);
};
</nowiki>}}

You may then reference it twice:

{{file|/etc/nixos/configuration.nix|nix|<nowiki>
## if you want it per-user instead of system-wide use 'users.users.<name>.packages = with pkgs; [' instead
environment.systemPackages = with pkgs; [
myEmacs
];

## enabling emacsclient and making all the packages available
services.emacs = {
enable = true;
package = pkgs.myEmacs;
};
</nowiki>}}

Using this approach, there is no need to keep two lists of emacsPackages in sync.

==== Tree-sitter ====
[[Emacs]] 29 [[emacswiki:Tree-sitter|supports Tree-sitter parsers]] when built with the <code>--with-tree-sitter</code> option. The <code>emacsPackages.treesit-grammars</code> fake package makes them accessible to Emacs when using <code>emacs29.pkgs.withPackages</code>:<ref>https://github.com/NixOS/nixpkgs/pull/230751</ref><syntaxhighlight lang="nix">
{
pkgs ? import <nixpkgs> { },
}:
pkgs.emacs29.pkgs.withPackages (epkgs: [
(epkgs.treesit-grammars.with-grammars (grammars: [ grammars.tree-sitter-bash ]))
])
</syntaxhighlight>

When using Emacs with tree-sitter support, it's recommended to install both <code>epkgs.tree-sitter-langs</code> and <code>epkgs.treesit-grammars</code>. While <code>treesit-grammars</code> handles the registration of grammars with Emacs's native tree-sitter interface, the actual grammar files will come from <code>tree-sitter-langs</code>. <code>tree-sitter-langs</code> being a MELPA package means it receives regular updates when new grammar versions are released, whereas the grammars in the tree-sitter-grammars package may lag behind in nixpkgs. The combination ensures you get both up-to-date grammars and proper integration with Emacs's built-in tree-sitter support.

Bonus Tip:

<code>emacs.pkgs.pretty-sha-path</code> is quality of life improvement for Nix, Guix users.

Allows toggling Guix/Nix store paths by replacing SHA-sequences with ellipsis, i.e.:

<syntaxhighlight lang="bash">/gnu/store/72f54nfp6g1hz873w8z3gfcah0h4nl9p-foo-0.1 → /gnu/store/…-foo-0.1
/nix/store/nh4n4yzb1bx7nss2rg342dz44g14m06x-bar-0.2 → /nix/store/…-bar-0.2</syntaxhighlight>

located at https://github.com/alezost/pretty-sha-path.el

==== Automatic Package Management ====
If you use <code>use-package</code> or <code>leaf</code> in your configuration, the community overlay can manage your Emacs packages automatically by using <code>emacsWithPackagesFromUsePackage</code>. First, install the overlay (instructions above), then add the following to your <code>configuration.nix</code>:
<syntaxhighlight lang="nix">
{
environment.systemPackages = [
(pkgs.emacsWithPackagesFromUsePackage {
package = pkgs.emacsGit; # replace with pkgs.emacsPgtk, or another version if desired.
config = path/to/your/config.el;
# config = path/to/your/config.org; # Org-Babel configs also supported

# Optionally provide extra packages not in the configuration file.
extraEmacsPackages = epkgs: [
epkgs.use-package
];

# Optionally override derivations.
override = epkgs: epkgs // {
somePackage = epkgs.melpaPackages.somePackage.overrideAttrs(old: {
# Apply fixes here
});
};
})
];
}
</syntaxhighlight>

See the [https://github.com/nix-community/emacs-overlay#extra-library-functionality overlay README] for a full list of options.

==== Adding packages from outside ELPA/MELPA ====
Some packages may require more sophisticated derivation, but the following is a good starting point for adding external packages:

{{file|lambda-line.nix|nix|<nowiki>
{
melpaBuild,
fetchFromGitHub,
all-the-icons,
}:
melpaBuild {
pname = "lambda-line";
version = "0-unstable-2022-11-23";
src = fetchFromGitHub {
owner = "Lambda-Emacs";
repo = "lambda-line";
rev = "22186321a7442f1bd3b121f739007bd809cb38f8";
hash = "sha256-2tOXMqpmd14ohzmrRoV5Urf0HlnRPV1EVHm/d8OBSGE=";
};
# elisp dependencies
packageRequires = [
all-the-icons
];
}
</nowiki>}}

You can then use the new package with automatic package management like so:

{{file|configuration.nix|nix|<nowiki>
{
environment.systemPackages = [
(pkgs.emacsWithPackagesFromUsePackage {
...
override = epkgs: epkgs // {
lambda-line = callPackage ./lambda-line.nix {
inherit (pkgs) fetchFromGitHub;
inherit (epkgs) melpaBuild all-the-icons;
};
};
})
];
}
</nowiki>}}

or manual package management like so:

{{file|configuration.nix|nix|<nowiki>
{
environment.systemPackages = with pkgs;
[ ...
((emacsPackagesFor emacs-pgtk).emacsWithPackages (epkgs: [
epkgs.vterm
(callPackage ./lambda-line.nix {
inherit (pkgs) fetchFromGitHub;
inherit (epkgs) melpaBuild all-the-icons;
};)
]))
...
];
}</nowiki>}}

==== Packaging and testing Emacs nixpkgs ====
Emacs packages can be defined and tested like other nixpkgs.
They can be obtained from melpa, elpa or other sources such as github.

{{file|default.nix|nix|<nowiki>
{ melpaBuild
, lib
, fetchFromGitHub
...
}:

melpaBuild {
pname = "...";
version = "...";

src = fetchFromGitHub {
owner = "...";
repo = "...";
rev = "...";
hash = "...";
};

packageRequires = [ ... ];

patches = [ ... ];

meta = {
description = "...";
license = lib.licenses.gpl3Plus;
};
}
</nowiki>}}

They are located at <code>pkgs/applications/editors/emacs/elisp-packages/manual-packages/</code> [https://github.com/NixOS/nixpkgs/tree/master/pkgs/applications/editors/emacs/elisp-packages/manual-packages] and a new pkg must be added under <code>pkgs/applications/editors/elisp-packages/manual-packages.nix</code> [https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/editors/emacs/elisp-packages/manual-packages.nix]. Once the nixpkg is ready, it can be tested using the following command. This inserts the nixpkg into the load-path of Emacs.
{{Commands|
<nowiki>
$ nix-shell -I nixpkgs=<path_to_nixpkgs_copy> -p "(emacsPackagesFor pkgs.emacs28).emacsWithPackages (epkgs: [ epkgs.<package> ])"
</nowiki>
}}

==== Window Manager Integration ====
Out of the box, non-"Mac Port" versions of Emacs will not be picked up properly by window managers like [https://github.com/koekeishiya/yabai Yabai] because [https://github.com/koekeishiya/yabai/issues/86#issuecomment-507537023 Emacs does not set the correct macOS window role]. This can be fixed with a patch (e.g. the first patch in the example above). However, even with the patch, Yabai may not correctly pick up Emacs if you invoke the <code>emacs</code> binary directly from a shell. For Emacs to work properly with window managers you must invoke it by running the macOS app that is generated when you install Emacs with nix. You can setup an alias to do this like so (replace <code>pkgs.emacs</code> with the package you are using):<syntaxhighlight lang="nix">
programs.zsh = {
enable = true;
shellAliases = {
emacs = "${pkgs.emacs}/Applications/Emacs.app/Contents/MacOS/Emacs";
};
};
</syntaxhighlight>

==== Available Emacs Variants ====
{{warning| Certain issues are possible, when mixing different versions of Emacs, in particular a configuration file tailored towards emacs with native compilation, may misbehave on non-native compiling versions, unless only the emacs lisp code is shared between them.}}

===== Stable (nixpkgs) =====
Emacs is available in nixpkgs under the names <code>emacs</code> and <code>emacs-gtk</code>.

[https://github.com/NixOS/nixpkgs/pull/189543 Since 2022-09], the package called <code>emacs</code> now installs the lucid toolkit instead of gtk. The reason is that Emacs is less stable with gtk especially in daemon mode. However, the lucid flavor of Emacs will not take into account the GTK theme (since it is not even GTK) and looks quite… ugly (see comparisons [https://emacs.stackexchange.com/questions/33065/on-linux-why-should-one-choose-lucid-over-gtk-gui-for-emacs here]). If you still prefer the GTK version of Emacs, you can instead install <code>emacs-gtk</code> (before 2022-09 this package does not exist and Emacs defaults to the gtk version).

===== Unstable (community overlay) =====
The [https://github.com/nix-community/emacs-overlay community overlay] provides nightly versions of the Emacs unstable branches, ELPA/MELPA packages, and [https://github.com/ch11ng/exwm EXWM] + its dependencies. '''To use these, first apply the overlay (instructions below), which will make the packages available in nixpkgs.''' Then you can follow the normal nixpkgs installation instructions (above), but use your package of choice from the overlay (e.g. <code>pkgs.emacsGit</code>) in place of <code>pkgs.emacs</code>. See the [https://github.com/nix-community/emacs-overlay#emacs-overlay README] for a complete list of packages provided, and their differences.

====== With flakes ======
Using a system flake, one can specify the specific revision of the overlay as a flake input, for example:<syntaxhighlight lang="nix">
inputs.emacs-overlay.url = "github:nix-community/emacs-overlay/da2f552d133497abd434006e0cae996c0a282394";
</syntaxhighlight>This can then be used in the system configuration by using the {{ic|self}} argument:<syntaxhighlight lang="nix">
nixpkgs.overlays = [ (import self.inputs.emacs-overlay) ];
</syntaxhighlight>

====== Without flakes ======
For installing one of the unstable branches of Emacs, add the following lines to your configuration file:
{{file|configuration.nix|nix|<nowiki>
{
nixpkgs.overlays = [
(import (builtins.fetchGit {
url = "https://github.com/nix-community/emacs-overlay.git";
ref = "master";
rev = "bfc8f6edcb7bcf3cf24e4a7199b3f6fed96aaecf"; # change the revision
}))
];
}
</nowiki>}}

===== Darwin (macOS) =====
Nixpkgs provides several of the "Mac Port" versions of Emacs, which have been patched to provide better integration with macOS (see the [https://nixos.org/manual/nixos/stable/index.html#module-services-emacs-releases NixOS manual entry for a full list of packages]). However, those packages typically track the stable releases of Emacs.

If you would like to use the latest version of Emacs on Darwin, one option is to use a package like <code>emacsPgkt</code> from the community overlay (see above), and apply patches yourself via an override. For example, here is a derivation that applies the patches from the [https://github.com/d12frosted/homebrew-emacs-plus <code>emacs-plus</code> homebrew formula]:

<syntaxhighlight lang="nix">
pkgs.emacsPgtk.overrideAttrs (old: {
patches =
(old.patches or [])
++ [
# Fix OS window role (needed for window managers like yabai)
(fetchpatch {
url = "https://raw.githubusercontent.com/d12frosted/homebrew-emacs-plus/master/patches/emacs-28/fix-window-role.patch";
sha256 = "0c41rgpi19vr9ai740g09lka3nkjk48ppqyqdnncjrkfgvm2710z";
})
# Enable rounded window with no decoration
(fetchpatch {
url = "https://raw.githubusercontent.com/d12frosted/homebrew-emacs-plus/master/patches/emacs-29/round-undecorated-frame.patch";
sha256 = "111i0r3ahs0f52z15aaa3chlq7ardqnzpwp8r57kfsmnmg6c2nhf";
})
# Make Emacs aware of OS-level light/dark mode
(fetchpatch {
url = "https://raw.githubusercontent.com/d12frosted/homebrew-emacs-plus/master/patches/emacs-28/system-appearance.patch";
sha256 = "14ndp2fqqc95s70fwhpxq58y8qqj4gzvvffp77snm2xk76c1bvnn";
})
];
});
};
}
</syntaxhighlight>

== Troubleshooting ==

==== Plasma taskbar grouping ====
To fix/workaround [[KDE|Plasma]] grouping Emacs incorrectly (confusing emacs.desktop with emacsclient.desktop), perform the following:

* Open Emacs
* Right click title bar
* More Actions > Configure Special Window Settings
* Add Property > Desktop File Name
* Set desktop file name to "/home/<USERNAME>/.nix-profile/share/applications/emacs.desktop"
* Apply the changes
* Restart Emacs if need

All Emacs instances should now be grouped together, allowing you to pin it and reliably switch to it with Super+<number>

==== Spell checking ====
Because Emacs expects the dictionaries to be on the same directory as aspell, they won't be picked up. To fix it install the <code>aspellWithDicts</code> package, specifying the dictionaries you want to use:

{{file|configuration.nix|nix|<nowiki>
{
environment.systemPackages = with pkgs; [
(aspellWithDicts (dicts: with dicts; [ en en-computers en-science es]))
];
}
</nowiki>}}

A list of official dictionaries for aspell can be found on [https://ftp.gnu.org/gnu/aspell/dict/0index.html Aspell Website]

== See also ==

* [[Home Manager]] – For declarative Emacs configuration at the user level: [https://nix-community.github.io/home-manager/options.html#opt-programs.emacs.enable Emacs module in Home Manager]
* [https://www.gnu.org/software/emacs/manual/ Emacs Manuals] – Official Emacs documentation.
* [https://search.nixos.org/options?channel=unstable&query=services.emacs NixOS options for Emacs services] – System-level Emacs configuration.
* [https://discourse.nixos.org/search?q=emacs Emacs discussions on NixOS Discourse] – Community tips, troubleshooting, and use cases.
* [https://doomemacs.org Doom Emacs] – A popular Emacs configuration framework.
* [https://github.com/nix-community/emacs-overlay Emacs Overlay on Nixpkgs] – For nightly builds and additional Emacs packages.

== References ==
[[Category:Applications]]
[[Category:CLI Applications]]
[[Category:NixOS Manual]]
[[Category:Text Editor]]

Emacs

2026-01-09T19:51:22Z

Pigs: /* Advanced */ defaultEditor is only an option for services.emacs, not programs.emacs

{{application infobox
|name=GNU Emacs
|image=EmacsIcon.svg
|type=Text Editor
|firstRelease=1985; 40 years ago
|license=[https://www.gnu.org/licenses/gpl.html GNU General Public License]
|os=Cross-platform
|website=[https://www.gnu.org/software/emacs gnu.org/emacs]
|github=
}}
Emacs is a free and open-source text editor known for its exceptional extensibility and adaptability. It can be customized into anything from a simple editor to a full development environment or productivity tool. Emacs features built-in self-documentation, syntax-aware editing, and a vast ecosystem of community-developed packages.<ref>https://www.gnu.org/software/emacs/</ref>

For an easier introduction, [https://doomemacs.org Doom Emacs] offers a pre-configured Emacs framework with modern defaults and features like IDE tools, note-taking, and task management.

There is an official Matrix room for Nix/Emacs: [https://matrix.to/#/#emacs:nixos.org #emacs:nixos.org].

== Installation ==

==== Shell ====

To temporarily use Emacs in a shell environment without modifying your system configuration, you can run:
{{Commands|
<nowiki>
$ nix-shell -p emacs
</nowiki>
}}
This makes the Emacs editor available in your current shell. You can then launch Emacs by typing <code>emacs</code>.

==== System setup ====

To install Emacs system-wide, making it available to all users, add the following to your configuration:
<syntaxhighlight lang="nix">
# Example for /etc/nixos/configuration.nix
environment.systemPackages = [
pkgs.emacs
];

# User-specific installation (in ~/.config/nixpkgs/home.nix)
home.packages = [
pkgs.emacs
];
</syntaxhighlight>
After rebuilding your system with <code>nixos-rebuild switch</code> or <code>home-manager switch</code>, Emacs will be installed and accessible.

== Configuration ==
{{Note|Currently, configuring Emacs is possible by using Home Manager. A workaround for a global configuration is highlighted in the advanced section.}}

==== Basic ====
<syntaxhighlight lang="nix">
programs.emacs = {
enable = true;
defaultEditor = true;
};
</syntaxhighlight>

==== Advanced ====
<syntaxhighlight lang="nix">
# Global Configuration
# Emacs is running as a daemon here, accesible via the "emacsclient" command
services.emacs = {
enable = true;
package = pkgs.emacs;
};

# Home Configuration
programs.emacs = {
enable = true;
package = pkgs.emacs; # replace with pkgs.emacs-gtk if desired
extraConfig = ''
(setq standard-indent 2)
'';
};
</syntaxhighlight>

== Tips and Tricks ==

==== Installing Packages ====
{{Note|Emacs, much like NixOS can rebuild and re-fetch all of its packages based on its initialization file alone, if one chooses to use an extension called "use-package". Such a configuration file can be version controlled and used in all compatible operating systems.}}
One can mix and match whether Emacs packages are installed by Nix or Emacs. This can be particularly useful for Emacs packages that need to be built, such as vterm. One way to install Emacs packages through Nix is by the following, replacing {{ic|emacs-pgtk}} with the variant in use:<syntaxhighlight lang="nix">
environment.systemPackages = with pkgs;
[ ...
((emacsPackagesFor emacs-pgtk).emacsWithPackages (
epkgs: [ epkgs.vterm ]
))
...
];

# To make the packages available to emacsclient, one can do the following:
services.emacs.package = with pkgs; (
(emacsPackagesFor emacs-pgtk).emacsWithPackages (
epkgs: [ epkgs.vterm ]
)
);

# Some packages have characters like + that Nix considers a syntax error.
# To fix this, write the package name in quotes and specify the package set, even if using with epkgs;.
# For example, use epkgs."ido-completing-read+".

</syntaxhighlight>Note that if the expression <code>(emacsPackagesFor emacs-pgtk)</code> is present, <code>emacs-pgtk</code> need not be listed separately in the list <code>environment.systemPackages</code>. Indeed, if one does that, <code>nixos-rebuild</code> will warn about link collisions when the configuration is rebuilt.

====== Alternative way of installation to ensuring consistent package management for emacs and emacsclient ======
If you plan to use the same packages for both emacs and emacsclient, you can define a custom emacs like this:
{{file|/etc/nixos/configuration.nix|nix|<nowiki>
nixpkgs.config.packageOverrides = pkgs: rec {
myEmacs = pkgs.emacs.pkgs.withPackages (epkgs: with epkgs; [
org
nixmode
... # list all your desired emacsPackages here
]);
};
</nowiki>}}

You may then reference it twice:

{{file|/etc/nixos/configuration.nix|nix|<nowiki>
## if you want it per-user instead of system-wide use 'users.users.<name>.packages = with pkgs; [' instead
environment.systemPackages = with pkgs; [
myEmacs
];

## enabling emacsclient and making all the packages available
services.emacs = {
enable = true;
package = pkgs.myEmacs;
};
</nowiki>}}

Using this approach, there is no need to keep two lists of emacsPackages in sync.

==== Tree-sitter ====
[[Emacs]] 29 [[emacswiki:Tree-sitter|supports Tree-sitter parsers]] when built with the <code>--with-tree-sitter</code> option. The <code>emacsPackages.treesit-grammars</code> fake package makes them accessible to Emacs when using <code>emacs29.pkgs.withPackages</code>:<ref>https://github.com/NixOS/nixpkgs/pull/230751</ref><syntaxhighlight lang="nix">
{
pkgs ? import <nixpkgs> { },
}:
pkgs.emacs29.pkgs.withPackages (epkgs: [
(epkgs.treesit-grammars.with-grammars (grammars: [ grammars.tree-sitter-bash ]))
])
</syntaxhighlight>

When using Emacs with tree-sitter support, it's recommended to install both <code>epkgs.tree-sitter-langs</code> and <code>epkgs.treesit-grammars</code>. While <code>treesit-grammars</code> handles the registration of grammars with Emacs's native tree-sitter interface, the actual grammar files will come from <code>tree-sitter-langs</code>. <code>tree-sitter-langs</code> being a MELPA package means it receives regular updates when new grammar versions are released, whereas the grammars in the tree-sitter-grammars package may lag behind in nixpkgs. The combination ensures you get both up-to-date grammars and proper integration with Emacs's built-in tree-sitter support.

Bonus Tip:

<code>emacs.pkgs.pretty-sha-path</code> is quality of life improvement for Nix, Guix users.

Allows toggling Guix/Nix store paths by replacing SHA-sequences with ellipsis, i.e.:

<syntaxhighlight lang="bash">/gnu/store/72f54nfp6g1hz873w8z3gfcah0h4nl9p-foo-0.1 → /gnu/store/…-foo-0.1
/nix/store/nh4n4yzb1bx7nss2rg342dz44g14m06x-bar-0.2 → /nix/store/…-bar-0.2</syntaxhighlight>

located at https://github.com/alezost/pretty-sha-path.el

==== Automatic Package Management ====
If you use <code>use-package</code> or <code>leaf</code> in your configuration, the community overlay can manage your Emacs packages automatically by using <code>emacsWithPackagesFromUsePackage</code>. First, install the overlay (instructions above), then add the following to your <code>configuration.nix</code>:
<syntaxhighlight lang="nix">
{
environment.systemPackages = [
(pkgs.emacsWithPackagesFromUsePackage {
package = pkgs.emacsGit; # replace with pkgs.emacsPgtk, or another version if desired.
config = path/to/your/config.el;
# config = path/to/your/config.org; # Org-Babel configs also supported

# Optionally provide extra packages not in the configuration file.
extraEmacsPackages = epkgs: [
epkgs.use-package
];

# Optionally override derivations.
override = epkgs: epkgs // {
somePackage = epkgs.melpaPackages.somePackage.overrideAttrs(old: {
# Apply fixes here
});
};
})
];
}
</syntaxhighlight>

See the [https://github.com/nix-community/emacs-overlay#extra-library-functionality overlay README] for a full list of options.

==== Adding packages from outside ELPA/MELPA ====
Some packages may require more sophisticated derivation, but the following is a good starting point for adding external packages:

{{file|lambda-line.nix|nix|<nowiki>
{
melpaBuild,
fetchFromGitHub,
all-the-icons,
}:
melpaBuild {
pname = "lambda-line";
version = "0-unstable-2022-11-23";
src = fetchFromGitHub {
owner = "Lambda-Emacs";
repo = "lambda-line";
rev = "22186321a7442f1bd3b121f739007bd809cb38f8";
hash = "sha256-2tOXMqpmd14ohzmrRoV5Urf0HlnRPV1EVHm/d8OBSGE=";
};
# elisp dependencies
packageRequires = [
all-the-icons
];
}
</nowiki>}}

You can then use the new package with automatic package management like so:

{{file|configuration.nix|nix|<nowiki>
{
environment.systemPackages = [
(pkgs.emacsWithPackagesFromUsePackage {
...
override = epkgs: epkgs // {
lambda-line = callPackage ./lambda-line.nix {
inherit (pkgs) fetchFromGitHub;
inherit (epkgs) melpaBuild all-the-icons;
};
};
})
];
}
</nowiki>}}

or manual package management like so:

{{file|configuration.nix|nix|<nowiki>
{
environment.systemPackages = with pkgs;
[ ...
((emacsPackagesFor emacs-pgtk).emacsWithPackages (epkgs: [
epkgs.vterm
(callPackage ./lambda-line.nix {
inherit (pkgs) fetchFromGitHub;
inherit (epkgs) melpaBuild all-the-icons;
};)
]))
...
];
}</nowiki>}}

==== Packaging and testing Emacs nixpkgs ====
Emacs packages can be defined and tested like other nixpkgs.
They can be obtained from melpa, elpa or other sources such as github.

{{file|default.nix|nix|<nowiki>
{ melpaBuild
, lib
, fetchFromGitHub
...
}:

melpaBuild {
pname = "...";
version = "...";

src = fetchFromGitHub {
owner = "...";
repo = "...";
rev = "...";
hash = "...";
};

packageRequires = [ ... ];

patches = [ ... ];

meta = {
description = "...";
license = lib.licenses.gpl3Plus;
};
}
</nowiki>}}

They are located at <code>pkgs/applications/editors/emacs/elisp-packages/manual-packages/</code> [https://github.com/NixOS/nixpkgs/tree/master/pkgs/applications/editors/emacs/elisp-packages/manual-packages] and a new pkg must be added under <code>pkgs/applications/editors/elisp-packages/manual-packages.nix</code> [https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/editors/emacs/elisp-packages/manual-packages.nix]. Once the nixpkg is ready, it can be tested using the following command. This inserts the nixpkg into the load-path of Emacs.
{{Commands|
<nowiki>
$ nix-shell -I nixpkgs=<path_to_nixpkgs_copy> -p "(emacsPackagesFor pkgs.emacs28).emacsWithPackages (epkgs: [ epkgs.<package> ])"
</nowiki>
}}

==== Window Manager Integration ====
Out of the box, non-"Mac Port" versions of Emacs will not be picked up properly by window managers like [https://github.com/koekeishiya/yabai Yabai] because [https://github.com/koekeishiya/yabai/issues/86#issuecomment-507537023 Emacs does not set the correct macOS window role]. This can be fixed with a patch (e.g. the first patch in the example above). However, even with the patch, Yabai may not correctly pick up Emacs if you invoke the <code>emacs</code> binary directly from a shell. For Emacs to work properly with window managers you must invoke it by running the macOS app that is generated when you install Emacs with nix. You can setup an alias to do this like so (replace <code>pkgs.emacs</code> with the package you are using):<syntaxhighlight lang="nix">
programs.zsh = {
enable = true;
shellAliases = {
emacs = "${pkgs.emacs}/Applications/Emacs.app/Contents/MacOS/Emacs";
};
};
</syntaxhighlight>

==== Available Emacs Variants ====
{{warning| Certain issues are possible, when mixing different versions of Emacs, in particular a configuration file tailored towards emacs with native compilation, may misbehave on non-native compiling versions, unless only the emacs lisp code is shared between them.}}

===== Stable (nixpkgs) =====
Emacs is available in nixpkgs under the names <code>emacs</code> and <code>emacs-gtk</code>.

[https://github.com/NixOS/nixpkgs/pull/189543 Since 2022-09], the package called <code>emacs</code> now installs the lucid toolkit instead of gtk. The reason is that Emacs is less stable with gtk especially in daemon mode. However, the lucid flavor of Emacs will not take into account the GTK theme (since it is not even GTK) and looks quite… ugly (see comparisons [https://emacs.stackexchange.com/questions/33065/on-linux-why-should-one-choose-lucid-over-gtk-gui-for-emacs here]). If you still prefer the GTK version of Emacs, you can instead install <code>emacs-gtk</code> (before 2022-09 this package does not exist and Emacs defaults to the gtk version).

===== Unstable (community overlay) =====
The [https://github.com/nix-community/emacs-overlay community overlay] provides nightly versions of the Emacs unstable branches, ELPA/MELPA packages, and [https://github.com/ch11ng/exwm EXWM] + its dependencies. '''To use these, first apply the overlay (instructions below), which will make the packages available in nixpkgs.''' Then you can follow the normal nixpkgs installation instructions (above), but use your package of choice from the overlay (e.g. <code>pkgs.emacsGit</code>) in place of <code>pkgs.emacs</code>. See the [https://github.com/nix-community/emacs-overlay#emacs-overlay README] for a complete list of packages provided, and their differences.

====== With flakes ======
Using a system flake, one can specify the specific revision of the overlay as a flake input, for example:<syntaxhighlight lang="nix">
inputs.emacs-overlay.url = "github:nix-community/emacs-overlay/da2f552d133497abd434006e0cae996c0a282394";
</syntaxhighlight>This can then be used in the system configuration by using the {{ic|self}} argument:<syntaxhighlight lang="nix">
nixpkgs.overlays = [ (import self.inputs.emacs-overlay) ];
</syntaxhighlight>

====== Without flakes ======
For installing one of the unstable branches of Emacs, add the following lines to your configuration file:
{{file|configuration.nix|nix|<nowiki>
{
nixpkgs.overlays = [
(import (builtins.fetchGit {
url = "https://github.com/nix-community/emacs-overlay.git";
ref = "master";
rev = "bfc8f6edcb7bcf3cf24e4a7199b3f6fed96aaecf"; # change the revision
}))
];
}
</nowiki>}}

===== Darwin (macOS) =====
Nixpkgs provides several of the "Mac Port" versions of Emacs, which have been patched to provide better integration with macOS (see the [https://nixos.org/manual/nixos/stable/index.html#module-services-emacs-releases NixOS manual entry for a full list of packages]). However, those packages typically track the stable releases of Emacs.

If you would like to use the latest version of Emacs on Darwin, one option is to use a package like <code>emacsPgkt</code> from the community overlay (see above), and apply patches yourself via an override. For example, here is a derivation that applies the patches from the [https://github.com/d12frosted/homebrew-emacs-plus <code>emacs-plus</code> homebrew formula]:

<syntaxhighlight lang="nix">
pkgs.emacsPgtk.overrideAttrs (old: {
patches =
(old.patches or [])
++ [
# Fix OS window role (needed for window managers like yabai)
(fetchpatch {
url = "https://raw.githubusercontent.com/d12frosted/homebrew-emacs-plus/master/patches/emacs-28/fix-window-role.patch";
sha256 = "0c41rgpi19vr9ai740g09lka3nkjk48ppqyqdnncjrkfgvm2710z";
})
# Enable rounded window with no decoration
(fetchpatch {
url = "https://raw.githubusercontent.com/d12frosted/homebrew-emacs-plus/master/patches/emacs-29/round-undecorated-frame.patch";
sha256 = "111i0r3ahs0f52z15aaa3chlq7ardqnzpwp8r57kfsmnmg6c2nhf";
})
# Make Emacs aware of OS-level light/dark mode
(fetchpatch {
url = "https://raw.githubusercontent.com/d12frosted/homebrew-emacs-plus/master/patches/emacs-28/system-appearance.patch";
sha256 = "14ndp2fqqc95s70fwhpxq58y8qqj4gzvvffp77snm2xk76c1bvnn";
})
];
});
};
}
</syntaxhighlight>

== Troubleshooting ==

==== Plasma taskbar grouping ====
To fix/workaround [[KDE|Plasma]] grouping Emacs incorrectly (confusing emacs.desktop with emacsclient.desktop), perform the following:

* Open Emacs
* Right click title bar
* More Actions > Configure Special Window Settings
* Add Property > Desktop File Name
* Set desktop file name to "/home/<USERNAME>/.nix-profile/share/applications/emacs.desktop"
* Apply the changes
* Restart Emacs if need

All Emacs instances should now be grouped together, allowing you to pin it and reliably switch to it with Super+<number>

==== Spell checking ====
Because Emacs expects the dictionaries to be on the same directory as aspell, they won't be picked up. To fix it install the <code>aspellWithDicts</code> package, specifying the dictionaries you want to use:

{{file|configuration.nix|nix|<nowiki>
{
environment.systemPackages = with pkgs; [
(aspellWithDicts (dicts: with dicts; [ en en-computers en-science es]))
];
}
</nowiki>}}

A list of official dictionaries for aspell can be found on [https://ftp.gnu.org/gnu/aspell/dict/0index.html Aspell Website]

== See also ==

* [[Home Manager]] – For declarative Emacs configuration at the user level: [https://nix-community.github.io/home-manager/options.html#opt-programs.emacs.enable Emacs module in Home Manager]
* [https://www.gnu.org/software/emacs/manual/ Emacs Manuals] – Official Emacs documentation.
* [https://search.nixos.org/options?channel=unstable&query=services.emacs NixOS options for Emacs services] – System-level Emacs configuration.
* [https://discourse.nixos.org/search?q=emacs Emacs discussions on NixOS Discourse] – Community tips, troubleshooting, and use cases.
* [https://doomemacs.org Doom Emacs] – A popular Emacs configuration framework.
* [https://github.com/nix-community/emacs-overlay Emacs Overlay on Nixpkgs] – For nightly builds and additional Emacs packages.

== References ==
[[Category:Applications]]
[[Category:CLI Applications]]
[[Category:NixOS Manual]]
[[Category:Text Editor]]

Flakes

2026-01-05T18:50:02Z

Pigs: fix broken link

<languages />

{{Cleanup}}

<translate>

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


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


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

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

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

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

outputs = { self, nixpkgs }: {
packages.x86_64-linux = {
default = self.packages.x86_64-linux.hello;
hello = nixpkgs.legacyPackages.x86_64-linux.hello;
};
};
}</nowiki>|name=flake.nix|lang=nix}}

<translate>

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

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

{{File|3=<nowiki>{
...
nixConfig = {
extra-substituters = [
"https://nix-community.cachix.org"
];
extra-trusted-public-keys = [
"nix-community.cachix.org-1:...="
];
}
}</nowiki>|name=flake.nix|lang=nix}}

<translate>

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

=== Enabling flakes temporarily === 


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

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

<translate>
=== Enabling flakes permanently === 

==== NixOS ==== 


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

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

<translate>
====Home Manager==== 


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

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

<translate>
====Nix standalone==== 


{{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>:
</translate>

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

<translate>
== Usage == 


{{Warning | Since contents of flake files are copied to the world-readable [[Nix_package_manager#Nix_store|Nix store]] folder, do not put any unencrypted secrets in flake files. You should instead use a [[Comparison of secret managing schemes|secret managing scheme]].}}


{{Note | For flakes in [[git]] repositories, 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.}}

=== The nix flakes command === 
</translate>

{{Main|Nix (command)}}

<translate>

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


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

<syntaxhighlight lang="console">
$ nix flake show
└───packages
└───x86_64-linux
├───default: package 'hello-2.12.2'
└───hello: package 'hello-2.12.2'
</syntaxhighlight>

<translate>
==== Development shells ==== 


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

<syntaxhighlight lang="nix">
{
description = "Example flake with a devShell";

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

outputs = { self, nixpkgs }:
let
system = "x86_64-linux";
pkgs = import nixpkgs { inherit system; };
in {
devShells.x86_64-linux.default = pkgs.mkShell {
buildInputs = with pkgs; [
hello
];
shellHook = ''
echo "Welcome to the devShell!"
'';
};
};
}
</syntaxhighlight>

<translate>

To enter the development shell environment:
</translate>

<syntaxhighlight lang="console">
$ nix develop
</syntaxhighlight>

<translate>

{{note|You don’t need to define a devShell to enter a development shell using nix develop.
If no devShell is defined, nix develop will drop you into an environment containing the default build dependencies of the flake (if any).}}

==== Build specific attributes in a flake repository ==== 


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:
</translate>

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

<translate>

Likewise, you can specify an attribute with the run command: <code>nix run .#hello</code> and the develop command: <code>nix develop .#hello</code>.

== Flake schema == 


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|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:
</translate>

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

<translate>

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

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

<translate>

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 example, adding [[Hyprland]] as an input would look something like this:
</translate>

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

<translate>

If you want to make Hyprland follow the nixpkgs input to avoid having multiple versions of nixpkgs, this can be done using the following code:
</translate>

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

<translate>

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

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

<translate>

By default, Git submodules in package <code>src</code>'s won't get copied to the nix store, this may cause the build to fail. Flakes in Git repositories can declare that they need Git submodules to be enabled. Since Nix version [https://discourse.nixos.org/t/nix-2-27-0-released/62003 2.27], you can enable submodules by:
</translate>

<syntaxhighlight lang="nix">
inputs.self.submodules = true;
</syntaxhighlight>

<translate>
=== Output schema === 


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.


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

<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>";
meta = {description = "..."; inherit otherMetaAttrs; };
};
# Executed by `nix run . -- <args?>`
apps."<system>".default = { type = "app"; program = "..."; meta = {description = "..."; inherit otherMetaAttrs; }; };

# Formatter (alejandra, nixfmt, treefmt-nix 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>

<translate>

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

== Core usage patterns == 

=== Making your evaluations pure === 


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


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

=== Defining a flake for multiple architectures === 


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

<syntaxhighlight lang="nix">
{
description = "A flake targeting multiple architectures";

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

outputs = { self, nixpkgs }: let
systems = [ "x86_64-linux" "aarch64-linux" ];
forAllSystems = f: builtins.listToAttrs (map (system: {
name = system;
value = f system;
}) systems);
in {
packages = forAllSystems (system: let
pkgs = nixpkgs.legacyPackages.${system};
in {
hello = pkgs.hello;
default = pkgs.hello;
});
};
}
</syntaxhighlight>

<translate>

You can also use third-parties projects like [[Flake Utils|flake-utils]] or [[Flake Parts|flake-parts]] that automatically provide code to avoid this boilerplate. To avoid re-defining the program multiple times, refer to [[Flake Utils#Defining a flake for multiple architectures]]

=== Using overlays === 


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

=== Enable unfree software === 


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

<syntaxhighlight lang="nix">
{
inputs.nixpkgs.url = "github:nixos/nixpkgs?ref=nixos-unstable";
outputs = { self, nixpkgs, flake-compat }:
let
system = "x86_64-linux";
pkgs = import nixpkgs { inherit system; config.allowUnfree = true;};
in {
...
};
}
</syntaxhighlight>

<translate>
== NixOS configuration with flakes == 


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


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

== Development tricks == 

=== Automatically switch nix shells with direnv === 


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

=== Pushing Flakes to Cachix === 
</translate>

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

<translate>
=== Flake support in projects without flakes === 


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


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

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

=== Efficiently build multiple flake outputs === 


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

=== Build a package added in a PR === 
</translate>

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

<translate>

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:
</translate>

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

<translate>

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>):
</translate>

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

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

<syntaxHighlight lang=bash>
cd ~/libdep-src-checkout/
nix develop # Or `nix-shell` if applicable.
export prefix="./install" # configure nix to install it here
buildPhase # build it like nix does
installPhase # install it like nix does
</syntaxHighlight>

<translate>

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

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

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

== See also == 

=== Official sources === 


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


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


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


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

=== Guides === 


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

=== Useful flake modules === 


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


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


* [[Flake Compat|flake-compat]]: A compatibility layer for flakes


* [https://github.com/nix-community/todomvc-nix building Rust and Haskell flakes]
</translate>

{{references}}

<translate>

[[Category:Software|Software]]
[[Category:Nix|Nix]]
[[Category:Nix Language|Nix Language]]
[[Category:Flakes|Flakes]]
</translate>

NixOS as a desktop

2026-01-05T18:44:11Z

Pigs: fix broken link

<languages/>
<translate>

[[NixOS]] is a versatile operating system suitable for a wide range of use cases. This page is intended for users who wish to run NixOS as their primary desktop environment, either on physical hardware or within a virtual machine. Additionally, users planning to deploy NixOS in [[NixOS friendly hosters|cloud]] environments or on specialized server infrastructure may find it helpful to begin with the concepts and practices introduced here, as they provide a useful foundation for working within the broader [[Nix ecosystem]].

== Installation == 


Refer to [[NixOS Installation Guide]] to get started. Keep in mind that, for a desktop installation, you will probably want to make sure you start with at least 30 GiB of available disk space to allow for the [[:Category:Desktop environment|desktop environments]], [[:Category:Web Browser|web browsers]], and other [[:Category:Applications|graphical applications]], that would be typical of daily use. 15 GiB might be enough for a fairly bare-bones setup.

== Managing your configuration == 


As described in the [[Overview of the NixOS Linux distribution#Declarative Configuration]], NixOS is designed to be configured declaratively. This means the entire system configuration, including installed packages, system services, kernel parameters, and user accounts is defined in configuration files, typically in <code>/etc/nixos/configuration.nix</code>. These settings can then be applied consistently and reproducibly across machines.


The process for managing your configuration is documented in the {{NixOS Manual|name=NixOS official manual|anchor=#ch-configuration}}.

=== System Configuration === 


{{main|NixOS system configuration}}


The primary configuration file, <code>/etc/nixos/configuration.nix</code>, defines system-wide settings. This includes options like enabling services, managing system users, setting hardware options, and specifying installed packages. Changes are applied with:


<syntaxhighlight lang="console">
# nixos-rebuild switch
</syntaxhighlight>

=== User configuration with Home Manager === 


For managing per-user configurations such as application preferences, command-line tools, and dotfiles, [[Home Manager]] provides a convenient, declarative approach. It allows users to define which programs should be installed and how they should be configured, without needing to include those settings in the system-wide [https://nixos.org/manual/nixos/stable/#sec-changing-config configuration.nix].


Home Manager can be used independently of the system configuration and works with both traditional setups and newer [[Flakes]]-based configurations.

=== With Flakes === 


For users looking for a more streamlined and reproducible way to manage NixOS configurations, the [[Flakes]] feature has been gaining popularity within the community. While Flakes introduce some new concepts compared to traditional workflows, many users find them a convenient and organized approach to managing system and development configurations.


Refer to [[NixOS system configuration#Defining NixOS as a flake]] for details on getting started.

== Beyond initial setup == 


Once your basic NixOS installation is complete and functional, you can further customize your system with a variety of optional configurations tailored for desktop use. For a list of recommended initial system configurations, see [[NixOS Installation Guide#NixOS configuration]].


Common configuration areas include:

==== Desktop Environments ==== 


Install and configure full-featured environments such as [[GNOME]], [[KDE Plasma]], or [[Xfce]].


See [[:Category:Desktop environment]] for a full list.

==== Window Managers ==== 


Set up lightweight or tiling window managers like [[i3]], [[Sway]], [[Hyprland]], or [[XMonad]].


See [[:Category:Window managers]] for a full list.

==== Display Managers (Login Managers) ==== 


Configure graphical session managers such as [[Gnome|GDM]], [[KDE|SDDM]], or [[LightDM]].

==== Audio Setup ==== 


Enable and configure [[:Category:Audio|audio]] systems like [[PipeWire]], [[PulseAudio]], or [[ALSA]].

==== Network Management ==== 


Use tools such as [[NetworkManager]] or [[systemd-networkd]] for managing [[Networking|network]] connections.

==== Bluetooth Support ==== 


Set up [[Bluetooth]] with blueman or other management tools.

==== Power Management ==== 


Configure [[laptop]] [[Power Management|battery management]], suspend, and hibernation with tools like [[Laptop#tlp|tlp]] or [[systemd]] services.

==== Printing and Scanning ==== 


Enable [[Cups]] for printer support and tools like Sane for [[Scanners|scanning]] devices.

== Tips and tricks == 

=== Modularizing your configuration with modules === 


{{main|NixOS system configuration#Modularizing your configuration with modules}}

== See also == 


* [[Overview of the NixOS Linux distribution]]
* [[Comparison of NixOS setups]] for a table comparing some popular choices.
* [[Configuration Collection]] for a long list within the wiki.
* [https://github.com/topics/nix-flake nix-flake], [https://github.com/topics/nixos-configuration nixos-configuration], [https://github.com/topics/nixos-dotfiles nixos-dotfiles] Github topics
* [[Wil T Nix Guides]] Youtube video format guide


[[Category:Desktop]]
[[Category:Guide]]
[[Category:NixOS]]
</translate>

Sway

2026-01-05T18:31:44Z

Pigs: add crosslinking in opening header

[https://swaywm.org/ Sway] is a tiling [[Wayland]] compositor and a drop-in replacement for the [[i3]] window manager for X11. It can work with an existing i3 configuration and supports most of i3's features, plus a few extras. For users migrating from i3, see the [https://github.com/swaywm/sway/wiki/i3-Migration-Guide i3 migration guide].

== Setup ==
You can install Sway by enabling it in NixOS directly, or by using [[Home Manager]], or both.

=== Using NixOS ===
Here is a minimal configuration:

{{File|3={ config, pkgs, lib, ... }:
{
environment.systemPackages = with pkgs; [
grim # screenshot functionality
slurp # screenshot functionality
wl-clipboard # wl-copy and wl-paste for copy/paste from stdin / stdout
mako # notification system developed by swaywm maintainer
];

# Enable the gnome-keyring secrets vault.
# Will be exposed through DBus to programs willing to store secrets.
services.gnome.gnome-keyring.enable = true;

# enable Sway window manager
programs.sway = {
enable = true;
wrapperFeatures.gtk = true;
};
}|name=/etc/nixos/configuration.nix|lang=nix}}

By default, the Sway module in NixOS comes with a set of extra packages, including [https://codeberg.org/dnkl/foot/ Foot] terminal, [[Swayidle]], [[Swaylock]], and [https://codeberg.org/adnano/wmenu/ wmenu], which may be configured under the <code>[https://search.nixos.org/options?show=programs.sway.extraPackages programs.sway.extraPackages]</code> option. You may also want to include <code>wl-clipboard</code> for clipboard functionality, as well as a screenshot utility such as [https://github.com/emersion/slurp Slurp] or [[Flameshot]] for screenshot region selection.

Additionally, for a more customizable bar implementation than <code>sway-bar</code>, [[Waybar]] may be enabled with <code>programs.waybar.enable</code>.

The default Sway configuration is symlinked to <code>/etc/sway/config</code> and <code>/etc/sway/config.d/nixos.conf</code>. The latter file contains dbus and systemd configuration that is critical to using apps that depend on XDG desktop portals with Sway, and should be included in any custom configuration files.

A few general comments:
* There is some friction between GTK theming and Sway. Currently the Sway developers suggest using gsettings to set gtk theme attributes as described here [https://github.com/swaywm/sway/wiki/GTK-3-settings-on-Wayland]. There is currently a plan to allow GTK theme attributes to be set directly in the Sway config.
* Running Sway as a systemd user service is not recommended [https://github.com/swaywm/sway/wiki/Systemd-integration#running-sway-itself-as-a---user-service] [https://github.com/swaywm/sway/issues/5160]

=== Using Home Manager ===
To set up Sway using [[Home Manager]], you must first enable [[Polkit]] in your NixOS configuration.
{{file|/etc/nixos/configuration.nix|nix|<nowiki>
security.polkit.enable = true;
</nowiki>}}

Then you may enable Sway in your Home Manager configuration. Here is a minimal example:

{{File|3=wayland.windowManager.sway = {
enable = true;
wrapperFeatures.gtk = true; # Fixes common issues with GTK 3 apps
config = rec {
modifier = "Mod4";
# Use kitty as default terminal
terminal = "kitty";
startup = [
# Launch Firefox on start
{command = "firefox";}
];
};
};|name=/etc/nixos/home.nix|lang=nix}}

See [https://nix-community.github.io/home-manager/options.xhtml#opt-wayland.windowManager.sway.enable Home Manager's Options for Sway] for a complete list of configuration options.

You may need to activate dbus manually from .zshrc to use i.e: dunst, see [https://discourse.nixos.org/t/dunst-crashes-if-run-as-service/27671/2 Dunst crashes if run as service]

{{Note|
It's recommended to enable a [[Secret Service]] provider, like GNOME Keyring:
{{file|home.nix|nix|<nowiki>
services.gnome-keyring.enable = true;
</nowiki>}}
}}

=== Systemd services ===
Kanshi is an output configuration daemon. As explained above, we don't run Sway itself as a systemd service. There are auxiliary daemons that we do want to run as systemd services, for example Kanshi [https://gitlab.freedesktop.org/emersion/kanshi], which implements monitor hot swapping. It would be enabled as follows:
{{file|/etc/nixos/configuration.nix|nix|<nowiki>
# kanshi systemd service
systemd.user.services.kanshi = {
description = "kanshi daemon";
environment = {
WAYLAND_DISPLAY="wayland-1";
DISPLAY = ":0";
};
serviceConfig = {
Type = "simple";
ExecStart = ''${pkgs.kanshi}/bin/kanshi -c kanshi_config_file'';
};
};
</nowiki>}}

{{file|sway config|bash|
# give Sway a little time to startup before starting kanshi.
exec sleep 5; systemctl --user start kanshi.service
}}
When you launch Sway, the systemd service is started.

=== Using a greeter ===
Installing a greeter based on [[greetd]] is the most straightforward way to launch Sway.

==== TUIGreet ====
Tuigreet is a simple and lightweight option that does not require a separate compositor to launch.

{{file|||<nowiki>
services.greetd = {
enable = true;
settings = {
default_session = {
command = "${pkgs.tuigreet}/bin/tuigreet --time --cmd sway";
user = "greeter";
};
};
};
</nowiki>|name=/etc/nixos/configuration.nix|lang=nix}}

==== Regreet ====
[https://github.com/rharish101/ReGreet Regreet] is a clean and customizable GTK-based greeter written in Rust. It will automatically find Sway and remembers the last picked option. Additional configuration options may be found under [https://search.nixos.org/options?&query=regreet programs.regreet].
{{File|3=programs.regreet.enable = true;|name=/etc/nixos/configuration.nix|lang=nix}}

=== Automatic startup on boot ===
The snippet below will start Sway immediately on startup, without a greeter and '''without a login prompt'''. Only consider using this in conjunction with [[Full Disk Encryption]].

<syntaxhighlight lang="nix">
services.getty = {
autologinUser = "your_username";
autologinOnce = true;
};
environment.loginShellInit = ''
[[ "$(tty)" == /dev/tty1 ]] && sway
'';
</syntaxhighlight>When launched directly from the TTY, Sway will not inherit the user environment. This may cause issues with systemd user services such as application launchers or [[Swayidle]]. To fix this, add the following to your Home Manager configuration:{{file|home.nix|nix|<nowiki>
wayland.windowManager.sway.systemd.variables = ["--all"];
</nowiki>}}

== Configuration ==
Sway may be configured for specific users using Home Manager or manually through configuration files. The default location is <code>/etc/sway/config</code>, and custom user configuration in <code>~/.config/sway/config</code>.

=== Keyboard layout ===
Changing layout for all keyboards to German (de):<syntaxhighlight lang="console">
input * xkb_layout "de"
</syntaxhighlight>The same thing accomplished in Home Manager:<syntaxhighlight lang="nix">
wayland.windowManager.sway.input."*".xkb_layout = "de";
</syntaxhighlight>

=== High-DPI scaling ===
Changing scale for all screens to factor 1.5:<syntaxhighlight lang="console">
output * scale 1.5
</syntaxhighlight>

=== Brightness and volume ===
You may set the brightness and volume function keys by binding the key codes to their corresponding commands within your sway config. The following configurations accomplish this using <code>light</code> and <code>pulseaudio</code>:
{{file|/etc/nixos/configuration.nix|nix|<nowiki>
users.users.yourusername.extraGroups = [ "video" ];
programs.light.enable = true;
environment.systemPackages = [ pkgs.pulseaudio ];
</nowiki>}}

{{file|||

# Brightness
bindsym XF86MonBrightnessDown exec light -U 10
bindsym XF86MonBrightnessUp exec light -A 10

# Volume
bindsym XF86AudioRaiseVolume exec 'pactl set-sink-volume @DEFAULT_SINK@ +1%'
bindsym XF86AudioLowerVolume exec 'pactl set-sink-volume @DEFAULT_SINK@ -1%'
bindsym XF86AudioMute exec 'pactl set-sink-mute @DEFAULT_SINK@ toggle'
|name=Sway Config|lang=bash}}Or alternatively in Home Manager:
{{File|3=wayland.windowManager.sway = {
enable = true;
config = {
keybindings = {
# Brightness Controls
"XF86MonBrightnessDown" = "exec light -U 10";
"XF86MonBrightnessUp" = "exec light -A 10";

# Volume Controls
"XF86AudioRaiseVolume" = "exec pactl set-sink-volume @DEFAULT_SINK@ +1%";
"XF86AudioLowerVolume" = "exec pactl set-sink-volume @DEFAULT_SINK@ -1%";
"XF86AudioMute" = "exec pactl set-sink-mute @DEFAULT_SINK@ toggle";
};
};
};|name=/etc/nixos/home.nix|lang=nix}}For an on screen display for audio and brightness, check [[swayosd]].

=== Touchpad ===
See the [https://www.mankier.com/5/sway-input sway-input man page] for options.
{{File|3=wayland.windowManager.sway =
{
enable = true;
config.input = {
"type:touchpad" = {
# Enables or disables tap for specified input device.
tap = "enabled";
# Enables or disables natural (inverted) scrolling for the specified input device.
natural_scroll = "enabled";
# Enables or disables disable-while-typing for the specified input device.
dwt = "enabled";
};
};
};|name=/etc/nixos/home.nix|lang=nix}}

== Troubleshooting ==

=== Cursor is missing icons or too tiny on HiDPI displays ===

==== With programs.sway ====
<syntaxhighlight lang="nix>
{
programs.sway.extraPackages = with pkgs; [
adwaita-icon-theme # mouse cursor and icons
gnome-themes-extra # dark adwaita theme
...
];
}
</syntaxhighlight>

In ~/.config/sway/config
<syntaxhighlight>seat "*" xcursor_theme Adwaita 32</syntaxhighlight>

==== With Home Manager ====

Using [[Home Manager]] you may configure the mouse cursor size and theme. The reason that your cursor might be missing in some applications, is because <code>XCURSOR_THEME</code> is missing, which will cause applications relying on <code>XWAYLAND</code> to misbehave. Setting <code>sway.enable = true</code>, combined with the <code>name</code>, <code>package</code> and size will set the correct environment variables, which sway will then use.

{{File|3=home.pointerCursor = {
name = "Adwaita";
package = pkgs.adwaita-icon-theme;
size = 24;
x11 = {
enable = true;
defaultCursor = "Adwaita";
};

sway.enable = true;

};|name=/etc/nixos/home.nix|lang=nix}}

=== Missing fonts in Xorg applications ===

If fonts for certain languages are missing in Xorg applications (e.g. Japanese fonts don't appear in Discord) even though they're in the system, you can set them as default fonts in your configuration file.

<syntaxhighlight lang="nix>

fonts = {
packages = with pkgs; [
noto-fonts
noto-fonts-cjk
noto-fonts-emoji
font-awesome
source-han-sans
source-han-sans-japanese
source-han-serif-japanese
];
fontconfig.defaultFonts = {
serif = [ "Noto Serif" "Source Han Serif" ];
sansSerif = [ "Noto Sans" "Source Han Sans" ];
};
};

</syntaxhighlight>

=== Swaylock cannot be unlocked with the correct password ===

Add the following to your NixOS configuration.

<syntaxhighlight lang="nix>
security.pam.services.swaylock = {};
</syntaxhighlight>

The <code>programs.sway.enable</code> option does this automatically.

=== Inferior performance compared to other distributions ===

Enabling realtime may improve latency and reduce stuttering, specially in high load scenarios.

<syntaxhighlight lang="nix">
security.pam.loginLimits = [
{ domain = "@users"; item = "rtprio"; type = "-"; value = 1; }
];
</syntaxhighlight>

Enabling this option allows any program run by the "users" group to request real-time priority.

=== WLR Error when trying to launch Sway ===

When this happens on a new NixOS system, enabling OpenGL in configuration.nix may fix this issue.

{{Note|<code>hardware.opengl</code> was renamed to <code>hardware.graphics</code> in NixOS 24.11.}}

<syntaxhighlight lang="nix">
hardware.graphics.enable = true;
</syntaxhighlight>

=== Systemd user services missing environment variables (PATH, etc) ===
When sway is launched with out display manager systemd won't inherit the users environment variables. To fix this add the following to your home-manager configuration:
{{File|3=wayland.windowManager.sway.systemd.variables = ["--all"];|name=home.nix|lang=nix}}

=== Touchscreen input bound to the wrong monitor in multi-monitor setups ===

See this [https://github.com/swaywm/sway/issues/6590#issue-1021207180 GitHub issue for Sway] and the solution give in [https://github.com/swaywm/sway/issues/6590#issuecomment-938724355 this response].

Using [[Home Manager]] add the following to your Sway configuration:
<syntaxhighlight lang="nix">
wayland.windowManager.sway = {
[...]
config = {
[...]
input = {
[...]
"type:touch" = {
# Replace touchscreen_output_identifier with the identifier of your touchscreen.
map_to_output = touchscreen_output_identifier;
};
};
};
};
</syntaxhighlight>

=== GTK apps take an exceptionally long time to start ===
This occurs because GTK apps make blocking calls to freedesktop portals to be displayed. If Sway is not integrated with dbus and systemd, it will not be able to communicate via the <code>org.freedesktop.portal.Desktop</code> portal. To fix this, see the [[Sway#Using NixOS|description]] of default Sway configurations earlier. Adding the following to your sway configuration, if it is not already present, may resolve the issue:
include /etc/sway/config.d/*

===dbus-issues: no icons in tray, can't open files from Nautilus with the right program===

If you're using Gnome-Apps like Nautilus on NixOS with Sway, you might run into issue with settings standard applications to open files from Nautilus (e.g. there being no way of linking PDF to your preferred PDF-reader). You might also experience tray icons not showing up in your bar.

This is fixed by running <code>dbus-update-activation-environment --all</code> after starting your session. Make it permanent by adding <code>exec dbus-update-activation-environment --all</code> to your sway config file.

== Tips and tricks ==

=== Toggle monitor modes script ===
Following script toggles screen / monitor modes if executed. It can also be mapped to a specific key in Sway.

First add the Flake input required for the script<syntaxhighlight lang="nix">
{
inputs = {
[...]
wl-togglescreens.url = "git+https://git.project-insanity.org/onny/wl-togglescreens.git?ref=main";
};

outputs = {self, nixpkgs, ...}@inputs: {
nixosConfigurations.myhost = inputs.nixpkgs.lib.nixosSystem {
system = "x86_64-linux";
specialArgs.inputs = inputs;
[...]
</syntaxhighlight>Map the script binary to a specific key<syntaxhighlight lang="nix">
{ config, pkgs, lib, inputs, ... }:{
home-manager.users.onny = {
programs = {
[...]
wayland.windowManager.sway = {
enable = true;
config = {
[...]
keybindings = lib.mkOptionDefault{
[...]
"XF86Display" = "exec ${inputs.wl-togglescreens.packages.x86_64-linux.wl-togglescreens}/bin/wl-togglescreens";
};
};
};
};
</syntaxhighlight>

=== Screen sharing ===
{{File|3={ pkgs, ... }:
{
# xdg portal + pipewire = screensharing
xdg.portal = {
enable = true;
wlr.enable = true;
};
services.pipewire = {
enable = true;
alsa.enable = true;
pulse.enable = true;
};
}|name=/etc/nixos/configuration.nix|lang=nix}}{{Tip|Make sure that you do not have conflicting definitions for xdg.portal in Home Manager.}}

=== Auto mounting USB storage devices (e.g. Flash Drives) ===
You can use [https://github.com/coldfix/udiskie udiskie] to automatically mount external storage medias.

You will need to install and enable [https://www.freedesktop.org/wiki/Software/udisks/ udisks2].
{{File|3=services.udisks2.enable = true;|name=/etc/nixos/configuration.nix|lang=nix}}
Then, in Home Manager you can enable udiskie.
{{File|3=services.udiskie.enable = true;|name=/etc/nixos/home.nix|lang=nix}}
Udiskie will automatically mount attached USB storage media.

See related info on [[USB storage devices]].

=== Screen dimming with wl-gammarelay-rs ===
Add <code>wl-gammarelay-rs</code> to programs.sway.extraPackages, then add the following to sway config:
<syntaxhighlight>
# start daemon
exec wl-gammarelay-rs

# bind shortcut to reset brightness
bindsym $mod+Control+0 exec busctl --user set-property rs.wl-gammarelay / rs.wl.gammarelay Brightness d 1

# bind shortcut to dim screen for a particular output
bindsym $mod+Control+Underscore exec busctl --user set-property rs.wl-gammarelay /outputs/DP_1 rs.wl.gammarelay Brightness d 0.5

</syntaxhighlight>

=== Inhibit swayidle/suspend when fullscreen ===
Add to sway config:
<syntaxhighlight>
# When you use `for_window` the command you give is not executed
# immediately. It is stored in a list and the command is executed
# every time a window opens or changes (eg. title) in a way that
# matches the criteria.

# inhibit idle for fullscreen apps
for_window [app_id="^.*"] inhibit_idle fullscreen
</syntaxhighlight>
[[Category:Window managers]]
[[Category:Applications]]

NTFS

2026-01-02T04:03:57Z

Pigs: /* Troubleshooting */ adds section on dirty flag

New Technology File System (NTFS) is a proprietary journaling [[Filesystems|file system]] developed by Microsoft. It is still in use by modern Windows systems, although NTFS has not evolved since the release of version 3.1 in 2001.

== Mount NTFS filesystem on boot ==

Using [[nixos-generate-config]] to automatically generate Nix config is the recommended way to setup filesystems.

1. Run {{ic|lsblk}} to list device names.
{{code|
sd...
└─sdX
}}
2. Mount the device using [https://man7.org/linux/man-pages/man8/mount.8.html {{ic|mount}}], where {{ic|/dev/sdX}} replaced with your device name and {{ic|/mnt/sdX}} replaced with an existing folder path to mount your drive.
{{code|<nowiki>mount /dev/sdX /mnt/sdX -t ntfs3 -o uid=$UID</nowiki>}}
3. Run {{ic|nixos-generate-config --dir .}} to generate hardware configuration. This will automatically add all currently mounted devices to {{ic|hardware-configuration.nix}}.
{{file|/etc/nixos/hardware-configuration.nix|diff|3=
+ boot.supportedFilesystems = [ "ntfs" ];
+ fileSystems."/mnt/sdX" = {
+ device = "/dev/disk/by-uuid/F258FB9E58FB5FB1";
+ fsType = "ntfs3";
+ };
}}
4. Add {{ic|<nowiki>"uid=$UID"</nowiki>}} to {{nixos:option|fileSystems.*.options|fileSystems.<name>.options}} to get write access, where {{ic|<nowiki>$UID</nowiki>}} replaced with your UID:
{{file|/etc/nixos/configuration.nix|nix|3=
fileSystems =
let
ntfs-drives = [
"/mnt/sdX"
];
in
lib.genAttrs ntfs-drives (path: {
options = [
"uid=$UID" # REPLACE "$UID" WITH YOUR ACTUAL UID!
# "nofail"
];
});
}}

{{note|You may find your UID by running {{ic|echo $UID}}.}}
{{aside|It is not recommended to manually edit {{ic|hardware-configuration.nix}}.}}
5. {{evaluate}}

== Troubleshooting ==

=== Read-only file system ===

This is most likely caused by Windows not marking the disk as "clean" and unmounted.

To verify:

<pre>
journalctl -b0 | grep -i "The disk contains an unclean file system"
</pre>

It should return a similar message to what follows:

<pre>
The disk contains an unclean file system (0,0). Metadata
kept in Windows cache, refused to mount. Falling back to
read-only mount because the NTFS partition is in an unsafe
state. Please resume and shutdown Windows fully (no
hibernation or fast restarting.)
</pre>

If you have shutdown Windows fully, and not used hibernation, it may be caused by the fast startup or fast boot feature of Windows. It has been reported that major Windows updates may reset this setting to on.

[https://social.technet.microsoft.com/wiki/contents/articles/25908.fast-startup-how-to-disable-if-it-s-causing-problems.aspx This TechNet entry] explains how to disable fast startup. Additionally, [https://www.howtogeek.com/243901/the-pros-and-cons-of-windows-10s-fast-startup-mode/ this blog post on howtogeek.com] explains how the fast startup mode works, and how to disable it.

=== Unable to mount ntfs3 with dirty volume ===

When attempting to mount an <code>NTFS</code> partition using the <code>ntfs3</code> filesystem driver via the {{nixos:package|ntfs3g}} package, the mount operation may fail:

<syntaxhighlight lang="console">
# mount /dev/sda1 /mnt -t ntfs3
mount: /mnt: wrong fs type, bad option, bad superblock on /dev/sda1, missing codepage or helper program, or other error.
dmesg(1) may have more information after failed mount system call.
</syntaxhighlight>

With the resulting dmesg output:

<syntaxhighlight lang="console">
# dmesg
...
[168659.819978] ntfs3: sda1: It is recommened to use chkdsk.
[168659.820833] ntfs3: sda1: volume is dirty and "force" flag is not set!
</syntaxhighlight>

This indicates that the NTFS volume has the “dirty” flag set. In this state, the <code>ntfs3</code> driver refuses to mount the filesystem.

To clear the dirty flag, run <code>ntfsfix</code> on the affected partition:

<syntaxhighlight lang="console">
# ntfsfix --clear-dirty /dev/sda1
</syntaxhighlight>

If <code>ntfsfix</code> fails with an error <code>Windows is hibernated, refused to mount</code>, the partition can be mounted using <code>ntfs-3g</code> with the hibernation file removed:

<syntaxhighlight lang="console">
# ntfs-3g -o remove_hiberfile /dev/sda1 /mnt
</syntaxhighlight>

[[Category:Filesystem]]

AMD GPU

2025-12-31T06:46:05Z

Pigs: combine problems section with troubleshooting

[https://en.wikipedia.org/wiki/AMDgpu_(Linux_kernel_module) AMDGPU] is an open source graphics driver for AMD Radeon graphics cards. It supports AMD GPUs based on the [https://en.wikipedia.org/wiki/Graphics_Core_Next GCN architecture Graphics Core Next (GCN)] architecture and later, covering hardware released from approximately 2012 onward. This guide is about configuration of NixOS to correctly use AMD GPUs supported by the AMDGPU driver.

== Basic Setup ==
For ordinary desktop / gaming usage, AMD GPUs are expected to work out of the box. As with any desktop configuration though, graphics acceleration does need to be enabled.
<syntaxhighlight lang="nix">hardware.graphics = {
enable = true;
enable32Bit = true;
};</syntaxhighlight>There is also the [https://search.nixos.org/options?channel=unstable&query=hardware.amdgpu amdgpu nixos module available for common configuration options], such as enabling opencl, legacy support, overdrive/overclocking and loading during initrd.

== Special Configuration ==
The following configurations are only required if you have a specific reason for needing them. They are not expected to be necessary for a typical desktop / gaming setup.

=== Enable Southern Islands (SI) and Sea Islands (CIK) support (eg. HD 7000/8000) ===
The oldest architectures that AMDGPU supports are [[wikipedia:Radeon_HD_7000_series|Southern Islands (SI, i.e. GCN 1)]] and [[wikipedia:Radeon_HD_8000_series|Sea Islands (CIK, i.e. GCN 2)]], but support for them is disabled by default. To use AMDGPU instead of the <code>radeon</code> driver, you can set the legacySupport option in the amdgpu module.<syntaxhighlight lang="nix">
hardware.amdgpu.legacySupport.enable = true;
</syntaxhighlight>This will set the kernel parameters as follows (this is redundant if you set the above option)

<syntaxhighlight lang="nix">
boot.kernelParams = [
# For Southern Islands (SI i.e. GCN 1) cards
"amdgpu.si_support=1"
"radeon.si_support=0"
# For Sea Islands (CIK i.e. GCN 2) cards
"amdgpu.cik_support=1"
"radeon.cik_support=0"
];
</syntaxhighlight>

Doing this is required to use [[#Vulkan|Vulkan]] on these cards, as the <code>radeon</code> driver doesn't support it.

Please note this also removes support for analog video outputs, which is only available with the <code>radeon</code> driver.

=== HIP ===
Most software has the HIP libraries hard-coded. You can work around it on NixOS by using:

<syntaxhighlight lang="nix">
systemd.tmpfiles.rules =
let
rocmEnv = pkgs.symlinkJoin {
name = "rocm-combined";
paths = with pkgs.rocmPackages; [
rocblas
hipblas
clr
];
};
in [
"L+ /opt/rocm - - - - ${rocmEnv}"
];

</syntaxhighlight>

==== Blender ====
Hardware accelerated rendering can be achieved by using the package <syntaxhighlight lang="nix" inline="">blender-hip</syntaxhighlight>.

Currently, you need to [[Linux kernel|use the latest kernel]] for <syntaxhighlight lang="nix" inline="">blender-hip</syntaxhighlight> to work.

=== OpenCL ===
OpenCL support using the ROCM runtime library can be enabled via the amdgpu module.<syntaxhighlight lang="nix">
hardware.amdgpu.opencl.enable = true;
</syntaxhighlight>

You should also install the <code>clinfo</code> package to verify that OpenCL is correctly setup (or check in the program you use to see if it is now available, such as in Darktable).

==== Radeon 500 series (aka Polaris) ====
As of [https://github.com/ROCm/ROCm/issues/1659 ROCm 4.5], AMD has disabled OpenCL on Polaris-based cards. This can be re-enabled by setting the environment variable <code>ROC_ENABLE_PRE_VEGA=1</code>

<syntaxhighlight lang="nix">
environment.variables = {
ROC_ENABLE_PRE_VEGA = "1";
};
</syntaxhighlight>

==== Older GPUs (TeraScale) ====



For graphics cards older than GCN 1 — or for any GCN using the "radeon" driver — enable OpenCL by adding Clover ''instead of'' the ROCm ICD:

<syntaxhighlight lang="nix">
hardware.opengl.extraPackages = with pkgs; [
# OpenCL support for the older Radeon R300, R400, R500,
# R600, R700, Evergreen, Northern Islands,
# Southern Islands (radeon), and Sea Islands (radeon)
# GPU families
mesa.opencl
# NOTE: at some point GPUs in the R600 family and newer
# may need to replace this with the "rusticl" ICD;
# and GPUs in the R500-family and older may need to
# pin the package version or backport Clover
# - https://www.phoronix.com/news/Mesa-Delete-Clover-Discussion
# - https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/19385
];
</syntaxhighlight>

Merely installing <code>mesa.opencl</code> with <code>nix-shell -p</code> will not work; it needs to be present at build-time for the OpenCL ICD loader, which only searches static paths.

=== Vulkan ===
Vulkan is already enabled by default (using Mesa RADV) on 64 bit applications. The settings to control it are now the same as those shown in the basic setup:

<syntaxhighlight lang="nix">hardware.graphics.enable = true;
hardware.graphics.enable32Bit = true; # Replaced 'driSupport32Bit'
</syntaxhighlight>

==== AMDVLK ====

{{Warning|1=AMDVLK is being discontinued, so the only reason you may want to use it is if you have issues with RADV. See: https://github.com/GPUOpen-Drivers/AMDVLK/discussions/416.}}

The AMDVLK drivers can be used in addition to the Mesa RADV drivers. The program will choose which one to use (mostly defaulting to AMDVLK):

<syntaxhighlight lang="nix">
#24.11
hardware.graphics.extraPackages = with pkgs; [
amdvlk
];
# For 32 bit applications
hardware.graphics.extraPackages32 = with pkgs; [
driversi686Linux.amdvlk
];

#24.05 and below
hardware.opengl.extraPackages = with pkgs; [
amdvlk
];
# For 32 bit applications
hardware.opengl.extraPackages32 = with pkgs; [
driversi686Linux.amdvlk
];
</syntaxhighlight>

More information can be found here: https://nixos.org/manual/nixos/unstable/index.html#sec-gpu-accel-vulkan

One way to avoid installing it system-wide, is creating a wrapper like this:

<syntaxhighlight lang="nix">
with pkgs; writeShellScriptBin "amdvlk-run" ''
export VK_DRIVER_FILES="${amdvlk}/share/vulkan/icd.d/amd_icd64.json:${pkgsi686Linux.amdvlk}/share/vulkan/icd.d/amd_icd32.json"
exec "$@"
'';
</syntaxhighlight>

This wrapper can be used per-game inside Steam (<syntaxhighlight lang="sh" inline>amdvlk-run %command%</syntaxhighlight>) and lets RADV to be the system's default.

===== Performance Issues with AMDVLK =====
Some games choose AMDVLK over RADV, which can cause noticeable performance issues (e.g. <50% less FPS in games)

To force RADV<syntaxhighlight lang="nix">
environment.variables.AMD_VULKAN_ICD = "RADV";
</syntaxhighlight>

=== GUI tools ===

==== LACT - Linux AMDGPU Controller ====

This application allows you to overclock, undervolt, set fans curves of AMD GPUs on a Linux system.

In order to install the daemon service you need to add the package to <code>systemd.packages</code>. Also the <code>wantedBy</code> field should be set to <code>multi-user.target</code> to start the service during boot.

<syntaxhighlight lang="nix">
environment.systemPackages = with pkgs; [ lact ];
systemd.packages = with pkgs; [ lact ];
systemd.services.lactd.wantedBy = ["multi-user.target"];
</syntaxhighlight>Simple version is:<syntaxhighlight lang="nix">
services.lact.enable = true;
# https://github.com/NixOS/nixpkgs/blob/nixos-unstable/nixos/modules/services/hardware/lact.nix
</syntaxhighlight>

== Troubleshooting ==

=== Low resolution during initramfs phase ===
If you encounter a low resolution output during early boot phases, you can load the amdgpu module in the initial ramdisk<syntaxhighlight lang="nix">
hardware.amdgpu.initrd.enable = true; # sets boot.initrd.kernelModules = ["amdgpu"];
</syntaxhighlight>

=== Dual Monitors ===

If you encounter problems having multiple monitors connected to your GPU, adding `video` parameters for each connector to the kernel command line sometimes helps.

For example:

<syntaxhighlight lang="nix">
boot.kernelParams = [
"video=DP-1:2560x1440@144"
"video=DP-2:2560x1440@144"
];
</syntaxhighlight>

With the connector names (like `DP-1`), the resolution and frame rate adjusted accordingly.

To figure out the connector names, execute the following command while your monitors are connected:

<syntaxhighlight lang="bash">
head /sys/class/drm/*/status
</syntaxhighlight>

=== System Hang with Vega Graphics (and select GPUs) ===

Currently on the latest kernel/mesa (currently 6.13 and 24.3.4 respectively), Vega integrated graphics (and other GPUs like the RX 6600<ref>https://bbs.archlinux.org/viewtopic.php?pid=2224147#p2224147</ref>) will have a possibility to hang due to context-switching between Graphics and Compute.<ref>https://bbs.archlinux.org/viewtopic.php?id=301798</ref> There are currently two sets of patches to choose between stability or speed that can be applied: [https://github.com/SeryogaBrigada/linux/commits/v6.13-amdgpu amdgpu-stable] and [https://github.com/SeryogaBrigada/linux/commits/v6.13-amdgpu-testing amdgpu-testing].

See [[Linux Kernel#Patching a single In-tree kernel module]], keep in mind how to make [https://stackoverflow.com/a/23525893 patch diffs from commits from GitHub], and consider this example configuration:<syntaxhighlight lang="nix">
{ config, pkgs, ... }:
let
amdgpu-kernel-module = pkgs.callPackage ./packages/amdgpu-kernel-module.nix {
# Make sure the module targets the same kernel as your system is using.
kernel = config.boot.kernelPackages.kernel;
};
# linuxPackages_latest 6.13 (or linuxPackages_zen 6.13)
amdgpu-stability-patch = pkgs.fetchpatch {
name = "amdgpu-stability-patch";
url = "https://github.com/torvalds/linux/compare/ffd294d346d185b70e28b1a28abe367bbfe53c04...SeryogaBrigada:linux:4c55a12d64d769f925ef049dd6a92166f7841453.diff";
hash = "sha256-q/gWUPmKHFBHp7V15BW4ixfUn1kaeJhgDs0okeOGG9c=";
};
/*
# linuxPackages_zen 6.12
amdgpu-stability-patch = pkgs.fetchpatch {
name = "amdgpu-stability-patch-zen";
url = "https://github.com/zen-kernel/zen-kernel/compare/fd00d197bb0a82b25e28d26d4937f917969012aa...WhiteHusky:zen-kernel:f4c32ca166ad55d7e2bbf9adf121113500f3b42b.diff";
hash = "sha256-bMT5OqBCyILwspWJyZk0j0c8gbxtcsEI53cQMbhbkL8=";
};
*/
in
{
# amdgpu instability with context switching between compute and graphics
# https://bbs.archlinux.org/viewtopic.php?id=301798
# side-effects: plymouth fails to show at boot, but does not interfere with booting
boot.extraModulePackages = [
(amdgpu-kernel-module.overrideAttrs (_: {
patches = [
amdgpu-stability-patch
];
}))
];
}
</syntaxhighlight>

=== Sporadic Crashes ===

If getting error messages in <code>dmesg</code> with <code>page fault</code> or <code>GCVM_L2_PROTECTION_FAULT_STATUS</code> it might be from AMD GPU boosting too high without enough voltage

Use a tool like LACT to increase power usage limit to 15%, undervolt by moderate amount (e.g. -50mV for 7900 XTX) and optionally decrease maximum GPU clock.

* https://wiki.gentoo.org/wiki/AMDGPU#Frequent_and_Sporadic_Crashes
* https://gitlab.freedesktop.org/mesa/mesa/-/issues/11532
* https://gitlab.freedesktop.org/drm/amd/-/issues/3067

=== Error: <code>amdgpu: Failed to get gpu_info firmware</code> ===

Solution:
hardware.firmware = [ pkgs.linux-firmware ];

== See Also ==

* https://wiki.archlinux.org/title/AMDGPU
* https://wiki.gentoo.org/wiki/AMDGPU

== References ==

[[Category:Video]]

AMD GPU

2025-12-31T06:34:03Z

Pigs: clean up opening statement

[https://en.wikipedia.org/wiki/AMDgpu_(Linux_kernel_module) AMDGPU] is an open source graphics driver for AMD Radeon graphics cards. It supports AMD GPUs based on the [https://en.wikipedia.org/wiki/Graphics_Core_Next GCN architecture Graphics Core Next (GCN)] architecture and later, covering hardware released from approximately 2012 onward. This guide is about configuration of NixOS to correctly use AMD GPUs supported by the AMDGPU driver.

== Basic Setup ==
For ordinary desktop / gaming usage, AMD GPUs are expected to work out of the box. As with any desktop configuration though, graphics acceleration does need to be enabled.
<syntaxhighlight lang="nix">hardware.graphics = {
enable = true;
enable32Bit = true;
};</syntaxhighlight>There is also the [https://search.nixos.org/options?channel=unstable&query=hardware.amdgpu amdgpu nixos module available for common configuration options], such as enabling opencl, legacy support, overdrive/overclocking and loading during initrd.

== Problems ==

=== Low resolution during initramfs phase ===
If you encounter a low resolution output during early boot phases, you can load the amdgpu module in the initial ramdisk<syntaxhighlight lang="nix">
hardware.amdgpu.initrd.enable = true; # sets boot.initrd.kernelModules = ["amdgpu"];
</syntaxhighlight>

=== Dual Monitors ===

If you encounter problems having multiple monitors connected to your GPU, adding `video` parameters for each connector to the kernel command line sometimes helps.

For example:

<syntaxhighlight lang="nix">
boot.kernelParams = [
"video=DP-1:2560x1440@144"
"video=DP-2:2560x1440@144"
];
</syntaxhighlight>

With the connector names (like `DP-1`), the resolution and frame rate adjusted accordingly.

To figure out the connector names, execute the following command while your monitors are connected:

<syntaxhighlight lang="bash">
head /sys/class/drm/*/status
</syntaxhighlight>

=== System Hang with Vega Graphics (and select GPUs) ===

Currently on the latest kernel/mesa (currently 6.13 and 24.3.4 respectively), Vega integrated graphics (and other GPUs like the RX 6600<ref>https://bbs.archlinux.org/viewtopic.php?pid=2224147#p2224147</ref>) will have a possibility to hang due to context-switching between Graphics and Compute.<ref>https://bbs.archlinux.org/viewtopic.php?id=301798</ref> There are currently two sets of patches to choose between stability or speed that can be applied: [https://github.com/SeryogaBrigada/linux/commits/v6.13-amdgpu amdgpu-stable] and [https://github.com/SeryogaBrigada/linux/commits/v6.13-amdgpu-testing amdgpu-testing].

See [[Linux Kernel#Patching a single In-tree kernel module]], keep in mind how to make [https://stackoverflow.com/a/23525893 patch diffs from commits from GitHub], and consider this example configuration:<syntaxhighlight lang="nix">
{ config, pkgs, ... }:
let
amdgpu-kernel-module = pkgs.callPackage ./packages/amdgpu-kernel-module.nix {
# Make sure the module targets the same kernel as your system is using.
kernel = config.boot.kernelPackages.kernel;
};
# linuxPackages_latest 6.13 (or linuxPackages_zen 6.13)
amdgpu-stability-patch = pkgs.fetchpatch {
name = "amdgpu-stability-patch";
url = "https://github.com/torvalds/linux/compare/ffd294d346d185b70e28b1a28abe367bbfe53c04...SeryogaBrigada:linux:4c55a12d64d769f925ef049dd6a92166f7841453.diff";
hash = "sha256-q/gWUPmKHFBHp7V15BW4ixfUn1kaeJhgDs0okeOGG9c=";
};
/*
# linuxPackages_zen 6.12
amdgpu-stability-patch = pkgs.fetchpatch {
name = "amdgpu-stability-patch-zen";
url = "https://github.com/zen-kernel/zen-kernel/compare/fd00d197bb0a82b25e28d26d4937f917969012aa...WhiteHusky:zen-kernel:f4c32ca166ad55d7e2bbf9adf121113500f3b42b.diff";
hash = "sha256-bMT5OqBCyILwspWJyZk0j0c8gbxtcsEI53cQMbhbkL8=";
};
*/
in
{
# amdgpu instability with context switching between compute and graphics
# https://bbs.archlinux.org/viewtopic.php?id=301798
# side-effects: plymouth fails to show at boot, but does not interfere with booting
boot.extraModulePackages = [
(amdgpu-kernel-module.overrideAttrs (_: {
patches = [
amdgpu-stability-patch
];
}))
];
}
</syntaxhighlight>

=== Sporadic Crashes ===

If getting error messages in <code>dmesg</code> with <code>page fault</code> or <code>GCVM_L2_PROTECTION_FAULT_STATUS</code> it might be from AMD GPU boosting too high without enough voltage

Use a tool like LACT to increase power usage limit to 15%, undervolt by moderate amount (e.g. -50mV for 7900 XTX) and optionally decrease maximum GPU clock.

* https://wiki.gentoo.org/wiki/AMDGPU#Frequent_and_Sporadic_Crashes
* https://gitlab.freedesktop.org/mesa/mesa/-/issues/11532
* https://gitlab.freedesktop.org/drm/amd/-/issues/3067

== Special Configuration ==
The following configurations are only required if you have a specific reason for needing them. They are not expected to be necessary for a typical desktop / gaming setup.

=== Enable Southern Islands (SI) and Sea Islands (CIK) support (eg. HD 7000/8000) ===
The oldest architectures that AMDGPU supports are [[wikipedia:Radeon_HD_7000_series|Southern Islands (SI, i.e. GCN 1)]] and [[wikipedia:Radeon_HD_8000_series|Sea Islands (CIK, i.e. GCN 2)]], but support for them is disabled by default. To use AMDGPU instead of the <code>radeon</code> driver, you can set the legacySupport option in the amdgpu module.<syntaxhighlight lang="nix">
hardware.amdgpu.legacySupport.enable = true;
</syntaxhighlight>This will set the kernel parameters as follows (this is redundant if you set the above option)

<syntaxhighlight lang="nix">
boot.kernelParams = [
# For Southern Islands (SI i.e. GCN 1) cards
"amdgpu.si_support=1"
"radeon.si_support=0"
# For Sea Islands (CIK i.e. GCN 2) cards
"amdgpu.cik_support=1"
"radeon.cik_support=0"
];
</syntaxhighlight>

Doing this is required to use [[#Vulkan|Vulkan]] on these cards, as the <code>radeon</code> driver doesn't support it.

Please note this also removes support for analog video outputs, which is only available with the <code>radeon</code> driver.

=== HIP ===
Most software has the HIP libraries hard-coded. You can work around it on NixOS by using:

<syntaxhighlight lang="nix">
systemd.tmpfiles.rules =
let
rocmEnv = pkgs.symlinkJoin {
name = "rocm-combined";
paths = with pkgs.rocmPackages; [
rocblas
hipblas
clr
];
};
in [
"L+ /opt/rocm - - - - ${rocmEnv}"
];

</syntaxhighlight>

==== Blender ====
Hardware accelerated rendering can be achieved by using the package <syntaxhighlight lang="nix" inline="">blender-hip</syntaxhighlight>.

Currently, you need to [[Linux kernel|use the latest kernel]] for <syntaxhighlight lang="nix" inline="">blender-hip</syntaxhighlight> to work.

=== OpenCL ===
OpenCL support using the ROCM runtime library can be enabled via the amdgpu module.<syntaxhighlight lang="nix">
hardware.amdgpu.opencl.enable = true;
</syntaxhighlight>

You should also install the <code>clinfo</code> package to verify that OpenCL is correctly setup (or check in the program you use to see if it is now available, such as in Darktable).

==== Radeon 500 series (aka Polaris) ====
As of [https://github.com/ROCm/ROCm/issues/1659 ROCm 4.5], AMD has disabled OpenCL on Polaris-based cards. This can be re-enabled by setting the environment variable <code>ROC_ENABLE_PRE_VEGA=1</code>

<syntaxhighlight lang="nix">
environment.variables = {
ROC_ENABLE_PRE_VEGA = "1";
};
</syntaxhighlight>

==== Older GPUs (TeraScale) ====



For graphics cards older than GCN 1 — or for any GCN using the "radeon" driver — enable OpenCL by adding Clover ''instead of'' the ROCm ICD:

<syntaxhighlight lang="nix">
hardware.opengl.extraPackages = with pkgs; [
# OpenCL support for the older Radeon R300, R400, R500,
# R600, R700, Evergreen, Northern Islands,
# Southern Islands (radeon), and Sea Islands (radeon)
# GPU families
mesa.opencl
# NOTE: at some point GPUs in the R600 family and newer
# may need to replace this with the "rusticl" ICD;
# and GPUs in the R500-family and older may need to
# pin the package version or backport Clover
# - https://www.phoronix.com/news/Mesa-Delete-Clover-Discussion
# - https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/19385
];
</syntaxhighlight>

Merely installing <code>mesa.opencl</code> with <code>nix-shell -p</code> will not work; it needs to be present at build-time for the OpenCL ICD loader, which only searches static paths.

=== Vulkan ===
Vulkan is already enabled by default (using Mesa RADV) on 64 bit applications. The settings to control it are now the same as those shown in the basic setup:

<syntaxhighlight lang="nix">hardware.graphics.enable = true;
hardware.graphics.enable32Bit = true; # Replaced 'driSupport32Bit'
</syntaxhighlight>

==== AMDVLK ====

{{Warning|1=AMDVLK is being discontinued, so the only reason you may want to use it is if you have issues with RADV. See: https://github.com/GPUOpen-Drivers/AMDVLK/discussions/416.}}

The AMDVLK drivers can be used in addition to the Mesa RADV drivers. The program will choose which one to use (mostly defaulting to AMDVLK):

<syntaxhighlight lang="nix">
#24.11
hardware.graphics.extraPackages = with pkgs; [
amdvlk
];
# For 32 bit applications
hardware.graphics.extraPackages32 = with pkgs; [
driversi686Linux.amdvlk
];

#24.05 and below
hardware.opengl.extraPackages = with pkgs; [
amdvlk
];
# For 32 bit applications
hardware.opengl.extraPackages32 = with pkgs; [
driversi686Linux.amdvlk
];
</syntaxhighlight>

More information can be found here: https://nixos.org/manual/nixos/unstable/index.html#sec-gpu-accel-vulkan

One way to avoid installing it system-wide, is creating a wrapper like this:

<syntaxhighlight lang="nix">
with pkgs; writeShellScriptBin "amdvlk-run" ''
export VK_DRIVER_FILES="${amdvlk}/share/vulkan/icd.d/amd_icd64.json:${pkgsi686Linux.amdvlk}/share/vulkan/icd.d/amd_icd32.json"
exec "$@"
'';
</syntaxhighlight>

This wrapper can be used per-game inside Steam (<syntaxhighlight lang="sh" inline>amdvlk-run %command%</syntaxhighlight>) and lets RADV to be the system's default.

===== Performance Issues with AMDVLK =====
Some games choose AMDVLK over RADV, which can cause noticeable performance issues (e.g. <50% less FPS in games)

To force RADV<syntaxhighlight lang="nix">
environment.variables.AMD_VULKAN_ICD = "RADV";
</syntaxhighlight>

=== GUI tools ===

==== LACT - Linux AMDGPU Controller ====

This application allows you to overclock, undervolt, set fans curves of AMD GPUs on a Linux system.

In order to install the daemon service you need to add the package to <code>systemd.packages</code>. Also the <code>wantedBy</code> field should be set to <code>multi-user.target</code> to start the service during boot.

<syntaxhighlight lang="nix">
environment.systemPackages = with pkgs; [ lact ];
systemd.packages = with pkgs; [ lact ];
systemd.services.lactd.wantedBy = ["multi-user.target"];
</syntaxhighlight>Simple version is:<syntaxhighlight lang="nix">
services.lact.enable = true;
# https://github.com/NixOS/nixpkgs/blob/nixos-unstable/nixos/modules/services/hardware/lact.nix
</syntaxhighlight>

== Troubleshooting ==

==== Error: <code>amdgpu: Failed to get gpu_info firmware</code> ====
Solution:
hardware.firmware = [ pkgs.linux-firmware ];

=== Links ===

* https://wiki.archlinux.org/title/AMDGPU
* https://wiki.gentoo.org/wiki/AMDGPU

=== References ===

[[Category:Video]]

Steam

2025-12-30T07:18:15Z

Pigs: formatting and hyperlinking

<languages/>
<translate>

[https://store.steampowered.com/ Steam] is a digital distribution platform for video games, offering a vast library for purchase, download, and management. On NixOS, Steam is generally easy to install and use, often working "out-of-the-box". It supports running many Windows games on Linux through its compatibility layer, [[#Proton|Proton]].<ref>https://store.steampowered.com/</ref>
</translate>

<translate>
== Installation == 
</translate>

<translate>
==== Shell ==== 
</translate>

<translate>

To temporarily use Steam-related tools like <code>steam-run</code> (for FHS environments) or <code>steamcmd</code> (for server management or tools like steam-tui setup) in a shell environment, you can run:
</translate>
<syntaxhighlight lang="console">
$ nix-shell -p steam-run # For FHS environment
$ nix-shell -p steamcmd # For steamcmd
</syntaxhighlight>
<translate>

This provides the tools in your current shell without adding them to your system configuration. For <code>steamcmd</code> to work correctly for some tasks (like initializing for steam-tui), you might need to run it once to generate necessary files, as shown in the [[#steam-tui| steam-tui section]].
</translate>

<translate>
==== System setup ==== 
</translate>

<translate>

To install the [[Steam]] package and enable all the system options necessary to allow it to run, add the following to your system configuration:

</translate>
{{file|/etc/nixos/configuration.nix|nix|
<nowiki>
programs.steam = {
enable = true;
};

# Optional: If you encounter amdgpu issues with newer kernels (e.g., 6.10+ reported issues),
# you might consider using the LTS kernel or a known stable version.
# boot.kernelPackages = pkgs.linuxPackages_lts; # Example for LTS
</nowiki>
}}

<translate>

[https://news.ycombinator.com/item?id=41549030 Anecdata on kernel 6.10 issues]
</translate>

{{note|Enabling [[steam]] installs several [[unfree software|unfree packages]]. If you are using <code>allowUnfreePredicate</code> you will need to ensure that your configurations permit all of them.
<syntaxhighlight lang="nix">
nixpkgs.config.allowUnfreePredicate = pkg: builtins.elem (lib.getName pkg) [
"steam"
"steam-unwrapped"
];
</syntaxhighlight>
}}

<translate>
== Configuration == 
</translate>

<translate>

Basic Steam features can be enabled directly within the {{nixos:option|programs.steam}} attribute set:
</translate>
{{file|/etc/nixos/configuration.nix|nix|
<nowiki>
programs.steam = {
enable = true; # Master switch, already covered in installation
remotePlay.openFirewall = true; # Open ports in the firewall for Steam Remote Play
dedicatedServer.openFirewall = true; # Open ports for Source Dedicated Server hosting
# Other general flags if available can be set here.
};
# Tip: For improved gaming performance, you can also enable GameMode:
# programs.gamemode.enable = true;
</nowiki>
}}
<translate>

{{note|If you are using a Steam Controller or a Valve Index, Steam hardware support is implicitly enabled by <code>programs.steam.enable {{=}} true;</code> which sets {{nixos:option|hardware.steam-hardware.enable}} to true.}}
</translate>
<translate>
== Tips and tricks == 
</translate>

<translate>
=== Gamescope Compositor / "Boot to Steam Deck" === 
</translate>
<translate>

Gamescope can function as a minimal desktop environment, meaning you can launch it from a TTY and have an experience very similar to the Steam Deck hardware console.
</translate>
<syntaxhighlight lang="nix">
# Clean Quiet Boot
boot.kernelParams = [ "quiet" "splash" "console=/dev/null" ];
boot.plymouth.enable = true;

programs.gamescope = {
enable = true;
capSysNice = true;
};
programs.steam.gamescopeSession.enable = true; # Integrates with programs.steam

# Gamescope Auto Boot from TTY (example)
services.xserver.enable = false; # Assuming no other Xserver needed
services.getty.autologinUser = "USERNAME_HERE";

services.greetd = {
enable = true;
settings = {
default_session = {
command = "${pkgs.gamescope}/bin/gamescope -W 1920 -H 1080 -f -e --xwayland-count 2 --hdr-enabled --hdr-itm-enabled -- steam -pipewire-dmabuf -gamepadui -steamdeck -steamos3 > /dev/null 2>&1";
user = "USERNAME_HERE";
};
};
};
</syntaxhighlight>

<translate>
=== Gamescope HDR ===
In order for HDR to work within gamescope, you need to separately install the <code>gamescope-wsi</code> package alongside enabling the <code>gamescope</code> program.<syntaxhighlight lang="nix">
programs.gamescope = {
enable = true;
capSysNice = false;
};
environment.systemPackages = with pkgs; [
gamescope-wsi # HDR won't work without this
];
</syntaxhighlight>Additionally, it may be necessary to force HDR in gamescope with the argument <code>--hdr-debug-force-output</code> when configuring your game's launch options in steam (see the example below).<syntaxhighlight lang="bash">
gamescope -W 3840 -H 2160 -r 120 -f --adaptive-sync --hdr-enabled --hdr-debug-force-output --mangoapp -- %command%
</syntaxhighlight>

=== steam-tui === 
</translate>
<translate>

If you want the steam-tui client, you'll have to install it. It relies on <code>steamcmd</code> being set up, so you'll need to run <code>steamcmd</code> once to generate the necessary configuration files.
First, ensure <code>steamcmd</code> is available (e.g., via <code>nix-shell -p steamcmd</code> or by adding it to <code>environment.systemPackages</code>), then run:
</translate>
<syntaxhighlight lang="bash">
steamcmd +quit # This initializes steamcmd's directory structure
</syntaxhighlight>
<translate>

Then install and run `steam-tui`. You may need to log in within `steamcmd` first if `steam-tui` has issues:
</translate>
<syntaxhighlight lang="bash">
# (Inside steamcmd prompt, if needed for full login before steam-tui)
# login <username> <password> <steam_2fa_code>
# quit
</syntaxhighlight>
<translate>

After setup, <code>steam-tui</code> (if installed e.g. via <code>home.packages</code> or <code>environment.systemPackages</code>) should start fine.
</translate>

<translate>
=== FHS environment only === 
</translate>
<translate>

To run proprietary games or software downloaded from the internet that expect a typical Linux Filesystem Hierarchy Standard (FHS), you can use <code>steam-run</code>. This provides an FHS-like environment without needing to patch the software.
Note that this is not necessary for clients installed from Nixpkgs (like Minigalaxy or Itch), which already use the FHS environment as needed.
There are two options to make <code>steam-run</code> available:
1. Install <code>steam-run</code> system-wide or user-specifically:
</translate>
<syntaxhighlight lang="nix">
# In /etc/nixos/configuration.nix
environment.systemPackages = with pkgs; [
steam-run
];
</syntaxhighlight>
<translate>

2. If you need more flexibility or want to use an overridden Steam package's FHS environment:
</translate>
<syntaxhighlight lang="nix">
# In /etc/nixos/configuration.nix
environment.systemPackages = with pkgs; [
(steam.override { /* Your overrides here */ }).run
];
</syntaxhighlight>
<translate>
=== Proton === 
</translate>
<translate>

You should be able to play most Windows games using Proton. If a game has a native Linux version that causes issues on NixOS, you can force the use of Proton by selecting a specific Proton version in the game's compatibility settings in Steam.
</translate>
<translate>

By default, Steam also looks for custom Proton versions in <code>~/.steam/root/compatibilitytools.d</code>. The environment variable <code>STEAM_EXTRA_COMPAT_TOOLS_PATHS</code> can be set to add other search paths.
</translate>
<translate>

Declarative install of custom Proton versions (e.g. GE-Proton):
</translate>
<syntaxhighlight lang="nix">
programs.steam.extraCompatPackages = with pkgs; [
proton-ge-bin
];
</syntaxhighlight>
<translate>

Manual management of multiple Proton versions can be done with ProtonUp-Qt:
</translate>
<syntaxhighlight lang="nix">
environment.systemPackages = with pkgs; [
protonup-qt
];
</syntaxhighlight>
<translate>
=== Overriding the Steam package === 
</translate>
<translate>

In some cases, you may need to override the default Steam package to provide missing dependencies or modify its build. Use the <code>programs.steam.package</code> option for this. Steam on NixOS runs many games in an FHS environment, but the Steam client itself or certain tools might need extra libraries.
</translate>
<translate>

Example: Adding Bumblebee and Primus (for NVIDIA Optimus):
</translate>
<syntaxhighlight lang="nix">
programs.steam.package = pkgs.steam.override {
extraPkgs = pkgs': with pkgs'; [ bumblebee primus ];
};

# For 32-bit applications with Steam, if using steamFull:
# programs.steam.package = pkgs.steamFull.override { extraPkgs = pkgs': with pkgs'; [ bumblebee primus ]; };
</syntaxhighlight>

<translate>

Example: Adding Xorg libraries for Gamescope (when used within Steam):
</translate>
<syntaxhighlight lang="nix">
programs.steam.package = pkgs.steam.override {
extraPkgs = pkgs': with pkgs'; [
xorg.libXcursor
xorg.libXi
xorg.libXinerama
xorg.libXScrnSaver
libpng
libpulseaudio
libvorbis
stdenv.cc.cc.lib # Provides libstdc++.so.6
libkrb5
keyutils
# Add other libraries as needed
];
};
</syntaxhighlight>

<translate>
=== Fix missing icons for games in GNOME dock and activities overview === 
</translate>
<translate>

GNOME uses the window class to determine the icon associated with a window. Steam currently doesn't set the required key for this in its .desktop files<ref>https://github.com/ValveSoftware/steam-for-linux/issues/12207</ref>, but you can fix this manually by editing the <code>StartupWMClass</code> key for each game's .desktop file, found under <code>~/.local/share/applications/</code>.


For games running through Proton, the value should be <code>steam_app_<game_id></code> (where <code><game_id></code> matches the value after steam://rungameid/ on the <code>Exec</code> line).


For games running natively, the value should match the game's main executable.


For example, the modified .desktop file for Valheim looks like this:
</translate>

<syntaxhighlight lang="desktop">
[Desktop Entry]
Name=Valheim
Comment=Play this game on Steam
Exec=steam steam://rungameid/892970
Icon=steam_icon_892970
Terminal=false
Type=Application
Categories=Game;
StartupWMClass=valheim.x86_64
</syntaxhighlight>
<translate>
== Troubleshooting == 
</translate>

<translate>

For all issues: first run <code>steam -dev -console</code> through the terminal and read the output.
</translate>

<translate>
=== Steam fails to start. What do I do? === 
</translate>
<translate>

Run <code>strace steam -dev -console 2> steam.logs</code> in the terminal. If <code>strace</code> is not installed, temporarily install it using <code>nix-shell -p strace</code> or <code>nix run nixpkgs#strace -- steam -dev -console 2> steam.logs</code> (if using Flakes). After that, create a bug report. 
</translate>

<translate>
=== Steam is not updated === 
</translate>
<translate>

When you restart [[Steam]] after an update, it starts the old version. ([https://github.com/NixOS/nixpkgs/issues/181904 #181904])
A workaround is to remove the user files in <code>/home/<USER>/.local/share/Steam/userdata</code>. This can be done with <code>rm -rf /home/<USER>/.local/share/Steam/userdata</code> in the terminal or with your file manager. After that, Steam can be set up again by restarting.
</translate>

<translate>
=== Game fails to start === 
</translate>
<translate>

Games may fail to start because they lack dependencies (this should be added to the script, for now), or because they cannot be patched. The steps to launch a game directly are:
* Patch the script/binary if you can
* Add a file named steam_appid.txt in the binary folder, with the appid as contents (it can be found in the stdout from steam)
* Using the LD_LIBRARY_PATH from the nix/store steam script, with some additions, launch the game binary
</translate>
<syntaxhighlight lang="bash">
LD_LIBRARY_PATH=~/.steam/bin32:$LD_LIBRARY_PATH:/nix/store/pfsa... blabla ...curl-7.29.0/lib:. ./Osmos.bin32 (if you could not patchelf the game, call ld.so directly with the binary as parameter)
</syntaxhighlight>
<translate>

Note: If a game gets stuck on Installing scripts, check for a DXSETUP.EXE process and run it manually, then restart the game launch.
</translate>

<translate>
==== Changing the driver on AMD GPUs ==== 
</translate>
{{note|This is not recommended because radv drivers tend to perform better and are generally more stable than amdvlk.}}
<translate>

Sometimes, changing the driver on AMD GPUs helps. To try this, first, install multiple drivers such as radv and amdvlk:
</translate>
<syntaxhighlight lang="nix">
hardware.graphics = {
## radv: an open-source Vulkan driver from freedesktop
enable32Bit = true;

## amdvlk: an open-source Vulkan driver from AMD
extraPackages = [ pkgs.amdvlk ];
extraPackages32 = [ pkgs.driversi686Linux.amdvlk ];
};
</syntaxhighlight>
<translate>

In the presence of both drivers, [[Steam]] will default to amdvlk. The amdvlk driver can be considered more correct regarding Vulkan specification implementation, but less performant than radv. However, this tradeoff between correctness and performance can sometimes make or break the gaming experience.
</translate>
<translate>

To "reset" your driver to radv when both radv and amdvlk are installed, set either <code>AMD_VULKAN_ICD = "RADV"</code> or <code>VK_ICD_FILENAMES = "/run/opengl-driver/share/vulkan/icd.d/radeon_icd.x86_64.json"</code> environment variable. For example, if you start [[Steam]] from the shell, you can enable radv for the current session by running <code>AMD_VULKAN_ICD="RADV" steam</code>. If you are unsure which driver you currently use, you can launch a game with [https://github.com/flightlessmango/MangoHud MangoHud] enabled, which has the capability to show what driver is currently in use.
</translate>
<translate>
=== SteamVR === 
</translate>
<translate>

The setcap issue at SteamVR start can be fixed with:
<code>sudo setcap CAP_SYS_NICE+ep ~/.local/share/Steam/steamapps/common/SteamVR/bin/linux64/vrcompositor-launcher</code>
</translate>
<translate>
=== Gamescope fails to launch when used within Steam === 
</translate>
<translate>

Gamescope may fail to start due to missing Xorg libraries. ([https://github.com/NixOS/nixpkgs/issues/214275 #214275]) To resolve this override the steam package to add them:
</translate>
<syntaxhighlight lang="nix">
programs.steam.package = pkgs.steam.override {
extraPkgs = pkgs': with pkgs'; [
xorg.libXcursor
xorg.libXi
xorg.libXinerama
xorg.libXScrnSaver
libpng
libpulseaudio
libvorbis
stdenv.cc.cc.lib # Provides libstdc++.so.6
libkrb5
keyutils
# Add other libraries as needed
];
};
</syntaxhighlight>
<translate>
=== Udev rules for additional Gamepads === 
</translate>
<translate>

In specific scenarios gamepads, might require some additional configuration in order to function properly in the form of udev rules. This can be achieved with <code>services.udev.extraRules</code>.
</translate>
<translate>

The following example is for the 8bitdo Ultimate Bluetooth controller, different controllers will require knowledge of the vendor and product ID for the device:
</translate>
<syntaxhighlight lang="nix">
services.udev.extraRules = ''
SUBSYSTEM=="input", ATTRS{idVendor}=="2dc8", ATTRS{idProduct}=="3106", MODE="0660", GROUP="input"
'';
</syntaxhighlight>
<translate>

To find the vendor and product ID of a device [https://search.nixos.org/packages?channel=unstable&show=usbutils&from=0&size=50&sort=relevance&type=packages&query=usbutils usbutils] might be useful
</translate>
<translate>
=== Known issues === 
</translate>
<translate>

"Project Zomboid" may report "couldn't determine 32/64 bit of java". This is not related to java at all, it carries its own outdated java binary that refuses to start if path contains non-Latin characters. Check for errors by directly starting local java binary within <code>steam-run bash</code>.


Resetting your password through the [[Steam]] app may fail at the CAPTCHA step repeatedly, with [[Steam]] itself reporting that the CAPTCHA was not correct, even though the CAPTCHA UI shows success. Resetting password through the [[Steam]] website should work around that.
</translate>
<translate>
== References == 
</translate>

[[Category:Applications]]
[[Category:Gaming]]

Kind

2025-12-26T19:18:57Z

Pigs: Create page, detail installation and getting started

[https://kind.sigs.k8s.io/ Kind] (Kubernetes in Docker) is a tool for running local [[Kubernetes]] clusters using [[Docker]] containers as nodes. It is commonly used for development, testing, and CI environments.

= Installation =

Kind is available in nixpkgs:

{{file|/etc/nixos/configuration.nix|nix|
<nowiki>
environment.systemPackages = with pkgs; [
kind
kubectl
];
</nowiki>
}}

= Container runtime configuration =

Enable [[Docker]] in the NixOS Configuration:

{{file|/etc/nixos/configuration.nix|nix|
<nowiki>
virtualisation.docker.enable = true;
users.users.</nowiki><<nowiki>username</nowiki>><nowiki>.extraGroups = [ "docker" ];
</nowiki>
}}

Log out and back in for group membership to take effect.

{{note|Running Docker in rootless mode may cause permission issues.}}

= Managing clusters =

To create a default cluster:

<syntaxHighlight lang=console>
$ kind create cluster
</syntaxHighlight>

This creates a single node Kubernetes cluster running inside a Docker container.

To list existing Kind clusters:

<syntaxHighlight lang=console>
$ kind get clusters
</syntaxHighlight>

To delete the cluster:

<syntaxHighlight lang=console>
$ kind delete cluster
</syntaxHighlight>

= See Also =

* [[Kubernetes]]
* [[Docker]]
* [[k3s]]

Git

2025-12-21T17:33:38Z

Pigs: improve wording, add additional information on git installation and configuring

[https://en.wikipedia.org/wiki/Git_(software) Git] is the version control system (VCS) developed by Junio C Hamano and designed by Linus Torvalds (creator of linux kernel). Git is used to maintain NixOS packages, as well as many other projects, including sources for the Linux kernel.

== Installing and configuring Git ==

On NixOS, Git can be installed and configured at either the system level or the user level with [[Home Manager]].

=== System-wide installation ===

Git can be installed system-wide either by adding it to the list of system environment packages:

{{file|/etc/nixos/configuration.nix|nix|<nowiki>
environment.systemPackages = with pkgs; [
git
];
</nowiki>}}

Or by enabling the NixOS Git module:

{{file|/etc/nixos/configuration.nix|nix|<nowiki>
programs.git.enable = true;
</nowiki>}}

Additional Git module configuration options can be found at {{nixos:option|programs.git}}.

{{note|Configuration options provided by this module are applied at the system level and therefore apply to all users on the system.}}

=== User-level configuration with Home Manager ===

Git can be configured using [[Home Manager]]:

<syntaxhighlight lang="nix">
programs.git = {
enable = true;
settings.user = {
name = "John Doe";
email = "johndoe@example.com";
};
};
</syntaxhighlight>

Aliases can be added with:

<syntaxhighlight lang="nix">
programs.git = {
enable = true;
settings.alias = {
ci = "commit";
co = "checkout";
s = "status";
};
};
</syntaxhighlight>

Git [https://git-lfs.com/ LFS] can be enabled with:

<syntaxhighlight lang="nix">
programs.git = {
enable = true;
lfs.enable = true;
};
</syntaxhighlight>
Configure git-credential-helper with libsecret:

<syntaxhighlight lang="nix">{ pkgs, ... }:

{
programs.git = {
enable = true;
package = pkgs.git.override { withLibsecret = true; };
settings = {
credential.helper = "libsecret";
};
};
}</syntaxhighlight>

To add additional configuration you can specify options in an attribute set, so to add something like this:

<syntaxhighlight lang="ini">
[push]
autoSetupRemote = true
</syntaxhighlight>

To your <code>~/.config/git/config</code>, you can add the below to <code>extraConfig</code>

<syntaxhighlight lang="nix">
{ pkgs, ... }:

{
programs.git = {
enable = true;
settings = {
push = { autoSetupRemote = true; };
};
};
}
</syntaxhighlight>

==== Using your public SSH key as a signing key ====

To configure git to automatically sign your commits using your public SSH key like so:

<syntaxhighlight lang="nix">
{
programs.git = {
enable = true;
signing = {
key = "ssh-ed25519 AAAAAAAAAAAA...AA username@hostname";
signByDefault = true;
};
settings = {
gpg = {
format = "ssh";
};
};
};
}
</syntaxhighlight>

However, note that this will also require Home Manager to manage your SSH configuration:

<syntaxhighlight lang="nix">{
programs.ssh = {
enable = true;
addKeysToAgent = "yes";
};
}</syntaxhighlight>

=== Enabling Git UI ===

Install <code>tk</code> to use the git gui:

<syntaxhighlight lang=console>
$ git citool
</syntaxhighlight>

Or you may wish to install the <code>gitFull</code> package, which includes <code>git gui</code>, <code>gitk</code>, etc. This can be installed either through system environment packages or by setting the package module option:

<syntaxhighlight lang="nix">
programs.git = {
enable = true;
package = pkgs.gitFull;
};
</syntaxhighlight>

== Management of the <code>nixpkgs</code> git repository ==

<code>nixpkgs</code> has become a git repository of quite substantial size with > 889 000 commits (as of late 2025). This brings many unoptimized tools to their limits, leading to long waiting times on certain operations. Here we’ll collect useful info on how to manage that.

=== Garbage collecting ===

Normal <code>git gc</code> should work as usual, but you should force a full garbage collect every half a year or so. <code>git gc --aggressive</code> is the command for that. For the author it did not work on the first try, since their laptop’s memory was too small and it went out of memory. According to [https://stackoverflow.com/a/4829883/1382925|this StackOverflow] answer it suffices to set some local repository config variables.

<syntaxhighlight lang=console>
$ git config pack.windowMemory 2g
$ git config pack.packSizeLimit 1g
</syntaxhighlight>

worked well on a machine with about 6–8 GB of free RAM and two processor threads, and reduced the size of the <code>nixpkgs</code> checkout from ~1.3 GB to ~0.95 GB.

= Serve Git repos via SSH =

This section implements [https://git-scm.com/book/en/v2/Git-on-the-Server-Setting-Up-the-Server Git on the Server - Setting Up the Server] on NixOS.

See also: [[gitolite]].

== Configuration ==

<syntaxhighlight lang="nix">
{ config, pkgs, ... }: {
users.users.git = {
isSystemUser = true;
group = "git";
home = "/var/lib/git-server";
createHome = true;
shell = "${pkgs.git}/bin/git-shell";
openssh.authorizedKeys.keys = [
# FIXME: Add pubkeys of authorized users
"ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIF38sHxXn/r7KzWL1BVCqcKqmZA/V76N/y5p52UQghw7 example"
];
};

users.groups.git = {};

services.openssh = {
enable = true;
extraConfig = ''
Match user git
AllowTcpForwarding no
AllowAgentForwarding no
PasswordAuthentication no
PermitTTY no
X11Forwarding no
'';
};
}
</syntaxhighlight>

== Usage ==

1. Run this on the server to create repo <code>myproject</code> accessible by user <code>git</code>

<syntaxhighlight lang="bash">
sudo -u git bash -c "git init --bare ~/myproject.git"
</syntaxhighlight>
(<code>~</code> here is the home of the user <code>git</code>, which is <code>/var/lib/git-server</code>)

2. Push to the server repo from another system

<syntaxhighlight lang="bash">
mkdir myproject
cd myproject
echo hello > a
git init
git add .
git commit -m init
git remote add origin git@myserver:myproject.git
git push origin master
</syntaxhighlight>

3. Clone and edit the server repo from another system

<syntaxhighlight lang="bash">
git clone git@myserver:myproject.git
cd myproject
cat a
echo world >> a
git commit -am hello
git push origin master
</syntaxhighlight>

== Bisecting Nix regressions ==

{{main|bisecting}}

[[Category:Applications]]
[[Category:CLI Applications]]
[[Category:Version control]]

JAX

2025-12-09T19:11:28Z

Pigs: /* Example shell.nix with GPU support */ syntax highlight code block, additional crosslinking and formatting

[https://github.com/google/jax JAX] is a framework for program transformation, esp. for automatic differentiation and machine learning. It's available in [[Nixpkgs]] in the <code>python3Packages.{{{nixos:package|python3Packages.jax|jax}}, {{nixos:package|python3%20jaxlib|jaxlib}}, {{nixos:package|python3*.jaxlibWithCuda|jaxlibWithCuda}}}</code> packages.

{{tip|1='''Cache''': Using the [https://app.cachix.org/cache/nix-community nix-community cache] is recommended! It will save you valuable time and electrons. Getting set up should be as simple as <code>cachix use nix-community</code>. See the [[CUDA]] wiki page for more info.
}}

== Example shell.nix, CPU only ==
<syntaxHighlight lang=nix>
let
# Last updated 01/31/2022. Check status.nixos.org for updates.
pkgs = import (fetchTarball("https://github.com/NixOS/nixpkgs/archive/376934f4b7ca6910b243be5fabcf3f4228043725.tar.gz")) {};
in pkgs.mkShell {
buildInputs = with pkgs; [
python3
python3Packages.jax
python3Packages.jaxlib
];
}
</syntaxHighlight>

== Example shell.nix with GPU support ==
JAX defers execution to the jaxlib library for execution. In order to use GPU support you'll need a [[NVIDIA]] GPU and [[OpenGL]]. In your <code>/etc/nixos/configuration.nix</code>:
<syntaxHighlight lang=nix>
# NVIDIA drivers are unfree
nixpkgs.config.allowUnfree = true;
services.xserver.videoDrivers = [ "nvidia" ];
hardware.opengl.enable = true;
</syntaxHighlight>
Then you can use the <code>jaxlibWithCuda</code> package (equivalent to setting the <code>cudaSupport</code> parameter):
<syntaxHighlight lang=nix>
let
# Last updated 01/31/2022. Check status.nixos.org for updates.
pkgs = import (fetchTarball("https://github.com/NixOS/nixpkgs/archive/376934f4b7ca6910b243be5fabcf3f4228043725.tar.gz")) {};
in pkgs.mkShell {
buildInputs = with pkgs; [
python3
python3Packages.jax
python3Packages.jaxlibWithCuda
];
}
</syntaxHighlight>
You can test that JAX is using the GPU as intended with

<syntaxHighlight lang=bash>
# after version 0.8.0
python -c "import jax.extend as ex; print(ex.backend.get_backend().platform)"

# before version 0.8.0
python -c "from jax.lib import xla_bridge; print(xla_bridge.get_backend().platform)"
</syntaxHighlight>

It should print either <code>cpu</code>, <code>gpu</code>, or <code>tpu</code>.

{{Note| [[Hydra]] may not cache <code>jaxlibWithCuda</code> builds on cache.nixos.org since CUDA is [[unfree software]]. @samuela publishes builds on a public cachix [https://app.cachix.org/cache/ploop#pull ploop] cache. These are periodically built and pushed from [https://github.com/samuela/nixpkgs-upkeep/ nixpkgs-upkeep].}}

== FAQ ==
=== How do I package JAX libraries? ===
Never ever ever put <code>jaxlib</code> in <code>propagatedBuildInputs</code>. However, it may live happily in <code>buildInputs</code> or <code>checkInputs</code>. See https://github.com/NixOS/nixpkgs/pull/156808 for context.

=== RuntimeError: Unknown: no kernel image is available for execution on the device ===
This usually indicates that you have a driver version that is too old for the CUDA toolkit version the package is built with. The easiest fix is to set the environment variable <code>XLA_FLAGS="--xla_gpu_force_compilation_parallelism=1"</code>. Also consider upgrading your CUDA driver.

See https://github.com/google/jax/issues/5723#issuecomment-913038780.

[[Category:Applications]]
[[Category:Python]]

Talk:Libvirt

2025-12-04T05:02:03Z

Pigs: /* Libvirt's extra group */ Reply

== Watch for SPICE support in Apache Guacamole ==

https://issues.apache.org/jira/browse/GUACAMOLE-261 If this comes to fruition, this could streamline the guide to setting up SPICE via web browser, probably reduces attack surface area a lot. (Could be a risky proposition to expose SPICE to the internet directly, via websocket...) — [[User:Winny|Winny]] ([[User talk:Winny|talk]]) 18:31, 20 April 2023 (UTC)

== Libvirt's extra group ==

Shouldn't extraGroups = [ "libvirt" ] instead of "libvirtd"?

Ref: https://wiki.archlinux.org/title/Libvirt#Using_libvirt_group, https://askubuntu.com/questions/930491/group-libvirtd-does-not-exist-while-installing-qemu-kvm. [[User:Daanturo|Daanturo]] ([[User talk:Daanturo|talk]]) 03:43, 4 December 2025 (UTC)

:<code>libvirtd</code> is correct, different Linux distros have different naming conventions.
:See https://github.com/NixOS/nixpkgs/blob/8bb5646e0bed5dbd3ab08c7a7cc15b75ab4e1d0f/nixos/modules/virtualisation/libvirtd.nix#L429C1-L429C58 for the source [[User:Pigs|Pigs]] ([[User talk:Pigs|talk]]) 05:02, 4 December 2025 (UTC)

Locales

2025-10-30T18:09:39Z

Pigs: fix broken supportedLocales to extraLocales

NixOS allows to set the default [https://en.wikipedia.org/wiki/Locale_(computer_software) locale] as well as individual locales in the system configuration file:

{{file|/etc/nixos/configuration.nix|nix|<nowiki>
# Mandatory
i18n.defaultLocale = "en_US.UTF-8";

# Optionally (BEWARE: requires a different format with the added /UTF-8)
i18n.extraLocales = ["es_VE.UTF-8/UTF-8"];

# Optionally
i18n.extraLocaleSettings = {
# LC_ALL = "en_US.UTF-8"; # This overrides all other LC_* settings.
LC_CTYPE = "en_US.UTF8";
LC_ADDRESS = "es_VE.UTF-8";
LC_MEASUREMENT = "es_VE.UTF-8";
LC_MESSAGES = "en_US.UTF-8";
LC_MONETARY = "es_VE.UTF-8";
LC_NAME = "es_VE.UTF-8";
LC_NUMERIC = "en_US.UTF-8";
LC_PAPER = "es_VE.UTF-8";
LC_TELEPHONE = "es_VE.UTF-8";
LC_TIME = "es_VE.UTF-8";
LC_COLLATE = "es_VE.UTF-8";
};
</nowiki>
}}

{{nixos:option|i18n.defaultLocale}} will set the language and the character set systemwide to the desired value. Specifically, defaultLocale will define the <code>LANG</code> environment variable.

In addition, with {{nixos:option|i18n.extraLocales}}, the system will also support Venezuelan Spanish. The value <code>"all"</code> means that all locales supported by Glibc will be installed. A full list of supported locales can be found at https://sourceware.org/git/?p=glibc.git;a=blob;f=localedata/SUPPORTED.

And in the {{nixos:option|i18n.extraLocaleSettings}}, it is possible to set the LC locales individually. This does allow fine-grained adjustments of the used locales. In the above example a mix of American English and Venezuelan Spanish is used. It is also possible to find these settings at [https://search.nixos.org/options NixOS options]. Just search for i18 locale.

{{note|The setting <code>i18n.extraLocales</code> requires a different format to <code>i18n.extraLocaleSettings</code> with the added <code>/UTF-8</code>. Otherwise, your locale settings will likely not work.}}

== Troubleshooting when using nix on non-NixOS linux distributions ==

You may need to set the environmental variable LOCALE_ARCHIVE to point to your system's locale-archive. The following can be added to your .zshenv (zsh) or .profile (bash) and applies to Debian, Red Hat, and Arch derivatives:

<syntaxhighlight lang=bash>
export LOCALE_ARCHIVE=/usr/lib/locale/locale-archive
</syntaxhighlight>

And if that file from the local system is somehow broken:

<syntaxhighlight lang="bash">
# May require a one-time installation with:
nix profile install nixpkgs#glibcLocales
# Using nix profile
export LOCALE_ARCHIVE="$(nix profile list --json | jq '.elements[] | select(.attrPath? and (.attrPath | type == "string") and (.attrPath | endswith("glibcLocales"))) | .storePaths[0]')/lib/locale/locale-archive"

# Legacy usage with `nix-env`: May require a one-time installation with: nix-env -iA nixpkgs.glibcLocales
export LOCALE_ARCHIVE="$(nix-env --installed --no-name --out-path --query glibc-locales)/lib/locale/locale-archive"

</syntaxhighlight>

== Enable locale support in Nix shell ==

To support locales within a Nix shell, for example to get localised command output, you need to do something similar:

<syntaxhighlight lang=bash>
pkgs.mkShell {
# [other code omitted]
LOCALE_ARCHIVE = "${pkgs.glibcLocales}/lib/locale/locale-archive";
}
</syntaxhighlight>

[[Category:Configuration]]

KSMBD

2025-09-21T16:43:33Z

Pigs: Remove nonexistent configuration options

[https://docs.kernel.org/next/filesystems/cifs/ksmbd.html KSMBD] is a Linux kernel server which implements SMB3 protocol in kernel space for sharing files over network.

Userspace utilities for the KSMBD kernel SMB server are provided by the {{nixos:package|ksmbd-tools}}.

[[Category:Filesystem]]
[[Category:Networking]]

User:Pigs/NixOS Wiki

2025-06-28T03:07:59Z

Pigs: testing out changes on my page

<languages/>
<translate>


__NOTOC__




<div class="row home-panes">
<div class="col-md-7">
{{home:box|get-started|icon=clarifications|Getting started|
Welcome to the official NixOS Wiki!


NixOS is a [https://kernel.org/ Linux] operating system based on the Nix package manager and the Nixpkgs package repository.

This wiki complements the [https://nixos.org/nixos/manual NixOS Manual] with user guides, configuration examples, troubleshooting tips, and community knowledge.


'''New to Nix? Start here:'''
* [[Nix Ecosystem|Overview of the Nix Core Ecosystem]] - for a broad orientation
* [[Overview_of_the_NixOS_Linux_distribution|NixOS]] - the operating system
* [[Nix package manager]] - the core tool
* [[Nixpkgs|Nixpkgs]] - package repository
* [[Overview of the Nix Language|Nix Language]] - the domain specific language behind configurations

To get started with Nix on another OS, visit [https://nix.dev nix.dev] for guides on using Nix on other Linux distributions or macOS.
}}


{{home:box|hosting|icon=cloud|Setting up NixOS|
To install NixOS, start with the [[NixOS Installation Guide]].

Guides for specific environments:
* [[NixOS as a desktop]] - personal computers
* [[NixOS as a server]] - server environments
* [[NixOS on ARM]] - ARM devices
* [[NixOS friendly hosters|NixOS in the cloud]] - cloud hosting options
}}


{{home:box|doctopics|icon=manual|Documentation & topics|
Visit the [[Resources]] page for links to essential Nix documentation. Notable examples:


'''Essential nix manuals:'''
* [https://nixos.org/nixos/manual/ NixOS manual]
* [https://nixos.org/nix/manual/ Nix manual]
* [https://nixos.org/nixpkgs/manual/ Nixpkgs manual]
* [https://nixos.org/hydra/manual/ Hydra manual]

'''Explore by category:'''
* [[:{{ns:14}}:Software|Software]]
* [[:{{ns:14}}:Hardware|Hardware]]
* [[:{{ns:14}}:Desktop|Desktop]]
* [[:{{ns:14}}:Server|Server]]
* [[:{{ns:14}}:Community|Community]]


'''Helpful pages:'''
* [[FAQ]]
* [[Cheatsheet]]
* [[Nix vs. Linux Standard Base]]
* [[Terms and Definitions in Nix Project]]
* [[Ubuntu vs. NixOS|Comparison between Ubuntu and NixOS]]
}}

</div>
<div class="col-md-5">

{{home:box|get-in-touch|icon=dialog-hi|Get in touch|
With the community
* [https://nixos.org/ Official NixOS website]
* [https://nixos.org/community/#governance-teams Official Teams]
* [[Nix Community|Community overview]]
* [[Get In Touch|Chats and forums]]
* [[Support|Get support]]
* [[Get In Touch#Events|Events]]


About the Wiki
* Matrix chat for Wiki contributors [https://matrix.to/#/#wiki:nixos.org #wiki:nixos.org]
* Email [mailto:wiki@nixos.org wiki@nixos.org] for contacting wiki.nixos.org regarding any wiki operational topics or requests
* [[Contributing|Contribute to wiki and NixOS]]
* [[Manual of Style]]
}}

{{home:box|news|News|{{NixOS_Wiki:News}}
[[NixOS_Wiki:News{{!}}... all news articles →]]
}}


{{home:box|wikipages|Special pages|3=<ul>
<li>[{{fullurl:Special:SpecialPages}} Overview of special pages]</li>
<li>[{{fullurl:Special:AllPages|hideredirects=1}} All pages of {{SERVERNAME}}]</li>
<li>[[Special:Categories|All categories of {{SERVERNAME}}]]</li>
<li>[{{fullurl:Special:RecentChanges|hidebots=1&reviewStatus=unpatrolled}} Unpatrolled changes of {{SERVERNAME}}]</li>
</ul>}}

</div>
</div>
</translate>

User:Pigs

2025-06-15T18:14:08Z

Pigs: Created page with "Hello, You can see my contributions here: https://wiki.nixos.org/wiki/Special:Contributions/Pigs My blog post is at https://pigs.dev"

Hello,

You can see my contributions here: https://wiki.nixos.org/wiki/Special:Contributions/Pigs

My blog post is at https://pigs.dev

NixOS as a server

2025-06-15T17:38:22Z

Pigs: Create initial page

[[NixOS]] is well-suited for server deployments, offering declarative, reproducible system configurations and atomic system upgrades and rollbacks. This page provides an overview of configuring, deploying, and maintaining NixOS systems in server environments.

== Initial setup ==

Refer to the [[NixOS Installation Guide]] for detailed installation instructions.

For setting up NixOS in the cloud, refer to the [[NixOS friendly hosters]].

For guidance on defining and maintaining your system configuration, consult [[NixOS system configuration]].

== NixOS infrastructure tools ==

=== Deployment orchestration ===

* [[nixos-anywhere]] - Install NixOS everywhere via SSH

* [https://github.com/zhaofengli/colmena Colmena] - A simple, stateless NixOS deployment tool modeled after NixOps and morph, written in Rust

* [[Morph]] - NixOS deployment tool

* [[Clan]] - Peer-to-peer computer management framework for NixOS

* [[Krops]] - Lightweight toolkit to deploy NixOS systems

* [https://github.com/serokell/deploy-rs deploy-rs] - A simple, multi-profile Nix-flake deploy tool

* [[NixOps]] - Native NixOS deployment tool for cloud and virtual infrastructure (not currently recommended)

=== Binary cache and CI ===

See the main pages, [[Binary Cache]] and [[Continuous Integration (CI)]].

* [https://www.cachix.org/ Cachix] - Share binaries between CI, development and deployment environments

* [https://github.com/zhaofengli/attic Attic] - Self-hostable Nix Binary Cache server backed by an S3-compatible storage provider

* [[Hydra]] - Tool for continuous integration testing and software release

=== Secrets management ===

* [[Agenix]] - commandline tool for managing secrets in your Nix configuration
* [https://github.com/Mic92/sops-nix sops-nix] - Atomic, declarative, and reproducible secret provisioning for NixOS based on sops

Refer to [[Comparison of secret managing schemes]] for additional tools and in-depth comparisions

== Common server configurations ==

=== Web servers ===

* [[Nginx]] - Web server that can also be used as a reverse proxy, load balancer, mail proxy and HTTP cache.
* [[Apache]] - Free and open-source cross-platform web server
* [[Caddy]] - Extensible, cross-platform, open-source web server written in Go

=== File sharing and storage ===

* [[NFS]] - Unix-based network file sharing
* [[Samba]] - Windows-compatible file and printer sharing

=== Backup and replication ===

* [[ZFS]] - With native snapshots and replication
* [[Syncthing]] - Decentralized file synchronization application
* [[Restic]] - Fast and secure backup program
* [[BorgBackup]] - Deduplicating incremental backup program for local and remote data
* [[Rclone]] - Command-line program that synchronizes files and directories between different cloud storage services

=== VPN and networking ===

* [[WireGuard]] - Fast, modern, secure VPN tunnel

* [[OpenVPN]] - Flexible VPN implementation for secure networking

* [[Firewall]] - NixOS has an integrated firewall based on iptables or nftables

* [[SSH]] - secure remote administration.

== See Also ==

* [[NixOS friendly hosters]] - Guides on setting up NixOS with various cloud providers

* [[NixOS Installation Guide]]

* [[NixOS as a desktop]] - Desktop counterpart to this article

* [[NixOS system configuration]]

[[Category:NixOS]]
[[Category:Server]]

Talk:Nix ecosystem

2025-06-15T17:28:05Z

Pigs: /* Is this an official term? */ Reply

== Is this an official term? ==

I see the [[Nix ecosystem]] referenced in different parts of the wiki, however, is it an 'official' term? Or rather, does it have a formal definition in the documentation?

I'm not necessarily proposing changing the page, rather, I am wondering whether this terminology is the best way to define the set of tools we use. To be clear, it might be, I'm simply trying to construct a Nix learning journey from [[:Wikipedia:First principle|first principles]], and to figure out the most natural way all the tools we use come together. [[User:DoggoBit|DoggoBit]] ([[User talk:DoggoBit|talk]]) 23:43, 14 June 2025 (UTC)

:I don't think it has a formal term but I do see it places such as the opening statement on https://nix.dev/index.html: "nix.dev is the home of official documentation for the Nix ecosystem". So therefore I would take that to mean anything mentioned on nix.dev is considered to be in the Nix ecosystem. [[User:Pigs|Pigs]] ([[User talk:Pigs|talk]]) 17:21, 15 June 2025 (UTC)
::Maybe a looser definition is anything mentioned in https://github.com/NixOS or https://github.com/nix-community [[User:Pigs|Pigs]] ([[User talk:Pigs|talk]]) 17:28, 15 June 2025 (UTC)

Talk:Nix ecosystem

2025-06-15T17:21:07Z

Pigs: /* Is this an official term? */ Reply

Template talk:NixOS Manual

2025-06-15T17:00:34Z

Pigs: /* {{Manual }}does not work for nixos manual */ Reply

== {{{{:manual}} }}does not work for nixos manual ==

Currently, {{:manual}} only links to https://nix.dev, the nix language reference material and does not have capabilities to link to https://nixos.org/manual/nixos where the nixos manual lives.

Until {{:manual}} can link to the nixos manual, I don't think marking this page for removal is appropriate. [[User:Pigs|Pigs]] ([[User talk:Pigs|talk]]) 06:31, 9 June 2025 (UTC)

:Oh yeah, that is a given. I will improve {{tl|manual}} before proceeding. Thanks for pointing it out! [[User:DoggoBit|DoggoBit]] ([[User talk:DoggoBit|talk]]) 13:26, 9 June 2025 (UTC)
:I have updated {{tl|manual}}, it should now support all 3 use cases, as well as subsections within the Nix reference manual. Would appreciate a double check to make sure I didn't miss anything. [[User:DoggoBit|DoggoBit]] ([[User talk:DoggoBit|talk]]) 11:35, 15 June 2025 (UTC)
::Looks good to me [[User:Pigs|Pigs]] ([[User talk:Pigs|talk]]) 17:00, 15 June 2025 (UTC)

Swap

2025-06-15T16:38:28Z

Pigs: /* Zswap swap cache */ add note of needing to enable systemd for using lz4

[[Category:Configuration]]

Swap provides additional virtual memory by extending physical RAM. This can be accomplished by using space on disk, such as [[#Swap file|swap file]] or [[#Swap partition|swap partition]], or through compression based methods like [[#Zram swap|zram]]. Additionally, [[#Zswap swap cache|zswap]] can act as a RAM-based compressed cache sitting in front of a traditional disk-based swap device.

= Configuration =

The following sections describe how to configure and manage swap on NixOS.

To check your current swap setup and usage, you can use the following command: <code>swapon --show</code>

{{note| <code>nixos-generate-config</code> does not automatically generate a <code>swapDevices</code> entry if your system uses a swap file or <code>/dev/zram</code> for swap. For details, see the [https://github.com/NixOS/nixpkgs/pull/63083 discussion on GitHub]}}

{{note|It's generally recommended to use either zram or zswap, but not both simultaneously, as they serve overlapping roles and may lead to suboptimal memory management behavior.}}

== Swap file ==

A swap file provides swap space using a regular file on your filesystem, offering greater flexibility compared to a dedicated swap partition.

To add a swap file in NixOS, add the following:

{{file|/etc/nixos/configuration.nix|nix|
<nowiki>
swapDevices = [{
device = "/var/lib/swapfile";
size = 16*1024; # 16 GB
}];
</nowiki>
}}

This will create a 16GB swapfile at <code>/var/lib/swapfile</code>. The <code>size</code> value [https://search.nixos.org/options?show=swapDevices.*.size is specified in megabytes]

== Swap partition ==

Swap partitions are typically created during the initial disk partitioning phase of a NixOS installation. For instructions on creating swap partitions, see the relevant NixOS manual sections for [https://nixos.org/manual/nixos/stable/#sec-installation-manual-partitioning-UEFI UEFI]/[https://nixos.org/manual/nixos/stable/#sec-installation-manual-partitioning-MBR MBR] partition schemes and [https://nixos.org/manual/nixos/stable/#sec-installation-manual-partitioning-formatting formatting].

== Zram swap ==

Zram is a kernel module for creating a compressed block device in RAM.

{{file|/etc/nixos/configuration.nix|nix|
<nowiki>
zramSwap.enable = true; # Creates a zram block device and uses it as a swap device
</nowiki>
}}

It is an alternative or complementary approach to swap disks, suitable for systems with enough RAM. In the event the system needs to swap it will move uncompressed RAM contents into the compressed area, saving RAM space while effectively increasing the available RAM at the cost of computational power for compression and decompression.

See [https://search.nixos.org/options?query=zramSwap zramSwap] for a full list of available options and their descriptions.

=== Zram writeback ===

Zram supports writeback functionality, allowing idle or incompressible pages to be moved to a backing storage device rather than keeping it in memory. Currently, writeback can only use block storage devices (such as partitions) and does not support swap files. The backing partition must be manually created first, but does not require formatting.

An example configuration:

{{file|/etc/nixos/configuration.nix|nix|
<nowiki>
zramSwap = {
enable = true;
writebackDevice = "/dev/sda1"
</nowiki>
}}

To verify the block storage device is being used:

<syntaxhighlight lang="bash">
cat /sys/block/zram0/backing_dev
</syntaxhighlight>

== Zswap swap cache ==

[https://docs.kernel.org/admin-guide/mm/zswap.html Zswap] is a compress RAM cache for swap pages. It acts as a middle layer between system memory and a traditional disk-based swap device, storing compressed pages in RAM before optionally writing them out to disk-based swap if necessary.

Unlike zram, zswap requires a disk-based swap device to back it.

Zswap is controlled by kernel parameters and can be enabled in your NixOS configuration by setting appropriate options through <code>boot.kernelParams</code>.

{{file|/etc/nixos/configuration.nix|nix|
<nowiki>
boot.kernelParams = [
"zswap.enabled=1" # enables zswap
"zswap.compressor=lz4" # compression algorithm
"zswap.max_pool_percent=20" # maximum percentage of RAM that zswap is allowed to use
];
</nowiki>
}}

{{note|If you use the <code>lz4</code> algorithm, you will also need to set {{nixos:option|boot.initrd.systemd.enable}} to true}}

You can verify zswap's runtime status via <code>cat /sys/module/zswap/parameters/enabled</code> and inspect usage statistics with <code># grep -r . /sys/kernel/debug/zswap/</code>

== Disable swap ==

To remove all swap devices from NixOS, set the following to remove the swap partition or file from being included in <code>/etc/fstab</code>.

<syntaxhighlight lang="nix">
swapDevices = lib.mkForce [ ];
</syntaxhighlight>

If you are using GPT partitioning tables, <code>systemd-gpt-auto-generator(8)</code> will still mount your swap partition automatically. You must therefore turn on attribute 63 on your partition in the partition table. This can be done with gptfdisk or similar:

<syntaxhighlight lang="console">
gdisk /dev/sda
x
a
<partition number>
63
<enter>
w
</syntaxhighlight>

= Tips and Tricks =

== Encrypt swap with random key ==

Swap can be automatically encrypted with a new key on every boot. This can be used to simplify certain disk layouts, such as securing a swap file on a filesystem partition without an encryption container (such as LUKS).

<syntaxhighlight lang="nix">
swapDevices = [{
device = "/dev/sdXY";
randomEncryption.enable = true;
}];
</syntaxhighlight>

== Adjusting swap usage behaviour ==

[https://docs.kernel.org/admin-guide/sysctl/vm.html#swappiness Swappiness] controls how aggressibely swap space is used. By default, Linux uses a swappiness value of 60. Higher values will make the kernel prefer swapping out idle processes sooner. Conversely lower values will try to avoid swapping as much as possible, keeping processes in RAM unless absolutely necessary. An optimal value is workload dependent and will will require experimentation.

{{file|/etc/nixos/configuration.nix|nix|
<nowiki>
boot.kernel.sysctl = {
"vm.swappiness" = 10;
};
</nowiki>
}}

You can see your current swappiness level by <code>cat /proc/sys/vm/swappiness</code>.

== ZFS and swap ==

OpenZFS does not support swap on zvols nor do they support swap files on a ZFS dataset.

Instead you should set up a swap partition or swap file on a non-ZFS filesystem.<ref>https://utcc.utoronto.ca/~cks/space/blog/solaris/ZFSForSwapMyViews</ref>

== Using swap files on Btrfs ==

For Btrfs file system-specific considerations, see the [[Btrfs#Swap file|Btrfs swap file section]].

== Swapspace ==

[https://github.com/Tookmund/Swapspace Swapspace] is a dynamic swap space manager for GNU/Linux. i.e. it allows unused disk space to be utilised as swap to handle the occasional memory-intensive task, and frees the disk space once done.

Enable it via <code>services.swapspace.enable = true;</code> in your nixos configuration. And after switching, check that <code>systemctl status swapspace.service</code> is green, that's all, swapspace will auto manage swap for you.

See all the options it supports here, [https://search.nixos.org/options?query=swapspace search.nixos.org]

You can also use zramSwap along with this service.

See your active swap partitions/files with <code>swapon</code>. For eg.
{{warning|Do not run the following without swapspace active + more than 34GB free disk space (assuming 8GB ram) OR without 42GB+ ram to spare.}}
<syntaxhighlight lang="console">
# Read the WARNING above, and adjust 2, 20GB according to your free space
$ # nix shell nixpkgs#stress.out -c stress --vm 2 --vm-bytes 20G
$ swapon
NAME TYPE SIZE USED PRIO
/dev/zram0 partition 13.8G 2.6G 5
/var/lib/swapspace/1 file 5.2G 59.2M -2
/var/lib/swapspace/2 file 6.1G 56.4M -3
</syntaxhighlight>

Flakes

2025-06-14T20:15:56Z

Pigs: add citation to lock file and showing flake inputs

<languages />

<translate>

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

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

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

=== Enabling flakes ===

====Enable flakes temporarily==== 


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

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


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

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

====With Home Manager==== 


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

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

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

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

===Basic Usage of Flake=== 


{{Warning | Since contents of flake files are copied to the world-readable [[Nix_package_manager#Nix_store|Nix store]] folder, do not put any unencrypted secrets in flake files. You should instead use a [[Comparison of secret managing schemes|secret managing scheme]].}}


{{Note | For flakes in [[git]] repositories, 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.}}

====Generate flake.nix file==== 


To initialize a flake, run the following flake command in the project directory:

</translate>
<syntaxhighlight lang="console">
$ nix flake init
</syntaxhighlight>
<translate>

====Common structure====

The above command will provide a very simple flake file looking like:

</translate>
<syntaxHighlight lang=nix>
{
description = "A very basic flake";

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

outputs = { self, nixpkgs }: {

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

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

};
}
</syntaxHighlight>
<translate>

You will then be able to build this flake with <code>nix build</code> and run it with <code>nix run</code>

{{note|Flakes force you to specify a program for each supported architecture. To avoid this, refer to [[#Defining a flake for multiple architectures]] section of the wiki.}}

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


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

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

<syntaxhighlight lang="console">
$ nix flake show
└───packages
└───x86_64-linux
├───default: package 'hello-2.12.2'
└───hello: package 'hello-2.12.2'
</syntaxhighlight>

==== Development shells ====

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

<syntaxhighlight lang="nix">
{
description = "Example flake with a devShell";

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

outputs = { self, nixpkgs}:
let
system = "x86_64-linux";
pkgs = import nixpkgs { inherit system; };
in {
devShells.x86_64-linux.default = pkgs.mkShell {
buildInputs = with pkgs; [
hello
];
shellHook = ''
echo "Welcome to the devShell!"
'';
};
};
}
</syntaxhighlight>

To enter the development shell environment:

<syntaxhighlight lang="console">
$ nix develop
</syntaxhighlight>

{{note|You don’t need to define a devShell to enter a development shell using nix develop.
If no devShell is defined, nix develop will drop you into an environment containing the default build dependencies of the flake (if any).}}

==== Build specific attributes in a flake repository ==== 


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:

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

Likewise, you can specify an attribute with the run command: <code>nix run .#hello</code> and the develop command: <code>nix develop .#hello</code>.

== Flake schema == 


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

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

Nixpkgs can alternatively also point to an url cached by the NixOS organization:

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

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

<translate>


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:

</translate>
<code>inputs.hyprland.url = "github:hyprwm/Hyprland";</code>
<translate>


If you want to make Hyprland follow the nixpkgs input to avoid having multiple versions of nixpkgs, this can be done using the following code:

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


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

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

By default, Git submodules in package <code>src</code>'s won't get copied to the nix store, this may cause the build to fail. Flakes in Git repositories can declare that they need Git submodules to be enabled. Since Nix version [https://discourse.nixos.org/t/nix-2-27-0-released/62003 2.27], you can enable submodules by:

<syntaxhighlight lang="nix">
inputs.self.submodules = true;
</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

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


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

== Core usage patterns ==

=== Making your evaluations pure === 


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


* {{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.getEnv</code> is also impure. Avoid reading from environment variables and likewise, do not reference files outside of the flake's directory.

=== Defining a flake for multiple architectures ===

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

<syntaxhighlight lang="nix">
{
description = "A flake targeting multiple architectures";

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

outputs = { self, nixpkgs }: let
systems = [ "x86_64-linux" "aarch64-linux" ];
forAllSystems = f: builtins.listToAttrs (map (system: {
name = system;
value = f system;
}) systems);
in {
packages = forAllSystems (system: let
pkgs = nixpkgs.legacyPackages.${system};
in {
hello = pkgs.hello;
default = pkgs.hello;
});
};
}
</syntaxhighlight>

You can also use third-parties projects like [[Flake Utils|flake-utils]] or [[Flake Parts|flake-parts]] that automatically provide code to avoid this boilerplate. To avoid re-defining the program multiple times, refer to [[Flake Utils#Defining a flake for multiple architectures]]

=== Using overlays ===

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

=== Enable unfree software === 

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

<syntaxhighlight lang="nix">
{
inputs.nixpkgs.url = "github:nixos/nixpkgs?ref=nixos-unstable";
outputs = { self, nixpkgs, flake-compat }:
let
system = "x86_64-linux";
pkgs = import nixpkgs { inherit system; config.allowUnfree = true;};
in {
...
};
}
</syntaxhighlight>

== NixOS configuration with flakes ==

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

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

== Development tricks == 

=== Automatically switch nix shells with direnv === 


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

=== Pushing Flakes to Cachix === 

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

=== Flake support in projects without flakes === 


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

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

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

=== Efficiently build multiple flake outputs ===


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

=== Build a package added in a PR === 

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


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:

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


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

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

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

</translate>
<syntaxHighlight lang=bash>
cd ~/libdep-src-checkout/
nix develop # Or `nix-shell` if applicable.
export prefix="./install" # configure nix to install it here
buildPhase # build it like nix does
installPhase # install it like nix does
</syntaxHighlight>
<translate>


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

</translate>
<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>
<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.

== See also == 

=== Official sources ===


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


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


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


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

=== Guides ===


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

=== Useful flake modules ===


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

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

* [[Flake Compat|flake-compat]]: A compatibility layer for flakes


* [https://github.com/nix-community/todomvc-nix building Rust and Haskell flakes]

{{references}}

</translate>
[[Category:Software]]
[[Category:Nix]]
[[Category:Nix Language]]
[[Category:Flakes]]

Firewall

2025-06-13T17:48:17Z

Pigs: Reword and refactor layout

[[NixOS]] includes an integrated firewall based on [https://www.netfilter.org/ iptables]/[https://www.nftables.org/ nftables], which can be configured declaratively through the [[NixOS system configuration]]. By default, the firewall is enabled and restricts incoming network connections, allowing users to explicitly define which ports and services should be accessible.

== Enable ==

The firewall is enabled by default on NixOS. To explicitly ensure it is enabled, add the following option to your system configuration:

{{file|/etc/nixos/configuration.nix|nix|<nowiki>
networking.firewall.enable = true;
</nowiki>}}

With the firewall enabled, all local ports and services will be unreachable from external connections unless explicitly allowed.

To use the newer nftables backend instead of iptables, set the option {{nixos:option|networking.nftables.enable}} to true.

== Configuration ==

To allow specific TCP/UDP ports or port ranges on all interfaces, use following syntax:

{{file|/etc/nixos/configuration.nix|nix|<nowiki>
networking.firewall = {
enable = true;
allowedTCPPorts = [ 80 443 ];
allowedUDPPortRanges = [
{ from = 4000; to = 4007; }
{ from = 8000; to = 8010; }
];
};
</nowiki>}}

Refer to {{nixos:option|networking.firewall}} for more firewall module options.

{{note|Many services also provide an option to open the required firewall ports automatically. For example, the media server Jellyfin offers the option <code><nowiki>services.jellyfin.openFirewall = true;</nowiki></code> which will open the required TCP ports.}}

{{warning|Firewall rules may be overwritten by [[Docker]], as per https://github.com/NixOS/nixpkgs/issues/111852}}

=== Interface specific rules ===

It is possible to define firewall rules for specific network interfaces. This can be useful for allowing different ports or services on different network connections. Add the following to your system configuration:

{{file|/etc/nixos/configuration.nix|nix|<nowiki>
networking.firewall.interfaces."eth0".allowedTCPPorts = [ 80 443 ];
</nowiki>}}

In this case, ports <code>80</code> and <code>443</code> will be allowed for the interface <code>eth0</code>.

== Tips and tricks ==

=== Temporary firewall rules ===

If using iptables, for temporary changes to the firewall rules, you can install the [https://search.nixos.org/packages?query=nixos-firewall-tool <code>nixos-firewall-tool</code>] package, which is a [https://github.com/NixOS/nixpkgs/blob/7eee17a8a5868ecf596bbb8c8beb527253ea8f4d/pkgs/by-name/ni/nixos-firewall-tool/nixos-firewall-tool.sh thin wrapper] around <code>iptables</code>.

[[Category:Server]]
[[Category:Applications]]

Apache Httpd

2025-06-13T17:16:08Z

Pigs: Create initial page

[https://httpd.apache.org/ Apache Http Server] is a web server developed by the [https://www.apache.org/ Apache Software Foundation].

== Enabling ==

To enable the Apache HTTP server service on your system, add the following options to your [[NixOS system configuration]]. Additionally, you may wish to open the appropriate ports in the [[firewall]] to allow HTTP and HTTPS traffic.

{{file|/etc/nixos/configuration.nix|nix|
<nowiki>
services.httpd.enable = true;
networking.firewall.allowedTCPPorts = [ 80 443 ];
</nowiki>
}}

Refer to {{nixos:option|services.httpd}} for more module configuration options.

== Tips and tricks ==

=== Using ACME certificates ===

Refer to {{NixOS Manual|name=NixOS Manual: Chapter - Package Management|anchor=#module-security-acme-httpd}}.

== See also ==

* [[Firewall]]
* [[Nginx]]

[[Category:Server]]

Nixpkgs

2025-06-12T17:42:49Z

Pigs: point to status page for current version

<translate>

'''Nixpkgs''' is the largest repository of [[Nix]] packages and [[NixOS]] modules. The repository is [https://github.com/nixos/nixpkgs hosted on GitHub] and maintained by the community, with official backing from the [[NixOS Foundation]].


To search among available packages and options, see [[Searching packages]].


As highlighted in [https://nixos.org/blog/announcements/2024/nixos-2411/ the announcement] of the NixOS 24.11 release, ''"NixOS is already known as [https://repology.org/repositories/statistics/newest the most up to date distribution] while also being [https://repology.org/repositories/statistics/total the distribution with the most packages]."'' This is thanks to the community's continued dedication to making Nixpkgs the preeminent Linux package repository.

== Subpages == 


There are a number of articles especially related to working with <tt>nixpkgs</tt>:
{{Special:PrefixIndex/{{FULLPAGENAME}}/ |hideredirects=1 |stripprefix=1}}

== Releases == 


{{main|Channel branches}}


The packages and modules hosted on Nixpkgs are distributed through various [[channel branches]] intended for particular use-cases. In practice they are differentiated by the level of testing updates must pass on the official [https://nixos.org/hydra/manual/#idm140737315980672 nixos.org Hydra instance] and the number of updates they receive.


For [[NixOS]] users, <code>nixos-unstable</code> channel branch is the rolling release, where packages pass build tests and [[NixOS VM tests|integration tests on a VM]], and are tested from the perspective of being an operative system (this means things like the [[Xorg|X server]], [[KDE]], various servers, and lower level details like installing [[Bootloader|bootloaders]] and running the NixOS installation steps are also tested).


For standalone [[Nix]] users, <code>nixpkgs-unstable</code> channel branch is the rolling release, where packages pass only basic build tests and are upgraded continuously.


Both [[NixOS]] and [[Nix]] users can use stable channel branches (see https://status.nixos.org/ for the current channels) to receive only conservative updates for fixing critical bugs and security vulnerabilities. Stable channel branches are released bi-annually at the end of May and the end of November.


Using stable channels on NixOS is comparable to the user experience on other Linux distributions.

== Alternatives == 


Due to the fact that Nixpkgs is ''only'' a Nix expression, it is possible to extend or replace the logic with your own sources.
In fact, there are a number of extensions as well as complete replacements for Nixpkgs, see the [[Alternative Package Sets]] article.
</translate>

[[Category:Pedias]]
[[Category:Nixpkgs]]
[[Category:Nix]]
[[Category:Software]]

Updating NixOS

2025-06-12T17:39:50Z

Pigs: link to channel branches

== Introduction ==
[[NixOS]] stands out due to its declarative configuration and atomic updates, which ensure that system updates are predictable, reversible, and don’t risk breaking the setup. This approach guarantees consistency across versions, allowing any changes to be easily rolled back. NixOS also offers flexibility, multi-version support, and advanced dependency management, making it an excellent choice for developers and system administrators.

As part of this process, only repository channels are updated or removed during updates. The system '''requires an internet connection''' to download the latest changes, and users '''cannot''' directly modify the system. For optimal stability, security, and access to new features, regular updates — ideally '''once a week''' — are recommended.

== Rebuilding the system after editing configuration.nix file ==
To apply the configuration changes made in <code>/etc/nixos/configuration.nix</code> without updating the channels, [[Nixpkgs]] and package versions. This is typically used when you've edited the system configuration, and you just want to apply those changes:<syntaxhighlight lang="console">
# nixos-rebuild switch
</syntaxhighlight>

== For non-flake configurations ==

=== Updating NixOS channels ===

<syntaxhighlight lang="console">
# nix-channel --update
</syntaxhighlight>

For more information on channels, see the main [[Channel branches]] page.

=== Rebuilding the system after updating channels ===
If you want to not only apply your configuration changes but also update the packages and system environment to the latest versions available from the Nixpkgs repository. This is typically used when you want to ensure you are using the latest versions of your software and system services:<syntaxhighlight lang="console">
# nixos-rebuild switch --upgrade
</syntaxhighlight>To apply configuration changes and new package updates only '''after''' rebooting the system, use the following command instead:<syntaxhighlight lang="console">
# nixos-rebuild boot --upgrade
</syntaxhighlight>

=== Changing Nixpkgs version ===
To see what is the latest channel available, see https://channels.nixos.org<syntaxhighlight lang="console"># nix-channel --add https://channels.nixos.org/nixos-<version> nixos</syntaxhighlight>

=== Deleting old generations ===
<syntaxhighlight lang="console">
# nix-collect-garbage -d
</syntaxhighlight>

=== Example of a system update ===
<syntaxhighlight lang="console">
# nix-channel --update && nixos-rebuild switch --upgrade && reboot
</syntaxhighlight>

== For flake based configurations ==

Because [[Flakes]] do not use channels and instead rely on explicitly defined inputs, updating a configuration involves modifying the system’s <code>flake.nix</code> to reference the desired versions of inputs. For example:

{{file|flake.nix|nix|
<nowiki>
{
inputs = {
nixpkgs.url = "github:nixos/nixpkgs/nixos-25.05"; # update version
...
};
...
}
</nowiki>
}}

Once the input URLs have been updated, refresh the flake lockfile with:

<syntaxhighlight lang="console">
# nix flake update
</syntaxhighlight>

Finally, rebuild the system configuration to apply the changes:

<syntaxhighlight lang="console">
# nixos-rebuild switch
</syntaxhighlight>

== Tips and tricks ==

=== Limiting the maximum number of running jobs ===

Sometimes, the update process may hang when the system CPU has a high number of cores. You can limit the maximum number of running jobs:

<syntaxhighlight lang="console">
# nixos-rebuild switch --option max-jobs 8
</syntaxhighlight>To make the change permanent, add the following to your configuration.nix:<syntaxhighlight lang="nix">
nix = {
settings = {
max-jobs = 8;
};
};
</syntaxhighlight>

[[Category:NixOS]]

NixOS

2025-06-12T17:37:19Z

Pigs: /* Channels */ An overview of channels should not have in-depth usage information, moving to channel branches

{{Expansion|Incomplete (reason: it needs to be an easy introduction, because its one of the first articles new users read here. Thats why it needs to be simplified a bit and more complex topics should be moved to other articles))}}

[https://nixos.org/ NixOS] is a Linux distribution based on the [[Nix]] package manager and build system. It supports [https://en.wikipedia.org/wiki/Declarative_programming declarative] system-wide [https://en.wikipedia.org/wiki/Configuration_management configuration management] as well as [https://en.wikipedia.org/wiki/Atomicity_(database_systems) atomic] upgrades and rollbacks, although it can additionally support [https://en.wikipedia.org/wiki/Imperative_programming imperative] package and user management. In NixOS, all components of the distribution — including the [https://en.wikipedia.org/wiki/Linux_kernel kernel], installed [https://en.wikipedia.org/wiki/Package_manager packages] and system configuration files — are built by [[Nix]] from [[Wikipedia:Pure function|pure functions]] called [[Nix Expression Language|Nix expressions]].

Since Nix uses [https://en.wikipedia.org/wiki/Executable binary] caching, this provides a unique compromise between the binary-oriented approach used by distributions such as Debian and the [https://en.wikipedia.org/wiki/Source_code source]-oriented approach used by distributions such as Gentoo. Binaries can be used for standard components, and custom-built packages and modules can be used automatically when a pre-built binary is not available.

Stable NixOS releases are delivered twice a year (around the end of May and the end of November). NixOS was created by [https://edolstra.github.io/ Eelco Dolstra] and [https://en.wikipedia.org/wiki/Armijn_Hemel Armijn Hemel], and initially released in 2003. It is community developed and maintained under the stewardship of the [[Nix_Community#NixOS_Foundation|NixOS Foundation]].

== Installation ==

For a full installation guide, see the [https://nixos.org/nixos/manual/index.html#ch-installation Installation chapter of the NixOS manual]. This wiki also includes alternative or supplemental guides, such as [[NixOS as a desktop]].

Most users will install NixOS via [https://nixos.org/download/#nixos-iso one of the ISO images.] Both "graphical" and "minimal" ISO variants are available for each supported architecture; the "graphical" images are suitable for users intending to install a desktop environment, and the "minimal" images are suitable for users intending to install NixOS in a server role or desiring a smaller ISO image. The ISO images are hybrid images which can be burnt to optical media or copied raw to a USB drive and booted as-is. See the installation guide for details.

In addition to the ISO images, the [https://nixos.org/download/#nixos-iso download page] provides a number of alternative methods for installing NixOS. These include:

* Virtual appliances in OVA format (compatible with VirtualBox);
* Amazon EC2 AMIs;

Additionally, many existing Linux installations can be converted into NixOS installations using [https://github.com/elitak/nixos-infect nixos-infect] or [https://github.com/jeaye/nixos-in-place nixos-in-place]; this is particularly useful for installing NixOS on hosting providers which do not natively support NixOS.

For information on installing NixOS on various ARM devices, see [[NixOS on ARM]].

== Usage ==

=== Declarative Configuration ===

One of NixOS's defining features is its declarative configuration model, where the entire system state — including installed packages, system services, and settings — is described in configuration files. The primary file is typically located at <code>/etc/nixos/configuration.nix</code>.

Changes to the configuration are applied atomically using <code>nixos-rebuild switch</code>, ensuring reproducibility and the ability to roll back to previous states. Most users track their configuration files in a version control system, enabling consistent and portable system setups. These shortcomings are often rectified after-the-fact if at all by configuration management solutions such as Puppet, Ansible or Chef. These tools reconcile system configuration with a description of the expected state. However, these tools are not integrated into the operating system design and are simply layered on top, and OS configuration may still vary where an aspect of OS configuration has not been specified in the description of expected state.

Unlike conventional distributions, where system configuration is often scattered across manually edited files, NixOS integrates configuration management directly into the operating system. This eliminates configuration drift and makes NixOS particularly well-suited for automated, reproducible deployments.

For more details and examples on NixOS configurations, see [[NixOS system configuration]].

=== Imperative Operations ===

While NixOS is typically configured declaratively as much as possible, these are a few domains where imperative operations are still necessary; these include user environment management and channel management.

==== User Environments ====

In addition to declarative system configuration, NixOS users can utilize Nix's imperative <code>nix-env</code> command to install packages at the user level, without changing the system state. See the [[Nix#User Environments| user environments section of the Nix article]] for more information.

==== Channels ====

In the [[Nix ecosystem]], [[Channel branches|channels]] are a mechanism for distributing collections of [[Nixpkgs|Nix packages]] and [[NixOS]] module definitions. A channel represents a curated, versioned set of package definitions and system configurations, typically corresponding to a particular release or the latest available development state.

When using channels, your system or [[User Environment|user environment]] pulls package definitions and options from a URL pointing to a specific snapshot of the Nix Packages collection (Nixpkgs) and associated NixOS modules.

For more information on using and configuring nix channels, refer to [[channel branches]].

== Internals ==

=== Comparison with traditional Linux Distributions ===

''Main Article: [[Nix vs. Linux Standard Base]]''

The main difference between NixOS and other Linux distributions is that NixOS does not follow the [https://en.wikipedia.org/wiki/Linux_Standard_Base Linux Standard Base] file system structure. On LSB-compliant systems software is stored under <code>/{,usr}/{bin,lib,share}</code> and configuration is generally stored in <code>/etc</code>. Software binaries are available in the user environment if they are placed in one of the LSB's <code>/bin</code> directories. When a program references dynamic libraries it will search for the required libraries in the LSB folders (<code>/lib</code>, <code>/usr/lib</code>).

In NixOS however <code>/lib</code> and <code>/usr/lib</code> do not exist. Instead all system libraries, binaries, kernels, firmware and configuration files are placed in the [[Nix#Nix store|Nix store]]. The files and directories in <code>/nix/store</code> are named by hashes of the information describing the built data. All of the files and directories placed in the Nix store are immutable. <code>/bin</code> and <code>/usr/bin</code> are almost absent: they contain only <code>/bin/sh</code> and <code>/usr/bin/env</code> respectively, to provide minimal compatibility with existing scripts using shebang lines. User-level environments are implemented using a large number of symbolic links to all required packages and auxiliary files. These environments are called [[Nix#Profiles|profiles]] and are stored in <code>/nix/var/nix/profiles</code>, each user having their own profiles. Structuring the system in this way is how NixOS obtains its key advantages over conventional Linux distributions, such as atomicity and rollback support.

=== Usage of the Nix store ===

A lot of confusion for newcomers arises from the fact that configuration is stored in the read-only <code>/nix/store</code> tree along with all the installed packages. This fact makes it impossible to manually edit system configuration; all configuration changes must be performed by editing the <code>/etc/nixos/configuration.nix</code> file and executing <code>nixos-rebuild switch</code>. NixOS provides the [[NixOS_modules|module system]] for editing all required configurations. Users should first use [https://search.nixos.org/options the option search tool] to check if the option they need exists before attempting to manually add files or configuration via low-level NixOS features like activation scripts.

The system purity makes it possible to keep system configuration in a central place, without the need to edit multiple files. This configuration can be distributed or version controlled as desired. It also provides for determinism; if you provide the same inputs, the same version of Nixpkgs and the same <code>/etc/nixos/configuration.nix</code> you will get the exact same system state.

=== Modules ===

The [[NixOS modules|NixOS module system]] as defined in [[Nixpkgs]] provides the means necessary to customize the configuration of the OS. It is used to enable and customize services such as nginx, enable firmware and customize the kernel.

All module configuration is generally performed by adding options to <code>/etc/nixos/configuration.nix</code>. Most of the examples in the wiki show how this file can be used to configure the OS.

The NixOS module system implements a typing system which allows typechecking of option settings. It also enables options defined in multiple places to be merged automatically. This allows you to spread your configuration over multiple files, and the options you set across all of those files will be merged together:

{{file|/etc/nixos/configuration.nix|nix|<nowiki>
{
imports = [
./basic-webserver.nix
./blog.nix
];
}
</nowiki>}}
{{file|/etc/nixos/basic-webserver.nix|nix|<nowiki>
{
services.nginx.enable = true;
services.nginx.virtualHosts."example.com" = {
root = "/var/www/example.com";
};
}
</nowiki>}}
{{file|/etc/nixos/blog.nix|nix|<nowiki>
{
services.nginx.virtualHosts."blog.example.com" = {
root = "/var/www/blog.example.com";
};
}
</nowiki>}}

See the [https://nixos.org/nixos/manual/index.html#sec-writing-modules Modules section of the NixOS Manual] for more details.

=== Generations ===

Every time the system state is rebuilt using <code>nixos-rebuild switch</code>, a new generation is created. You can revert to the previous generation at any time, which is useful if a configuration change (or system update) turns out to be detrimental.

You can roll back via:

<syntaxHighlight lang=shell>
$ nix-env --rollback # roll back a user environment
$ nixos-rebuild switch --rollback # roll back a system environment
</syntaxHighlight>

NixOS also places entries for previous generations in the bootloader menu, so as a last resort you can always revert to a previous configuration by rebooting. To set the currently booted generation as the default run

<syntaxHighlight lang=shell>
$ /run/current-system/bin/switch-to-configuration boot
</syntaxHighlight>

Because NixOS keeps previous generations of system state available in case rollback is desired, old package versions aren't deleted from your system immediately after an update. You can delete old generations manually:

<syntaxHighlight lang=shell>
# delete generations older than 30 days
$ nix-collect-garbage --delete-older-than 30d

# delete ALL previous generations - you can no longer rollback after running this
$ nix-collect-garbage -d
</syntaxHighlight>

List generations:
<syntaxHighlight lang=shell>
# as root
$ nix-env --list-generations --profile /nix/var/nix/profiles/system
</syntaxHighlight>

Switch generations:
<syntaxHighlight lang=shell>
# as root switch to generation 204
$ nix-env --profile /nix/var/nix/profiles/system --switch-generation 204
</syntaxHighlight>

delete broken generation(s):
<syntaxHighlight lang=shell>
# as root delete broken generations 205 and 206
$ nix-env --profile /nix/var/nix/profiles/system --delete-generations 205 206
</syntaxHighlight>

You can configure automatic garbage collection by setting the [https://search.nixos.org/options?query=nix.gc nix.gc] options in <code>/etc/nixos/configuration.nix</code>. This is recommended, as it keeps the size of the Nix store down.

== See also ==

* [[NixOS modules]], a library for modular [[Overview of the Nix Expression Language#Expressions|Nix expressions]] which powers [[#Declarative Configuration|the declarative configuration of NixOS]].
* [[NixOS VM tests]], a library for creating reproducible infrastructure tests, based on [[Nixpkgs]], [[NixOS]], QEMU and Perl.
* [https://github.com/ryan4yin/nixos-and-flakes-book NixOS & Flakes Book] (Ryan4yin, 2023) - 🛠️ ❤️ An unofficial NixOS & Flakes book for beginners.

[[Category:Pedias]]
[[Category:NixOS]]
[[Category:Nix]]

Channel branches

2025-06-12T17:33:05Z

Pigs: Reword and reorganize page, add section on flakes and usage in nixos

Nix channels provide a structured and reliable way to access tested, verified package collections and [[NixOS]] configurations from the [[Nixpkgs]] repository. Rather than installing packages or building systems directly from the frequently updated <code>master</code> branch of Nixpkgs, which receives new commits before extensive testing. Because of this, users typically follow channel branches.

A channel branch is a curated, tested snapshot of Nixpkgs, made available via [https://channels.nixos.org channels.nixos.org]. These branches only advance after builds and tests for a given commit have successfully passed on the [[Hydra]] continuous integration system.

Each channel branch follows a corresponding development branch to which new commits are first added. These new commits are then "verified" using the [[Hydra]] continuous integration system, where each channel branch corresponds to building any new or updated packages for that branch and perform the associated tests. A channel branch is updated once its builds succeeds for a new commit. Contrary to users of the development branches, channel branch users will benefit from both "verified" commits and pre-built packages from the [https://cache.nixos.org official public binary cache].

== The official channels ==

There are several types of channel branches, each with its own use case and verification phase. Channels can be broadly categorized into ''stable'' and ''unstable'' channels, and ''large'' and ''small'' channels. To view the current official channels, see the [https://status.nixos.org channel status webpage].

* Stable vs unstable:
** '''Stable channels''' (e.g. <code>nixos-25.05</code>) only provide conservative updates for fixing bugs and security vulnerabilities, but do not receive major updates after the initial release. New stable channels are released every six months.
** '''Unstable channels''' (e.g. <code>nixos-unstable</code>, <code>nixpkgs-unstable</code>) follow the <code>master</code> branch of Nixpkgs, delivering the latest tested updates on a rolling basis.

* Large vs small:
** '''Large channels''' (e.g. <code>nixos-25.05</code>, <code>nixos-unstable</code>) are updated only after Hydra has finished building the full breadth of Nixpkgs.
** '''Small channels''' (e.g. <code>nixos-25.05-small</code>, <code>nixos-unstable-small</code>) are identical to large channels, but are updated as soon as Hydra has finished building a defined set of commonly-used packages. Thus, users following these channels will get faster updates but may need to build any packages they use from outside the defined set themselves. These channels are intended to be used for server setups, for example.

For most users, a stable/large channel is recommended.

== The nix-channel command ==

Nix channels are maintained separately for each user account, including the root user. Each user, including root, has their own list of subscribed channels and local copies of those channel definitions. In NixOS, the channels configured for root control system-level operations such as nixos-rebuild, while channels for other users only affect their personal environments and package installations through tools like nix-env or nix-shell. If you wish to change the channel used by the system-level configuration (<code>/etc/nixos/configuration.nix</code>), ensure you run the correct <code>nix-channel</code> command as root:

{| class="wikitable"
|+ Common nix-channel commands
|-
|Listing current channels
|<code>nix-channel --list</code>
|-
| Adding a primary channel
|<code><nowiki>nix-channel --add https://nixos.org/channels/channel-name nixos</nowiki></code>
|-
| Adding other channels
|<code><nowiki>nix-channel --add https://some.channel/url my-alias</nowiki></code>
|-
| Remove a channel
|<code>nix-channel --remove channel-alias</code>
|-
| Updating a channel
|<code>nix-channel --update channel-alias</code>
|-
| Updating all channels
|<code>nix-channel --update</code>
|-
| Rollback the last update (useful if the last update breaks the <code>nixos-rebuild</code>)
|<code>nix-channel --rollback</code>
|}

== Channel usage in NixOS ==

Note that updating channels won't cause a rebuild in itself; if you want to update channels and rebuild, you can run <code>nixos-rebuild --upgrade switch</code> to do both in one step. See [[Updating NixOS]] for more in-depth information on changing/updating channels in NixOS.

== Using channel branches with flakes ==

Although [[Flakes]] do not make use of traditional Nix channels, they can still reference the same channel branches by specifying them in the flake’s inputs. These branches, such as <code>nixos-25.05</code> or <code>nixos-unstable</code>, correspond to named references within the Nixpkgs repository and serve a similar role in selecting which version of Nixpkgs or other inputs to use.

A simple example of defining channel branches in a flake:

{{file|flake.nix|nix|<nowiki>
{
inputs = {
nixpkgs.url = "github:nixos/nixpkgs/nixos-25.05";
nixpkgs-unstable.url = "github:nixos/nixpkgs/nixos-unstable";
};
...
}
</nowiki>}}

In this way, flakes offer fine-grained, declarative control over which versions of inputs are used, while no longer depending on the global Nix channel system.

== Internal channel update process ==

This section details the inner workings of how channels get generated from the Nixpkgs repository into channel branches. The channel update process begins when anyone with commit access pushes changes to either <code>master</code> or one of the <code>release-XX.XX</code> branches.

=== Hydra Build ===

Then, for each '''unstable''' channel (see above), a particular job at [https://hydra.nixos.org hydra.nixos.org] is started which must succeed:

* For NixOS: the [http://hydra.nixos.org/job/nixos/trunk-combined/tested trunk-combined/tested] job, which includes some automated NixOS tests.
* For nixos-small: the [http://hydra.nixos.org/job/nixos/unstable-small/tested unstable-small/tested] job.
* For nixpkgs: the [http://hydra.nixos.org/job/nixpkgs/trunk/unstable trunk/unstable] job, which contains some critical release packages.

=== Success Conditions ===

For a channel update to succeed, two conditions need to be satisfied:

* Particular jobset evaluation needs to be completely built ie. no more queued jobs, even if some jobs may fail
* Particular jobset evaluation's tested/unstable job needs to be built succesfully

The nixos.org server has a cronjob for which [https://github.com/nixOS/nixos-channel-scripts nixos-channel-scripts] are executed and poll for the newest jobset that satisfies the above two conditions and trigger a channel update.

=== Channel Update ===

Once the job succeeds at a particular nixpkgs commit, cache.nixos.org will download binaries from [https://hydra.nixos.org hydra.nixos.org]. When the download completes, the channel updates.

For the <code>NixOS</code> channel command-not-found index is generated, which can take some time since it has to fetch all packages. <code>nixpkgs</code> is quickly updated since none of the above needs to happen once a channel update is triggered.

Updates for the -unstable channels typically take a few days after commits land in the master branch.

To find out when a channel was last updated, check [https://status.nixos.org/ https://status.nixos.org/]. The progress of a particular pull request can be tracked via the (third-party) [https://nixpk.gs/pr-tracker.html Nixpkgs Pull Request Tracker].

=== Check build status ===
[https://github.com/nix-community/hydra-check hydra-check]
<syntaxhighlight lang="sh">
$ hydra-check --channel unstable bash
Build Status for nixpkgs.bash.x86_64-linux on unstable
✔ bash-4.4-p23 from 2021-05-23 - https://hydra.nixos.org/build/143785213
</syntaxhighlight>
also useful for finding build logs

== Tips and tricks ==

=== When unstable lags behind master ===

As https://status.nixos.org shows, a downside of nixos-unstable is that when the channel is blocked due to hydra failures, other (security) fixes will also not get in. While of course we try to keep hydra green, it is expected that this happens every once in a while. When you want to upgrade or downgrade a single package while leaving the rest of your system on nixos-unstable, you could use [[User:Raboof#using_a_fork_of_a_packaged_project|this approach]].

== See also ==

* [[Updating NixOS]] - For changing branches in NixOS
* [[Binary Cache]]
* [https://nix.dev/concepts/faq#which-channel-branch-should-i-use nix.dev] FAQ: Which channel branch should I use?
* [https://samuel.dionne-riel.com/blog/2024/05/07/its-not-flakes-vs-channels.html It's not about “Flakes vs. Channels”] by samueldr

[[Category:Nix]]
[[Category:NixOS]]
[[Category:Hydra]]
[[Category:Software]]

GNOME

2025-06-12T16:32:06Z

Pigs: /* Tips and tricks */ add back Excluding Gnome Applications section, under tips and tricks with a more minimal definition

[[{{PAGENAME}}]] (/(ɡ)noʊm/) is a [[:Category:Desktop environment|desktop environment]] for both [[Wayland]] and [[Xorg]] that seeks to be "an independent computing platform for everyone."<ref>Official GNOME Project one-liner https://www.gnome.org/ </ref>

This article is an extension of the documentation in the [https://nixos.org/manual/nixos/stable/#chap-gnome NixOS manual].

== Installation ==

=== GNOME desktop ===
To use the GNOME desktop environment on NixOS, the following configuration options must be set:

{{file|/etc/nixos/configuration.nix|nix|<nowiki>
{
# Pre 25.11
services.xserver.enable = true;
services.xserver.displayManager.gdm.enable = true;
services.xserver.desktopManager.gnome.enable = true;

# As of 25.11
services.displayManager.gdm.enable = true;
services.desktopManager.gnome.enable = true;
}
</nowiki>}}

Despite the options in NixOS versions before 25.11 being under the <code>xserver</code> namespace, GNOME runs offers [[Wayland]] by default. 25.11 and later versions remove support for the [[Xorg]] session entirely (though Xwayland is still included and supported for compatibility).

=== GNOME extensions ===
GNOME offers support for changing/overhauling the user interface (GNOME Shell) through the use of ''[https://extensions.gnome.org/about/ Extensions].'' Extensions are bundles of third-party [https://gjs.guide/extensions/ GJS] modules that are loaded while GNOME is running to augment the user experience. A repository of GNOME extensions can be found on GNOME's official [https://extensions.gnome.org/ webpage] and can be installed imperatively if needed by unpacking the extension in <code>~/.local/share/gnome-shell/extensions</code> directory. Extensions can only be activated if it supports the GNOME release that it's installed alongside with.

However, Nix automatically packages all available GNOME extensions under the <code>pkgs.gnomeExtensions</code> attribute. Extensions which require additional dependencies are then manually packaged if needed. Installed extensions can be enabled graphically through the built-in "Extensions" application or through the <code>gnome-extensions</code> command line interface.

{{file|3={
environment.systemPackages = with pkgs; [
gnomeExtensions.blur-my-shell
gnomeExtensions.just-perfection
gnomeExtensions.arc-menu
];
}|name=/etc/nixos/configuration.nix|lang=nix}}
== Configuration ==

=== dconf ===

Dconf is a low-level configuration system for storing and loading configurations. The dconf database is stored in a single binary file in <code>~/.config/dconf/user</code> and contains all known configuration values for all applications and programs that use dconf (GNOME applications and shell, gtk, etc).

For example, the setting which controls the accent color of GNOME shell is located in the ''schema'' labeled <code>/org/gnome/desktop/interface/</code> which contains the ''key'' <code>accent-color</code> which accepts a GVariant ''value'' of type <code>enum</code> (one of <code>'blue'</code>, <code>'teal'</code>, <code>'green'</code>, etc)

NixOS and Home Manager both provide an interface for declarative configuration of dconf settings exposed in <code>programs.dconf</code> and <code>dconf</code> modules respectively. This option accepts an attribute set whose names are schemas whose paired value is another attribute set whose names are keys and paired values as GVariant values.

Going back to the previous example, to set the accent color of GNOME in a declarative manner in NixOS as well as mapping the keyboard's "caps lock" key to "ctrl" you would write:

{{file|3={
programs.dconf.profiles.user.databases = [
{
lockAll = true; # prevents overriding
settings = {
"org/gnome/desktop/interface" = {
accent-color = "blue";
};
"org/gnome/desktop/input-sources" = {
xkb-options = [ "ctrl:nocaps" ];
};
};
}
];
}|name=/etc/nixos/configuration.nix|lang=nix}}

And the equivalent snippet in Home Manager:

{{file|3={
dconf.enable = true;
dconf.settings = {
"org/gnome/desktop/interface" = {
accent-color = "blue";
};
"org/gnome/desktop/input-sources" = {
xkb-options = [ "ctrl:nocaps" ];
};
};
}|name=~/.config/home-manager/home.nix|lang=nix}}

{{Note|Schemas in Nix are written without leading and trailing slashes. In addition, since dconf have more data types than the Nix language (for example, tuples), in some cases you'll need to convert Nix value to a GVariant value. You can achieve that by using function defined in <code>lib.gvariant</code>, they're documented [https://nixos.org/manual/nixpkgs/stable/#sec-functions-library-gvariant here].}}

==== Extensions ====
Extensions are not activated by default when installed with Nix but can be configured to do so using the respective dconf modules. The schema is <code>/org/gnome/shell/</code> with the key <code>enabled-extensions</code> which accepts a list of strings that represent extension UUIDs. If the extension was installed with Nix, then the UUID can be accessed by the <code>extensionUuid</code> attribute of the extension itself. Each extension's configuration can then be found under their corresponding schema in <code>/org/gnome/shell/extensions/</code> and be configured as needed.

For example, in Home Manager, you could write:

{{file|3={
dconf = {
enable = true;
settings = {
"org/gnome/shell" = {
disable-user-extensions = false; # enables user extensions
enabled-extensions = [
# Put UUIDs of extensions that you want to enable here.
# If the extension you want to enable is packaged in nixpkgs,
# you can easily get its UUID by accessing its extensionUuid
# field (look at the following example).
pkgs.gnomeExtensions.gsconnect.extensionUuid

# Alternatively, you can manually pass UUID as a string.
"blur-my-shell@aunetx"
# ...
];
};

# Configure individual extensions
"org/gnome/shell/extensions/blur-my-shell" = {
brightness = 0.75;
noise-amount = 0;
};
};
};
}|name=~/.config/home-manager/home.nix|lang=nix}}

== Tips and tricks ==

=== Discover dconf settings ===
If you wish to discover the corresponding dconf entry for a given setting in a program, you can run `dconf watch /` inside of a terminal and change the setting graphically. For example, when changing toggling the Quick-Settings option "Dark Style" from "on" to "off" and back to "on," this will be the output:<syntaxhighlight lang="shell-session">
$ dconf watch /
/org/gnome/desktop/interface/color-scheme
'default'

/org/gnome/desktop/interface/color-scheme
'prefer-dark'
</syntaxhighlight>Otherwise you can use the gsettings programs to inspect the schemas installed on your system. For example, to inspect all the keys contained within <code>/org/gnome/desktop/background</code> you could run:<syntaxhighlight lang="shell-session">
$ gsettings list-keys org.gnome.desktop.background
color-shading-type
picture-opacity
picture-options
picture-uri
picture-uri-dark
primary-color
secondary-color
show-desktop-icons

</syntaxhighlight>Then to see the range of possible values for one of the keys such as <code>picture-options</code> you could then run:<syntaxhighlight lang="shell-session">
$ gsettings range org.gnome.desktop.background picture-options
enum
'none'
'wallpaper'
'centered'
'scaled'
'stretched'
'zoom'
'spanned'

</syntaxhighlight>Which tells you that the ''key'' <code>picture-options</code> located in ''schema'' <code>/org/gnome/desktop/background/</code> accepts a ''value'' of type enumeration (a single string value from a set of accepted values).

=== Enable system tray icons ===
GNOME does not currently support system tray icons. However, Ubuntu has created an [https://extensions.gnome.org/extension/615/appindicator-support/ extension] that implements this in the top bar. You can install this extension with the following in NixOS:
{{File|3={
environment.systemPackages = [ pkgs.gnomeExtensions.appindicator ];
services.udev.packages = [ pkgs.gnome-settings-daemon ];
}|name=/etc/nixos/configuration.nix|lang=nix}}

=== Profiling (with sysprof) ===

Install {{ic|sysprof}} as a ''system'' package (it won't work properly if installed against users). Then enable the associated service with

<syntaxhighlight lang="nix">
services.sysprof.enable = true;
</syntaxhighlight>

=== Automatic screen rotation ===

<syntaxhighlight lang="nix">
hardware.sensor.iio.enable = true;
</syntaxhighlight>

=== Dark mode ===

Change default color theme for all GTK4 applications to dark using [[Home Manager]].

{{file|~/.config/home-manager/home.nix|nix|<nowiki>
{
dconf = {
enable = true;
settings."org/gnome/desktop/interface".color-scheme = "prefer-dark";
};
}
</nowiki>}}

=== Excluding GNOME Applications ===

To exclude certain applications that are installed by default with GNOME, set the {{nixos:option|environment.gnome.excludePackages}} module option:

{{file|/etc/nixos/configuration.nix|nix|<nowiki>
environment.gnome.excludePackages = with pkgs; [
totem
];
</nowiki>}}

== Troubleshooting ==

=== Running GConf-based applications ===

There exist very old applications which use the deprecated GConf service to store configuration. If you are running such an application and are getting an error like:

<syntaxhighlight lang="text">
GLib.GException: Failed to contact configuration server; the most common cause is a missing or misconfigured D-Bus session bus daemon. See http://projects.gnome.org/gconf/ for information
</syntaxhighlight>

you will need to add <code>pkgs.gnome2.GConf</code> to the list of dbus packages in your NixOS configuration like so:

{{File|3={
services.dbus.packages = with pkgs; [ gnome2.GConf ];
}|name=/etc/nixos/configuration.nix|lang=nix}}

After rebuilding your configuration, restart your desktop session to have GConf take effect.

=== Automatic login ===

As a potential workaround<ref>https://github.com/NixOS/nixpkgs/issues/103746#issuecomment-945091229</ref> for automatic login, include this in your NixOS configuration:

{{File|3={
services.xserver.displayManager.autoLogin.enable = true;
services.xserver.displayManager.autoLogin.user = "account";

systemd.services."getty@tty1".enable = false;
systemd.services."autovt@tty1".enable = false;
}|name=/etc/nixos/configuration.nix|lang=nix}}
:
== See also ==
* [[GNOME/Calendar]]

[[Category:Desktop environment]]
[[Category:Applications]]
[[Category:NixOS Manual]]
[[Category:GNOME]]

Biome

2025-06-10T21:14:36Z

Pigs: Add category and beginning statement

[https://github.com/biomejs/biome Biome] is a fast formatter and performant linter for [[JavaScript]], TypeScript, JSX, JSON, CSS and GraphQL.

== Troubleshooting ==

==== Issue: Biome LSP in Neovim failed on NixOS due to dynamic linking error. ====
Logged in <code>/home/incogshift/.local/state/nvim/lsp.log</code>:

<syntaxhighlight lang="log" line>
[ERROR] Could not start dynamically linked executable [...] NixOS cannot run dynamically linked executables intended for generic\nlinux environments out of the box [...]
</syntaxhighlight>

==== Fix ====

Edit: <code>~/.local/share/nvim/mason/bin/biome</code>

Look for a section like this:

<syntaxhighlight lang="javascript" line>
const PLATFORMS = {
...
darwin: {
x64: "@biomejs/cli-darwin-x64/biome",
arm64: "@biomejs/cli-darwin-arm64/biome",
},
linux: {
x64: "@biomejs/cli-linux-x64/biome",
arm64: "@biomejs/cli-linux-arm64/biome",
},
...
};
</syntaxhighlight>

Replace the architecture path of your OS with the absolute path to <code>biome</code> in your system. Find it using:

<syntaxhighlight lang="bash" line>
$ which biome
/etc/profiles/per-user/<user>/bin/biome
</syntaxhighlight>

Then update the block (assuming <code>x64</code> Linux as the platform):

<syntaxhighlight lang="javascript" line>
const PLATFORMS = {
...
darwin: {
x64: "@biomejs/cli-darwin-x64/biome",
arm64: "@biomejs/cli-darwin-arm64/biome",
},
linux: {
x64: "/etc/profiles/per-user/<user>/bin/biome",
arm64: "@biomejs/cli-linux-arm64/biome",
},
...
};
</syntaxhighlight>

Reference for similar issues: [https://stackoverflow.com/a/78215911/27134695 Stack Overflow]

[[Category:JavaScript]]

Talk:Haskell

2025-06-10T16:39:01Z

Pigs: /* flowchart replacement */ new section

"Nix recipes for Haskellers" link is currently broken (4/2/2021).

[2022/10/25] Thanks for working on this page. It is informative and has improved a lot since my last visit around a year ago. Thank you!

== ghcup ==

What about ghcup? The main installer of Haskell [[User:Turbotimon|Turbotimon]] ([[User talk:Turbotimon|talk]]) 16:05, 13 February 2025 (UTC)

:I added a section on ghcup under limitations. GHCup does not work out of the box on NixOS and the effort to get it to work is probably not worth it compared to just grabbing specific GHC versions from Nixpkgs. [[User:Pigs|Pigs]] ([[User talk:Pigs|talk]]) 16:56, 20 May 2025 (UTC)

== flowchart replacement ==

This flowchart was removed from the page. It did have many issues such as being out of date, an image that you cant update, and oversimplified,

However, with the 6 different ways documented on how to build Haskell projects, there needs to be some sort of introductory information at the top of the page that details why someone should choose one method over the other.

[[File:haskell_choice.png]] [[User:Pigs|Pigs]] ([[User talk:Pigs|talk]]) 16:39, 10 June 2025 (UTC)

1Password

2025-06-09T18:31:26Z

Pigs: /* Unlocking with System Authentication */ don't link to old wiki

[https://1password.com/ 1Password] is a password manager.

== NixOS ==

=== Installation ===

If you're using [[NixOS]], you can enable 1Password and its GUI with:
{{file|/etc/nixos/configuration.nix|nix|<nowiki>
{ config, lib, pkgs, ... }:
{
# Enable the unfree 1Password packages
nixpkgs.config.allowUnfreePredicate = pkg: builtins.elem (lib.getName pkg) [
"1password-gui"
"1password"
];
# Alternatively, you could also just allow all unfree packages
# nixpkgs.config.allowUnfree = true;

programs._1password.enable = true;
programs._1password-gui = {
enable = true;
# Certain features, including CLI integration and system authentication support,
# require enabling PolKit integration on some desktop environments (e.g. Plasma).
polkitPolicyOwners = [ "yourUsernameHere" ];
};
...
}
</nowiki>}}

=== Unlocking browser extensions ===

{{warning|1=This only works for browsers that are installed via [[NixOS]]. Browsers installed via [[Flatpak]] are not supported.}}

The 1Password app can unlock your browser extension using a special [https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Native_messaging native messaging] process. This streamlines your 1Password experience: Once you unlock 1Password from your tray icon, your browser extensions will be unlocked as well.

This is automatically configured for [[Firefox]], [[Chrome]], and [[Brave]] browsers. However, [[Vivaldi]] and other custom Chrome-based browsers may not unlock when you unlock 1Password. If you find this to be the case, the solution is to set the <code>/etc/1password/custom_allowed_browsers</code> file as follows:

* First, use <code>ps aux</code> to find the application name for the browser. For Vivaldi, this is <code>vivaldi-bin</code>
* Add that binary name to <code>/etc/1password/custom_allowed_browsers</code>:

<syntaxhighlight lang="nix">
environment.etc = {
"1password/custom_allowed_browsers" = {
text = ''
vivaldi-bin
wavebox
'';
mode = "0755";
};
};
</syntaxhighlight>

=== Unlocking with System Authentication ===

1Password allows [https://support.1password.com/system-authentication-linux/ unlocking with system authentication]. This means fingerprints or login passwords may be used in addition to the master password. This must be enabled under the Security preferences tab of 1Password as outlined in the 1Password documentation, but also requires a few other system tools to work.

For the graphical authentication prompt to work, a user [[Polkit#Authentication_agents|Polkit authentication agent]] must be started. The authentication agent may automatically be started under Gnome, KDE, or other DE at login, but may need to be explicitly enabled for other window managers.

For fingerprint unlocking to work, [[Fingerprint scanner|fingerprint scanning]] to be enabled and allowed for typical system authentication.

== Home Manager ==

{{warning|1=Non-[[NixOS]] installs [https://1password.community/discussion/comment/655813/#Comment_655813 will not link with browser extensions or system authentication] }}

=== Installation ===

Add the following to your [[Home Manager]] configuration:

<syntaxhighlight lang="nix">
home.packages = [
pkgs._1password
pkgs._1password-gui
];
</syntaxhighlight>

=== SSH key management ===

1Password [https://developer.1password.com/docs/ssh/ can manage SSH keys].

==== Configuring SSH ====

If 1Password manages your [[SSH]] keys and you use [[Home Manager]], you may also configure your <code>~/.ssh/config</code> file using Nix:

{{note|In order to start the 1Password SSH agent, you must open the 1Password settings, go to the Developer section and check the checkbox "Use the SSH agent".}}

<syntaxhighlight lang="nix">
_: let
# onePassPath = "~/Library/Group Containers/2BUA8C4S2C.com.1password/t/agent.sock";
onePassPath = "~/.1password/agent.sock";
in {
programs.ssh = {
enable = true;
extraConfig = ''
Host *
IdentityAgent ${onePassPath}
'';
};
}
</syntaxhighlight>

==== Configuring Git ====

You can enable [[Git]]'s [[SSH]] signing with [[Home Manager]]:

<syntaxhighlight lang="nix">
{
programs.git = {
enable = true;
extraConfig = {
gpg = {
format = "ssh";
};
"gpg \"ssh\"" = {
program = "${lib.getExe' pkgs._1password-gui "op-ssh-sign"}";
};
commit = {
gpgsign = true;
};

user = {
signingKey = "...";
};
};
};
}
</syntaxhighlight>

[[Category:Applications]]

Nixpkgs enhancements

2025-06-09T06:44:51Z

Pigs: mark for deletion

{{delete}}

(Under construction; please see [[Talk: Nixpkgs enhancements|Discussion]] about what should go here.)

[[Category:Nixpkgs]]

Template talk:NixOS Manual

2025-06-09T06:31:32Z

Pigs: /* {{Manual }}does not work for nixos manual */ new section

NixOS as a desktop

2025-06-09T05:49:37Z

Pigs: update flake link to new page

<languages/>
<translate>

[[NixOS]] is a versatile operating system suitable for a wide range of use cases. This page is intended for users who wish to run NixOS as their primary desktop environment, either on physical hardware or within a virtual machine. Additionally, users planning to deploy NixOS in [[NixOS friendly hosters|cloud]] environments or on specialized server infrastructure may find it helpful to begin with the concepts and practices introduced here, as they provide a useful foundation for working within the broader [[Nix ecosystem]].

== Installation == 


Refer to [[NixOS Installation Guide]] to get started. Keep in mind that, for a desktop installation, you will probably want to make sure you start with at least 30 GiB of available disk space to allow for the [[:Category:Desktop environment|desktop environments]], [[:Category:Web Browser|web browsers]], and other [[:Category:Applications|graphical applications]], that would be typical of daily use. 15 GiB might be enough for a fairly bare-bones setup.

== Managing your configuration == 


As described in the [[Overview of the NixOS Linux distribution#Declarative Configuration]], NixOS is designed to be configured declaratively. This means the entire system configuration, including installed packages, system services, kernel parameters, and user accounts is defined in configuration files, typically in <code>/etc/nixos/configuration.nix</code>. These settings can then be applied consistently and reproducibly across machines.

The process for managing your configuration is documented in the {{NixOS Manual|name=NixOS official manual|anchor=#ch-configuration}}.

=== System Configuration ===

{{main|NixOS system configuration}}

The primary configuration file, <code>/etc/nixos/configuration.nix</code>, defines system-wide settings. This includes options like enabling services, managing system users, setting hardware options, and specifying installed packages. Changes are applied with:

<syntaxhighlight lang="console">
# nixos-rebuild switch
</syntaxhighlight>

=== User configuration with Home Manager ===

For managing per-user configurations such as application preferences, command-line tools, and dotfiles, [[Home Manager]] provides a convenient, declarative approach. It allows users to define which programs should be installed and how they should be configured, without needing to include those settings in the system-wide [https://nixos.org/manual/nixos/stable/#sec-changing-config configuration.nix].

Home Manager can be used independently of the system configuration and works with both traditional setups and newer [[Flakes]]-based configurations.

=== With Flakes === 


For users looking for a more streamlined and reproducible way to manage NixOS configurations, the [[Flakes]] feature has been gaining popularity within the community. While Flakes introduce some new concepts compared to traditional workflows, many users find them a convenient and organized approach to managing system and development configurations.

Refer to [[NixOS system configuration#Defining NixOS as a flake]] for details on getting started.

== Beyond initial setup == 


Once your basic NixOS installation is complete and functional, you can further customize your system with a variety of optional configurations tailored for desktop use. For a list of recommended initial system configurations, see [[NixOS Installation Guide#NixOS configuration]].

Common configuration areas include:

==== Desktop Environments ====

Install and configure full-featured environments such as [[GNOME]], [[KDE Plasma]], or [[Xfce]].

See [[:Category:Desktop environment]] for a full list.

==== Window Managers ====

Set up lightweight or tiling window managers like [[i3]], [[Sway]], [[Hyprland]], or [[xmonad]].

See [[:Category:Window managers]] for a full list.

==== Display Managers (Login Managers) ====

Configure graphical session managers such as [[Gnome|GDM]], [[KDE|SDDM]], or [[LightDM]].

==== Audio Setup ====

Enable and configure [[:Category:Audio|audio]] systems like [[PipeWire]], [[PulseAudio]], or [[ALSA]].

==== Network Management ====

Use tools such as [[NetworkManager]] or [[systemd-networkd]] for managing [[Networking|network]] connections.

==== Bluetooth Support ====

Set up [[Bluetooth]] with blueman or other management tools.

==== Power Management ====

Configure [[laptop]] [[Power Management|battery management]], suspend, and hibernation with tools like [[Laptop#tlp|tlp]] or [[systemd]] services.

==== Printing and Scanning ====

Enable [[Cups]] for printer support and tools like Sane for [[Scanners|scanning]] devices.

== Tips and tricks == 

=== Modularizing your configuration with modules === 

{{main|NixOS system configuration#Modularizing your configuration with modules}}

== See also == 


* [[Overview of the NixOS Linux distribution]]
* [[Comparison of NixOS setups]] for a table comparing some popular choices.
* [[Configuration Collection]] for a long list within the wiki.
* [https://github.com/topics/nix-flake nix-flake], [https://github.com/topics/nixos-configuration nixos-configuration], [https://github.com/topics/nixos-dotfiles nixos-dotfiles] Github topics
* [[Wil T Nix Guides]] Youtube video format guide

[[Category:Desktop]]
[[Category:Guide]]
[[Category:NixOS]]
</translate>

NixOS as a desktop

2025-06-09T05:16:20Z

Pigs: /* System Configuration */ add link to system configuration

<languages/>
<translate>

[[NixOS]] is a versatile operating system suitable for a wide range of use cases. This page is intended for users who wish to run NixOS as their primary desktop environment, either on physical hardware or within a virtual machine. Additionally, users planning to deploy NixOS in [[NixOS friendly hosters|cloud]] environments or on specialized server infrastructure may find it helpful to begin with the concepts and practices introduced here, as they provide a useful foundation for working within the broader [[Nix ecosystem]].

== Installation == 


Refer to [[NixOS Installation Guide]] to get started. Keep in mind that, for a desktop installation, you will probably want to make sure you start with at least 30 GiB of available disk space to allow for the [[:Category:Desktop environment|desktop environments]], [[:Category:Web Browser|web browsers]], and other [[:Category:Applications|graphical applications]], that would be typical of daily use. 15 GiB might be enough for a fairly bare-bones setup.

== Managing your configuration == 


As described in the [[Overview of the NixOS Linux distribution#Declarative Configuration]], NixOS is designed to be configured declaratively. This means the entire system configuration, including installed packages, system services, kernel parameters, and user accounts is defined in configuration files, typically in <code>/etc/nixos/configuration.nix</code>. These settings can then be applied consistently and reproducibly across machines.

The process for managing your configuration is documented in the {{NixOS Manual|name=NixOS official manual|anchor=#ch-configuration}}.

=== System Configuration ===

{{main|NixOS system configuration}}

The primary configuration file, <code>/etc/nixos/configuration.nix</code>, defines system-wide settings. This includes options like enabling services, managing system users, setting hardware options, and specifying installed packages. Changes are applied with:

<syntaxhighlight lang="console">
# nixos-rebuild switch
</syntaxhighlight>

=== User configuration with Home Manager ===

For managing per-user configurations such as application preferences, command-line tools, and dotfiles, [[Home Manager]] provides a convenient, declarative approach. It allows users to define which programs should be installed and how they should be configured, without needing to include those settings in the system-wide [https://nixos.org/manual/nixos/stable/#sec-changing-config configuration.nix].

Home Manager can be used independently of the system configuration and works with both traditional setups and newer [[Flakes]]-based configurations.

=== With Flakes === 


For users looking for a more streamlined and reproducible way to manage NixOS configurations, the [[Flakes]] feature has been gaining popularity within the community. While Flakes introduce some new concepts compared to traditional workflows, many users find them a convenient and organized approach to managing system and development configurations.

Refer to [[Flakes#NixOS configuration with flakes]] for details on getting started.

== Beyond initial setup == 


Once your basic NixOS installation is complete and functional, you can further customize your system with a variety of optional configurations tailored for desktop use. For a list of recommended initial system configurations, see [[NixOS Installation Guide#NixOS configuration]].

Common configuration areas include:

==== Desktop Environments ====

Install and configure full-featured environments such as [[GNOME]], [[KDE Plasma]], or [[Xfce]].

See [[:Category:Desktop environment]] for a full list.

==== Window Managers ====

Set up lightweight or tiling window managers like [[i3]], [[Sway]], [[Hyprland]], or [[xmonad]].

See [[:Category:Window managers]] for a full list.

==== Display Managers (Login Managers) ====

Configure graphical session managers such as [[Gnome|GDM]], [[KDE|SDDM]], or [[LightDM]].

==== Audio Setup ====

Enable and configure [[:Category:Audio|audio]] systems like [[PipeWire]], [[PulseAudio]], or [[ALSA]].

==== Network Management ====

Use tools such as [[NetworkManager]] or [[systemd-networkd]] for managing [[Networking|network]] connections.

==== Bluetooth Support ====

Set up [[Bluetooth]] with blueman or other management tools.

==== Power Management ====

Configure [[laptop]] [[Power Management|battery management]], suspend, and hibernation with tools like [[Laptop#tlp|tlp]] or [[systemd]] services.

==== Printing and Scanning ====

Enable [[Cups]] for printer support and tools like Sane for [[Scanners|scanning]] devices.

== Tips and tricks == 

=== Modularizing your configuration with modules === 

{{main|NixOS system configuration#Modularizing your configuration with modules}}

== See also == 


* [[Overview of the NixOS Linux distribution]]
* [[Comparison of NixOS setups]] for a table comparing some popular choices.
* [[Configuration Collection]] for a long list within the wiki.
* [https://github.com/topics/nix-flake nix-flake], [https://github.com/topics/nixos-configuration nixos-configuration], [https://github.com/topics/nixos-dotfiles nixos-dotfiles] Github topics
* [[Wil T Nix Guides]] Youtube video format guide

[[Category:Desktop]]
[[Category:Guide]]
[[Category:NixOS]]
</translate>

NixOS Installation Guide

2025-06-09T05:10:52Z

Pigs: /* NixOS configuration */ add links to other pages

<languages/>
<translate>

This guide serves as a companion guide for the [https://nixos.org/nixos/manual/index.html#ch-installation official manual]. It describes installation of [[NixOS]] as a complete operating system. For instructions on installing [[Nix]] within an existing operating system, refer to the [[Nix Installation Guide]].


In addition to covering the steps from the official manual, it provides known good instructions for common use cases. When there is a discrepancy between the manual and this guide, the supported case is the one described in the manual.

== Installation target == 


NixOS can be installed on an increasing variety of hardware:


* regular (Intel or AMD) desktop computers, laptops or physically accessible servers, covered on this page
* SBCs (like the Raspberry Pis) and other ARM boards, see [[NixOS on ARM]]
* cloud and remote servers, see [[NixOS friendly hosters]]

== Installation method == 


NixOS, as with most Linux-based operating systems, can be installed in different ways.


# The classic way, booting from the installation media. (Described below.)
# [[Installing from Linux|Booting the media from an existing Linux installation]]

== Making the installation media == 


Since NixOS 14.11 the installer ISO is hybrid. This means it is bootable on both CD and USB drives. It also boots on EFI systems, like most modern motherboards and apple systems. The following instructions will assume the standard way of copying the image to a USB drive. When using a CD or DVD, the usual methods to burn to disk should work with the iso.

=== "Burning" to USB drive === 


First, download a [https://nixos.org/download.html#nixos-iso NixOS ISO image] or [[Creating a NixOS live CD|create a custom ISO]]. Then plug in a USB stick large enough to accommodate the image. Then follow the platform instructions:

==== From Linux ==== 


# Find the right device with <code>lsblk</code> or <code>fdisk -l</code>. Replace <code>/dev/sdX</code> with the proper device in the following steps.
# Copy to device: <code>cp nixos-xxx.iso /dev/sdX</code>


{{note|do not use /dev/sdX1 or partitions of the disk, use the whole disk /dev/sdX.}}


Writing the disk image with <code>dd if=nixos.iso of=/dev/sdX bs=4M status=progress conv=fdatasync</code> also works.

==== From macOS ==== 


# Find the right device with <code>diskutil list</code>, let's say <code>diskX</code>.
# Unmount with <code>diskutil unmountDisk diskX</code>.
# Burn with: <code>sudo dd if=path_to_nixos.iso of=/dev/diskX</code>


{{tip|Using <code>rdiskX</code> instead of <code>diskX</code> can makes a large speed difference. You can check the write speed with <code>iostat 2</code> in another terminal.}}

==== From Windows ==== 


# Download [http://sourceforge.net/projects/usbwriter/ USBwriter].
# Start USBwriter.
# Choose the downloaded ISO as 'Source'
# Choose the USB drive as 'Target'
# Click 'Write'
# When USBwriter has finished writing, safely unplug the USB drive.

=== Alternative installation media instructions === 


The previous methods are the supported methods of making the USB installation media.


Those methods are also documented, they can allow using the USB drive to boot multiple distributions. This is not supported, your mileage may vary.


* [[NixOS_Installation_Guide/Unetbootin|Using Unetbootin]]
* [[NixOS_Installation_Guide/Manual USB Creation|Manual USB Creation]]
* [[NixOS_Installation_Guide/multibootusb|multibootusb]]


== Booting the installation media ==
{{expansion|Troubleshooting steps, and details are lacking.}}


The installation media is hybrid and is capable of booting in both legacy BIOS mode and [[UEFI]] mode.


Whatever mode is used to boot the installation media, your motherboard or computer's configuration may need to be changed to allow booting from a Optical Disk Drive (for CD/DVD) or an external USB drive.

=== Legacy bios boot === 


This is the only boot possible on machines lacking EFI/UEFI.

=== UEFI boot === 


The EFI bootloader of the installation media is not signed and is not using a signed shim to boot. This means that Secure Boot will need to be disabled to boot.

== Connecting to the internet == 


The installation will '''definitely''' need a working internet connection. It is possible to install without one, but the available set of packages is limited.

=== Wired === 


For network interfaces supported by the kernel, DHCP resolution should already have happened once the shell is available.

==Tethered (Internet Sharing)== 


If you can not connect to the internet via cable or wifi, you may use smartphone's tethering capability to share internet. Depending on your smartphones capabilities, only stock kernel drivers may be required which can help providing a working network connection.

=== Wireless === 


[[NetworkManager]] is installed on the graphical ISO, meaning that it is possible to use <code>nmtui</code> on the command line to connect to a network.


Using the "Applications" tab at top
left or the launcher bar at bottom, choose a terminal application and from there launch <code>nmtui</code>. This will allow you to 'activate' a (wireless) connection - your local SSIDs should be visible in the list, else you can add a new connection. When the wireless connection is active and you have tested it, it is likely the install app which launched on startup has not detected the new connection. Close down the install app, and reopen it from the launcher bar at the bottom of the screen. This should then find the new connection and proceed.


On the minimal ISO, or if you are more familiar with [[wpa_supplicant]] then you can also run <code>wpa_passphrase ESSID | sudo tee /etc/wpa_supplicant.conf</code>, then enter your password and <code>systemctl restart wpa_supplicant</code>.

== Partitioning == 


To partition the persistent storage run <code>sudo fdisk /dev/diskX</code> and follow instructions for MBR or (U)EFI. To determine which mode you are booted into, run:

<syntaxhighlight lang="console">
$ [ -d /sys/firmware/efi/efivars ] && echo "UEFI" || echo "Legacy"
</syntaxhighlight>

A very simple example setup is given here.

=== Legacy Boot (MBR) === 


* o (dos disk label)
* n new
* p primary (4 primary in total)
* 1 (partition number [1/4])
* 2048 first sector (alignment for performance)
* +500M last sector (boot sector size)
* rm signature (Y), if ex. => warning of overwriting existing system, could use wipefs
* n
* p
* 2
* default (fill up partition)
* default (fill up partition)
* w (write)

=== UEFI === 


* g (gpt disk label)
* n
* 1 (partition number [1/128])
* 2048 first sector
* +500M last sector (boot sector size)
* t
* 1 (EFI System)
* n
* 2
* default (fill up partition)
* default (fill up partition)
* w (write)

=== Format partitions === 


The example below uses the [[ext4]] filesystem format. If you wish to use other filesystem formats such as [[Btrfs]] or [[ZFS]]:

* [[Bcachefs#NixOS installation on bcachefs]]
* [[Btrfs#Installation of NixOS on btrfs]]
* [[LVM#Basic Setup]]
* [[ZFS#Simple NixOS ZFS on root installation]]

This is useful for having multiple setups and makes partitions easier to handle<syntaxhighlight lang="console">
$ lsblk # lists current system block devices
# mkfs.fat -F 32 -n boot /dev/sdX1
# mkfs.ext4 /dev/sdX2 -L nixos
# mount /dev/disk/by-label/root /mnt
# mkdir -p /mnt/boot
# mount /dev/disk/by-label/boot /mnt/boot
</syntaxhighlight>


== NixOS configuration ==

NixOS is configured through a [[Overview of the NixOS Linux distribution#Declarative Configuration|declarative configuration]] file. To generate a default config file, run [[nixos-generate-config]]:

<syntaxhighlight lang="console">
# nixos-generate-config --root /mnt
# nano /mnt/etc/nixos/configuration.nix
</syntaxhighlight>

For information on working with a system configuration, see [[NixOS system configuration]]. For desktop-specific configurations, see [[NixOS as a desktop]].

Most essential changes:


* keyboard layout, ie <code>[[Keyboard Layout Customization|services.xserver.xkb.layout]]</code>
* [[networking]] (wifi), see below for fix if it breaks
* install [[:Category:Text Editor|editor]] to edit the configuration


The self-documenting NixOS options can be searched with [https://search.nixos.org/options NixOS options search].


=== Swap file ===

For additional methods of configuring swap, see [[Swap]]. The following example demonstrates how to create and enable a [[Swap#Swap file|swap file]]:

{{file|/mnt/etc/nixos/configuration.nix|nix|
<nowiki>
swapDevices = [{
device = "/var/lib/swapfile";
size = 16*1024; # 16 GB
}];
</nowiki>
}}

=== Bootloader ===

NixOS supports multiple [[Bootloader|bootloaders]] such as [[GNU GRUB]] and [[Systemd/boot]].

Sysyemd-boot is the recommended bootloader. The following example demonstrates how to enable systemd-boot in your configuration:

{{file|/mnt/etc/nixos/configuration.nix|nix|
<nowiki>
boot.loader.systemd-boot.enable = true;
</nowiki>
}}

You may also wish to configure [[Secure Boot]].

=== Users ===

For information on creating and managing users, see [[User management]] and the {{NixOS Manual|name=NixOS Manual: Chapter - Package Management|anchor=#sec-user-management}}. See an example below:

{{file|/mnt/etc/nixos/configuration.nix|nix|
<nowiki>
users.users.alice = {
isNormalUser = true;
initialPassword = "pw123";
};
</nowiki>
}}

== NixOS installation ==
<syntaxhighlight lang="console">
# cd /mnt
# nixos-install
</syntaxhighlight>after installation: Run <code>passwd</code> to change user password.


if internet broke/breaks, try one of the following:<syntaxhighlight lang="console">
# nixos-rebuild switch --option substitute false # no downloads
# nixos-rebuild switch --option binary-caches "" # no downloads
</syntaxhighlight>
* wpa_supplicant flags to connect to wifi


<hr />

== Additional notes for specific hardware == 


These are collected notes or links for specific hardware issues.


* Blog post how to install NixOS on a [http://grahamc.com/blog/nixos-on-dell-9560 Dell 9560]
* Brand servers may require extra kernel modules be included into initrd (<code>boot.initrd.extraKernelModules</code> in configuration.nix) For example HP Proliant needs "hpsa" module to see the disk drive.


[[Category:Guide]]
[[Category:Deployment]]
[[Category:NixOS]]
</translate>

Template talk:Nixos:package

2025-06-09T01:56:15Z

Pigs: /* Deletion candidate */ Reply

== Deletion candidate ==

Completely disagree about deleting this template.

* {{nixpkgs}} links to the github page. That is not user friendly. Someone should not have to read source code files to understand module package options and descriptions. The UI on search.nixos.org is much more user friendly.
* It is not LMGTFY as packages are not always indexed on search engines. It took me a long time as a NixOS user to learn about the existence of search.nixos.org, it should not be assumed that everyone is familiar with this service.
* This is one of the most used templates on the wiki.

If anything, in my opinion we should be encouraging {{nixos:package}} over the use of {{nixpkgs}} unless if there is a specific reason that a user would find the source code important. [[User:Pigs|Pigs]] ([[User talk:Pigs|talk]]) 05:31, 8 June 2025 (UTC)

:I ''would agree'' with you ''if'' the core of the argument was implemented properly on the search page. I '''am 100% on the same page''' that we should aim for readability and user friendliness here. But that's exactly why I don't think this template hits the mark on that front.
:<blockquote>Someone should not have to read source code files to understand module '''package options''' and descriptions.</blockquote>
:That's exactly the thing: the search functionality doesn't expose package options at all. The only way an user can learn about them is by reading the source code. Is that ideal? Of course not, but it is currently what it is.
:As for the description part, I would say in 99% of the time when this template is used, it's used either in the corresponding package's article, or in a context where adding the package description is trivial.
:For the second point, I think we should definitely be improving the main page itself to point the user to the search functionality as an option, as well as improving [[NixOS search]]. And on top of that, we probably want a [[First steps using NixOS]] page or similar to really drive this point home.
:For the third point, I don't think a package's current usage is an argument for or against its deletion (other than on technicality: we'd of course want to modify all pages using this template to point to the new one). However, do note, it's only used in [[Special:WhatLinksHere/Template:Nixos:package|24 pages]], hardly an edit burden. [[User:DoggoBit|DoggoBit]] ([[User talk:DoggoBit|talk]]) 17:10, 8 June 2025 (UTC)
::When I was writing my reply I kept mistakenly was thinking of the {{:nixos:option}} template which is much more of a useful and popular template. My mistake.
::You are right that currently linking to a package on search.nixos.org does not provide as much information as it should. (It's more on the package maintainers to provide useful descriptions (like the {{nixos:package|docker}} maintainers do) than it is of a missing feature from search.nixos.org.
::I still hold my position that linking to {{nixos:package|ghc}} is a way better user experience than linking to {{Nixpkgs Link|pkgs/development/compilers/ghc/common-hadrian.nix}} both in terms of a maintainer and as an end user.
::To me, linking to source code is a bad option when there is a friendly interface that displays all the relevant information such as '''programs provided''', '''current version''', '''outputs''', and if a user wants to, there is a link to the source code on the search result. How fast can you find that information on the Nixpkgs link? The version isn't even mentioned in the source code of the main file for GHC. [[User:Pigs|Pigs]] ([[User talk:Pigs|talk]]) 21:31, 8 June 2025 (UTC)
:::Yeah, I'm 100% with you on this, and {{tl|nixos:option}} is nowhere near being at risk of not making the cut here haha (other than a saner renaming). That template is a million times more useful than this one.
:::I'm thinking here very much from a user perspective: If I'm being served a link off the wiki, I would want it to contain ''more'' information than the wiki itself, right? Otherwise there's no point linking somewhere external in the first place. That's why I don't think this template makes sense with the current search interface at all, it's ''less useful'' than the page it's being used on. However, linking to the nixpkgs file is ''more usefu'' than the page, because the user can see the additional build options that package may have.
:::If we're talking about having ''a link'' to the corresponding Nix package entry, we could implement this via {{tl|infobox application}} (or the corresponding one) further down the line [[User:DoggoBit|DoggoBit]] ([[User talk:DoggoBit|talk]]) 21:55, 8 June 2025 (UTC)
::::But linking to search.nixos.org '''DOES''' provide more information on packages than linking to the nixpkgs source code. The search query result includes the link to the source code AND more. See my example above with the <code>ghc</code> package.
::::It is useful to the end user as it '''DOES''' include more information than what is on a wiki page, such as the current version. We wouldn't want to include information like package versions on the wiki since they can update very frequently. Would be cool to maybe auto-generate an {{:infobox application}} with the nixpkg information. I've toyed around with this idea before and have gone as so far to make a prototype mediawiki plugin that does it.
:::: 
::::Another example that I have used {{:nixos:package}} in the past has been linking to package sets. For example, {{nixos:package|haskellPackages.*}}. What am I suppose to do here? Link to the nixpkg file that contains all the haskellPackages that is so big it can't even render on github? https://github.com/NixOS/nixpkgs/blob/nixos-25.05/pkgs/development/haskell-modules/hackage-packages.nix
:::: 
::::This isn't most useful template, but it still has use cases and adds value to some wiki pages. I'm up for replacing this template with something else that contains the same information as search.nixos.org has on packages, but as I am aware that information is only able to be generated from evaluating the nix expressions in nixpkgs (which search.nixos.org does and stores it in an elasticache instance). [[User:Pigs|Pigs]] ([[User talk:Pigs|talk]]) 01:56, 9 June 2025 (UTC)

Template talk:Nixos:package

2025-06-08T21:31:12Z

Pigs: /* Deletion candidate */ Reply

Talk:Docker

2025-06-08T21:04:59Z

Pigs: /* Rootless linger */ Reply

== Rootless linger ==

I was new to using Docker rootless, and wasn't aware that systemd stops user services at logout. Docker itself doesn't provide any obvious logs that this is what stopped the container, and automatic restarts were allowed to trigger, leading to very unintuitive hard-to-debug problems, starting at random times when my login shell automatically exited. Some mention of `users.users.<name>.linger` similar to docker docs `sudo loginctl enable-linger $(whoami)` command would help those new to rootless docker tremendously. Also hi! First post on the wiki. [[User:CallumMcMahon|CallumMcMahon]] ([[User talk:CallumMcMahon|talk]]) 20:40, 8 June 2025 (UTC)

:That is a very useful note to make, thanks! Updated the page. [[User:Pigs|Pigs]] ([[User talk:Pigs|talk]]) 21:04, 8 June 2025 (UTC)

Docker

2025-06-08T21:03:53Z

Pigs: Ad note about rootless linger

<languages/>
<translate>

[https://www.docker.com/ Docker] is a platform for building, packaging, and distributing applications inside containers. Containers bundle an application's code, configurations, and dependencies into a single object that runs consistently across different computing environments. Docker works well with NixOS through the virtualization module.<ref>https://www.docker.com/resources/what-container/</ref>
</translate>

<translate>
== Installation == 
</translate>

<translate>
==== Shell ==== 
</translate>

<translate>

To temporarily use Docker in a shell environment, you can run:
</translate>
<syntaxhighlight lang="bash">
nix-shell -p docker
</syntaxhighlight>
<translate>

This will provide a shell with Docker CLI available, but note that the Docker daemon will not be running. For full functionality, you'll need a system-level installation.
</translate>

<translate>
==== System setup ==== 
</translate>

<translate>

To install Docker on NixOS, add the virtualization.docker module to your system configuration at <code>/etc/nixos/configuration.nix</code>:<ref>https://nixos.org/manual/nixos/stable/options#opt-virtualisation.docker.enable</ref>
</translate>
<syntaxhighlight lang="nix">
# In /etc/nixos/configuration.nix
virtualisation.docker = {
enable = true;
};

# Optional: Add your user to the "docker" group to run docker without sudo
users.users.<username>.extraGroups = [ "docker" ];
</syntaxhighlight>
{{Security Warning|Beware that the docker group membership is effectively [https://github.com/moby/moby/issues/9976 equivalent to being root]! Consider using [[#Rootless Docker|rootless mode]].}}

{{evaluate}}

<translate>

For a comprehensive list of configuration options, refer to the {{nixos:option|virtualisation.docker}} module options.
</translate>

<translate>
== Configuration == 
</translate>

<translate>
==== Basic ==== 
</translate>

<translate>

The basic Docker configuration on NixOS includes several options you can set in your <code>configuration.nix</code> file:
</translate>
<syntaxhighlight lang="nix">
virtualisation.docker = {
enable = true;
# Set up resource limits
daemon.settings = {
experimental = true;
default-address-pools = [
{
base = "172.30.0.0/16";
size = 24;
}
];
};
};
</syntaxhighlight>

<translate>
==== Advanced ==== 
</translate>

<translate>

For more advanced configuration, you can customize Docker daemon options and networking:
</translate>
<syntaxhighlight lang="nix">
virtualisation.docker = {
enable = true;
# Customize Docker daemon settings using the daemon.settings option
daemon.settings = {
dns = [ "1.1.1.1" "8.8.8.8" ];
log-driver = "journald";
registry-mirrors = [ "https://mirror.gcr.io" ];
storage-driver = "overlay2";
};
# Use the rootless mode - run Docker daemon as non-root user
rootless = {
enable = true;
setSocketVariable = true;
};
};
</syntaxhighlight>

<translate>
== Docker Compose == 
</translate>
<translate>

Currently, there are two options to use Docker Compose with NixOS: Arion or Compose2Nix.
</translate>

<translate>

With Arion, you can specify most Docker Compose options in Nix Syntax, and Arion will generate a <code>docker-compose.yml</code> file internally. The result is a systemd service that starts and stops the container.
</translate>

<translate>

Compose2Nix, generates all necessary configs directly from the <code>docker-compose.yml</code>, which is easier when using an already existing Docker Compose project. The result is similar to that from Arion: a systemd service is created that handles starting and stopping the container.
</translate>

<translate>
=== Arion === 
</translate>
<translate>

[https://docs.hercules-ci.com/arion/ Arion] is created for running Nix-based projects in Docker Compose. It uses the NixOS module system for configuration, it can bypass <code>docker build</code> and lets you use dockerTools or use the store directly in the containers. The images/containers can be typical dockerTools style images or full NixOS configs.
</translate>

<translate>

To use Arion, you first need to add its module to your NixOS configuration:
</translate>

<syntaxhighlight lang="nix">
modules = [ arion.nixosModules.arion ];
</syntaxhighlight>

<translate>

After that, you can access its options under
</translate>
<syntaxhighlight lang="nix">
virtualisation.arion = {}
</syntaxhighlight>

<translate>

A config for a simple container could look like this:
</translate>

<syntaxhighlight lang="nix">
virtualisation.arion = {
backend = "docker";
projects = {
"db".settings.services."db".service = {
image = "";
restart = "unless-stopped";
environment = { POSTGRESS_PASSWORD = "password"; };
};
};
};
</syntaxhighlight>

<translate>
=== Compose2Nix === 
</translate>
<translate>

With [https://github.com/aksiksi/compose2nix compose2nix] you can generate [https://search.nixos.org/options?query=virtualisation.oci-containers oci-containers] config from a <code>docker-compose.yaml</code>.
</translate>

<translate>
==== Install ==== 
</translate>
<translate>

To use <code>compose2nix</code> with <code>nix-shell</code> you can use
</translate>
<syntaxhighlight lang="bash">
nix shell github:aksiksi/compose2nix
compose2nix -h
</syntaxhighlight>
<translate>

To install <code>compose2nix</code> to NixOS, add the repo to your flake inputs
</translate>
<syntaxhighlight lang="nix">
compose2nix = {
url = "github:aksiksi/compose2nix";
inputs.nixpkgs.follows = "nixpkgs";
};
</syntaxhighlight>
<translate>

and add the package to your configuration
</translate>
<syntaxhighlight lang="nix">
environment.systemPackages = [
inputs.compose2nix.packages.x86_64-linux.default
];
</syntaxhighlight>

<translate>
==== Usage ==== 
</translate>
<translate>

After you have installed <code>compose2nix</code>, you can run <code>compose2nix</code> in the directory with your <code>docker-compose.yml</code>, which will output a <code>docker-compose.nix</code>.
</translate>

<translate>

Alternatively, you can specify the input and output files with the following flags
</translate>
<syntaxhighlight lang="bash">
compose2nix -inputs input.yml -output output.nix -runtime docker
</syntaxhighlight>
<translate>

The <code>-runtime</code> flag specifies the runtime. Here, we select <code>docker</code>. Options are <code>podman</code> and <code>docker</code>. The default is <code>podman</code>
</translate>

<translate>
== Tips and tricks == 
</translate>

<translate>
=== Docker on btrfs === 
</translate>

<translate>

If you use the [[btrfs]] file system, you might need to set the {{nixos:option|virtualisation.docker.storageDriver|storageDriver}} option:
</translate>
<syntaxhighlight lang="nix">
virtualisation.docker.storageDriver = "btrfs";
</syntaxhighlight>

<translate>
=== Rootless Docker === 
</translate>

<translate>

[https://docs.docker.com/engine/security/rootless/ Rootless Docker] lets you run the Docker daemon as a non-root user for improved security. To do so, enable {{nixos:option|virtualisation.docker.rootless}}. This activates the user-level systemd Docker service. Additionally, the option {{nixos:option|virtualisation.docker.rootless.setSocketVariable|setSocketVariable}} configures the <code>DOCKER_HOST</code> environment variable to point to the rootless Docker instance.
</translate>

<syntaxhighlight lang="nix">
virtualisation.docker = {
# Consider disabling the system wide Docker daemon
enable = false;

rootless = {
enable = true;
setSocketVariable = true;
# Optionally customize rootless Docker daemon settings
daemon.settings = {
dns = [ "1.1.1.1" "8.8.8.8" ];
registry-mirrors = [ "https://mirror.gcr.io" ];
};
};
};
</syntaxhighlight>

<translate>

A system reboot is required for these changes to take effect. Alternatively, the environment variable can be set manually in the current shell session, and the user Docker service can be started with the following commands:
</translate>

<syntaxhighlight lang="console">
$ export DOCKER_HOST=unix://$XDG_RUNTIME_DIR/docker.sock
$ systemctl --user start docker
</syntaxhighlight>

{{note|User services do not persist after logging out by default. This will cause any Docker containers to stop if a user logs out. Set option {{nixos:option|users.users.*.linger|users.users.<name>.linger}} to true for Docker containers to persist. See [[Systemd/User Services#Keeping user services running after logout]] for more details.}}

<translate>

To verify the status of the rootless Docker service:
</translate>
<syntaxhighlight lang="console">
$ systemctl --user status docker
</syntaxhighlight>

To confirm that Docker is running in rootless mode:

<syntaxhighlight lang="console">
$ docker info -f "{{println .SecurityOptions}}" | grep rootless
</syntaxhighlight>

=== Using Privileged Ports for Rootless Docker ===
Rootless containers are not able to ports from 0 to 1023 as such port can only be used by privileged users. This problem can be solved by using port forwarding.

Assume you'd like a rootless container to make use of ports 53 (DNS; TPC and UDP) and 80 (web; TCP). We may force the container to use port 8000 while the firewall is instructed for forward traffic from port 80 to 8000. Same logic applies for port 53. Refer to the following example:<syntaxhighlight lang="nixos"># Firewall
networking.firewall = {
enable = true;
allowedTCPPorts = [ 80 8000 53 5300 ];
allowedUDPPorts = [ 53 5300 ];
};

boot.kernel.sysctl = {
"net.ipv4.conf.eth0.forwarding" = 1; # enable port forwarding
};

networking = {
firewall.extraCommands = ''
iptables -A PREROUTING -t nat -i eth0 -p TCP --dport 80 -j REDIRECT --to-port 8000
iptables -A PREROUTING -t nat -i eth0 -p TCP --dport 53 -j REDIRECT --to-port 5300
iptables -A PREROUTING -t nat -i eth0 -p UDP --dport 53 -j REDIRECT --to-port 5300
'';
};</syntaxhighlight>Whilst the docker-compose.yaml might look like this:<syntaxhighlight lang="dockerfile">
services:
myserver:
image: ...
restart: always
ports:
- "5300:53/tcp"
- "5300:53/udp"
- "8000:80"
</syntaxhighlight>

<translate>

=== Creating images with Nix === 
</translate>

<translate>
==== Building a docker image with nixpkgs ==== 
</translate>
<translate>

There is an entry for [https://nixos.org/nixpkgs/manual/#sec-pkgs-dockerTools dockerTools] in the Nixpkgs manual for reference. In the linked page, they give the following example config:
</translate>

<syntaxhighlight lang="nix">
buildImage {
name = "redis";
tag = "latest";

fromImage = someBaseImage;
fromImageName = null;
fromImageTag = "latest";

copyToRoot = pkgs.buildEnv {
name = "image-root";
paths = [ pkgs.redis ];
pathsToLink = [ "/bin" ];
};

runAsRoot = ''
#!${pkgs.runtimeShell}
mkdir -p /data
'';

config = {
Cmd = [ "/bin/redis-server" ];
WorkingDir = "/data";
Volumes = { "/data" = { }; };
};

diskSize = 1024;
buildVMMemorySize = 512;
}
</syntaxhighlight>

<translate>

More examples can be found in the [https://github.com/NixOS/nixpkgs/blob/master/pkgs/build-support/docker/examples.nix nixpkgs] repo.
</translate>

<translate>

Also check out the excellent article by [https://lucabrunox.github.io/2016/04/cheap-docker-images-with-nix_15.html lethalman] about building minimal docker images with nix.
</translate>

<translate>
==== Reproducible image dates ==== 
</translate>

<translate>

The manual advises against using <code>created = "now"</code>, as that prevents images from being reproducible.
</translate>

<translate>

An alternative, if using [[flakes]], is to do <code>created = builtins.substring 0 8 self.lastModifiedDate</code>, which uses the commit date, and is therefore reproducible.
</translate>

<translate>
==== Calculating the sha256 for a pulled Docker image ==== 
</translate>

<translate>

The <code>sha256</code> argument of the <code>dockerTools.pullImage</code> function is the checksum of the archive generated by Skopeo. Since the archive contains the name and the tag of the image, Skopeo arguments used to fetch the image have to be identical to those used by the <code>dockerTools.pullImage</code> function.
</translate>

<translate>

For instance, the SHA of the following image
</translate>
<syntaxhighlight lang="nix">
pkgs.dockerTools.pullImage{
imageName = "lnl7/nix";
finalImageTag = "2.0";
imageDigest = "sha256:632268d5fd9ca87169c65353db99be8b4e2eb41833b626e09688f484222e860f";
sha256 = "1x00ks05cz89k3wc460i03iyyjr7wlr28krk7znavfy2qx5a0hfd";
};
</syntaxhighlight>

<translate>

can be manually generated with the following shell commands
</translate>

<syntaxhighlight lang="bash">
skopeo copy docker://lnl7/nix@sha256:632268d5fd9ca87169c65353db99be8b4e2eb41833b626e09688f484222e860f docker-archive:///tmp/image.tgz:lnl7/nix:2.0
</syntaxhighlight>

<syntaxhighlight lang="bash">
nix-hash --base32 --flat --type sha256 /tmp/image.tgz
</syntaxhighlight>
<syntaxhighlight lang="shell">
1x00ks05cz89k3wc460i03iyyjr7wlr28krk7znavfy2qx5a0hfd
</syntaxhighlight>

<translate>
==== Directly Using Nix in Image Layers ==== 
</translate>

<translate>

Instead of copying Nix packages into Docker image layers, Docker can be configured to directly utilize the <code>nix-store</code> by integrating with [https://github.com/pdtpartners/nix-snapshotter nix-snapshotter].
</translate>

<translate>

This will significantly reduce data duplication and the time it takes to pull images.
</translate>

<translate>
=== Using Podman as an alternative === 
</translate>

<translate>

Podman is a daemonless container engine that can run Docker containers without elevated privileges. It can be used as a drop-in replacement for Docker in many cases:
</translate>
<syntaxhighlight lang="nix">
# Enable Podman in configuration.nix
virtualisation.podman = {
enable = true;
# Create the default bridge network for podman
defaultNetwork.settings.dns_enabled = true;
};

# Optionally, create a Docker compatibility alias
programs.zsh.shellAliases = {
docker = "podman";
};
</syntaxhighlight>

<translate>
=== Changing Docker Daemon's Data Root === 
</translate>

<translate>

By default, the Docker daemon stores images, containers, and build context on the root file system. To use a different storage location, specify a new <code>data-root</code> in your configuration:
</translate>
<syntaxhighlight lang="nix">
virtualisation.docker.daemon.settings = {
data-root = "/some-place/to-store-the-docker-data";
};
</syntaxhighlight>

<translate>
=== Docker Containers as systemd Services === 
</translate>

<translate>

You can run Docker containers as systemd services using the <code>oci-containers</code> module:
</translate>
<syntaxhighlight lang="nix">
virtualisation.oci-containers = {
# backend defaults to "podman"
backend = "docker";
containers = {
foo = {
# ...
};
};
};
</syntaxhighlight>

<translate>

A more advanced example:
</translate>
<syntaxhighlight lang="nix">
{ config, pkgs, ... }:

{
config.virtualisation.oci-containers.containers = {
hackagecompare = {
image = "chrissound/hackagecomparestats-webserver:latest";
ports = ["127.0.0.1:3010:3010"];
volumes = [
"/root/hackagecompare/packageStatistics.json:/root/hackagecompare/packageStatistics.json"
];
cmd = [
"--base-url"
"\"/hackagecompare\""
];
};
};
}
</syntaxhighlight>

<translate>

See [https://search.nixos.org/options?from=0&size=50&sort=alpha_asc&query=virtualisation.oci-containers oci-containers] for further options.
</translate>

<translate>
==== Usage ==== 
</translate>
<translate>

Unless otherwise specified, NixOS uses Podman to run OCI containers. Note that these are '''user-specific''', so running commands with or without sudo can change your output.
</translate>

<translate>

List containers
</translate>
<syntaxhighlight lang="console">
# podman ps
</syntaxhighlight>
<translate>

Update image
</translate>
<syntaxhighlight lang="console">
# podman restart hackagecompare
</syntaxhighlight>
<translate>

List images
</translate>
<syntaxhighlight lang="console">
# podman ls
</syntaxhighlight>
<translate>

Remove container
</translate>
<syntaxhighlight lang="console">
# podman rm hackagecompare
</syntaxhighlight>
<translate>

Remove image
</translate>
<syntaxhighlight lang="console">
# podman rmi c0d9a5f58afe
</syntaxhighlight>
<translate>

Update image
</translate>
<syntaxhighlight lang="console">
# podman pull chrissound/hackagecomparestats-webserver:latest
</syntaxhighlight>
<translate>

Run interactive shell in running container
</translate>
<syntaxhighlight lang="console">
# podman exec -ti $ContainerId /bin/sh
</syntaxhighlight>

<translate>
===== Exposing ports from the host ===== 
</translate>
<translate>

If you have a service running on the host that you want to connect to from the container, you could try connecting to the hostname <code>host.containers.internal</code> (or <code>host.docker.internal</code> for podman), but this might require additional networking setup
</translate>

<translate>
===== Exposing sockets from the host ===== 
</translate>
<translate>

If you have a service running on the host that exposes a socket, such as mariadb, you can also expose that socket to the container instead. You'll want to expose the folder the socket is in as a volume - so:
</translate>
<syntaxhighlight lang="bash">
volumes = [
"/var/run/mysqld:/mysqld"
];
</syntaxhighlight>
<translate>

to provide access to <code>/var/run/mysqld/mysqld.sock</code>
</translate>

<translate>
=== Running the docker daemon from nix-the-package-manager - not NixOS === 
</translate>

<translate>

This is not supported. You're better off installing the docker daemon [https://docs.docker.com/engine/install/ "the normal non-nix way"].
</translate>

<translate>

See the discourse discussion: [https://discourse.nixos.org/t/how-to-run-docker-daemon-from-nix-not-nixos/43413 How to run docker daemon from nix (not NixOS)] for more.
</translate>

<translate>
== Troubleshooting == 
</translate>

<translate>
=== Cannot connect to the Docker daemon === 
</translate>

<translate>

If you encounter errors connecting to the Docker daemon, check that:
</translate>
<translate>

- The Docker service is running: <code>systemctl status docker</code>
</translate>
<translate>

- Your user is in the docker [[User management#Adding User to a group|group]]: <code>groups | grep docker</code>
</translate>
<translate>

- You've logged out and back in after adding your user to the docker group
</translate>

<translate>
=== Storage space issues === 
</translate>

<translate>

When Docker uses too much disk space:
</translate>
<syntaxhighlight lang="bash">
# Remove unused containers, networks, images, and volumes
docker system prune -a --volumes

# Configure Docker daemon to automatically prune in configuration.nix
virtualisation.docker.daemon.settings = {
pruning = {
enabled = true;
interval = "24h";
};
};
</syntaxhighlight>

<translate>
=== Network conflicts === 
</translate>

<translate>

Docker's default subnet (`172.17.0.0/16`) might conflict with your existing network. Configure a different subnet in your `configuration.nix`:
</translate>
<syntaxhighlight lang="nix">
virtualisation.docker.daemon.settings = {
default-address-pools = [
{
base = "192.168.0.0/16";
size = 24;
}
];
};
</syntaxhighlight>

<translate>
=== Cannot connect to public Wi-Fi, when using Docker === 
</translate>

<translate>

When connecting to a public Wi-Fi, where the login page's IP-Address is within the Docker network range, accessing the Internet might not be possible. This has been reported when trying to connect to the WIFIonICE of the Deutsche Bahn (DB). They use the <code>172.18.x.x</code> address range.
</translate>

<translate>

This can be resolved by changing the default address pool that Docker uses.
</translate>
<syntaxhighlight lang="nix">
virtualisation.docker = {
enable = true;
daemon.settings = {
"default-address-pools" = [
{ "base" = "172.27.0.0/16"; "size" = 24; }
];
};
};
</syntaxhighlight>
<translate>

Restarting the container or Docker might be required.
</translate>

<translate>

== References == 
</translate>

<references/>

[[Category:Applications]]
[[Category:Virtualization]]
[[Category:Cookbook]]
[[Category:Software]]
[[Category:Server]]
[[Category:Container]]

Flakes

2025-06-08T17:59:44Z

Pigs: /* NixOS configuration with flakes */ move nixos section to new page

<languages />
<translate>

'''Nix flakes''' is an [https://nixos.org/manual/nix/stable/development/experimental-features.html experimental feature] that was introduced with Nix 2.4 ([https://nixos.org/manual/nix/unstable/release-notes/rl-2.4.html see release notes]).

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

=== Enabling flakes ===

====Enable flakes temporarily==== 


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

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


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

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

====With Home Manager==== 


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

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

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

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

===Basic Usage of Flake=== 


{{Warning | Since contents of flake files are copied to the world-readable [[Nix_package_manager#Nix_store|Nix store]] folder, do not put any unencrypted secrets in flake files. You should instead use a [[Comparison of secret managing schemes|secret managing scheme]].}}


{{Note | For flakes in [[git]] repositories, 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.}}

====Generate flake.nix file==== 


To initialize a flake, run the following flake command in the project directory:

</translate>
<syntaxhighlight lang="console">
$ nix flake init
</syntaxhighlight>
<translate>

====Common structure====

The above command will provide a very simple flake file looking like:

</translate>
<syntaxHighlight lang=nix>
{
description = "A very basic flake";

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

outputs = { self, nixpkgs }: {

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

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

};
}
</syntaxHighlight>
<translate>

You will then be able to build this flake with <code>nix build</code> and run it with <code>nix run</code>

{{note|Flakes force you to specify a program for each supported architecture. To avoid this, refer to [[#Defining a flake for multiple architectures]] section of the wiki.}}

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


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

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

<syntaxhighlight lang="console">
$ nix flake show
└───packages
└───x86_64-linux
├───default: package 'hello-2.12.2'
└───hello: package 'hello-2.12.2'
</syntaxhighlight>

==== Development shells ====

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

<syntaxhighlight lang="nix">
{
description = "Example flake with a devShell";

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

outputs = { self, nixpkgs}:
let
system = "x86_64-linux";
pkgs = import nixpkgs { inherit system; };
in {
devShells.x86_64-linux.default = pkgs.mkShell {
buildInputs = with pkgs; [
hello
];
shellHook = ''
echo "Welcome to the devShell!"
'';
};
};
}
</syntaxhighlight>

To enter the development shell environment:

<syntaxhighlight lang="console">
$ nix develop
</syntaxhighlight>

{{note|You don’t need to define a devShell to enter a development shell using nix develop.
If no devShell is defined, nix develop will drop you into an environment containing the default build dependencies of the flake (if any).}}

==== Build specific attributes in a flake repository ==== 


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:

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

Likewise, you can specify an attribute with the run command: <code>nix run .#hello</code> and the develop command: <code>nix develop .#hello</code>.

== Flake schema == 


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

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

Nixpkgs can alternatively also point to an url cached by the NixOS organization:

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

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

<translate>


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:

</translate>
<code>inputs.hyprland.url = "github:hyprwm/Hyprland";</code>
<translate>


If you want to make Hyprland follow the nixpkgs input to avoid having multiple versions of nixpkgs, this can be done using the following code:

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


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

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

By default, Git submodules in package <code>src</code>'s won't get copied to the nix store, this may cause the build to fail. Flakes in Git repositories can declare that they need Git submodules to be enabled. Since Nix version [https://discourse.nixos.org/t/nix-2-27-0-released/62003 2.27], you can enable submodules by:

<syntaxhighlight lang="nix">
inputs.self.submodules = true;
</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

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


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

== Core usage patterns ==

=== Making your evaluations pure === 


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


* {{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.getEnv</code> is also impure. Avoid reading from environment variables and likewise, do not reference files outside of the flake's directory.

=== Defining a flake for multiple architectures ===

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

<syntaxhighlight lang="nix">
{
description = "A flake targeting multiple architectures";

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

outputs = { self, nixpkgs }: let
systems = [ "x86_64-linux" "aarch64-linux" ];
forAllSystems = f: builtins.listToAttrs (map (system: {
name = system;
value = f system;
}) systems);
in {
packages = forAllSystems (system: let
pkgs = nixpkgs.legacyPackages.${system};
in {
hello = pkgs.hello;
default = pkgs.hello;
});
};
}
</syntaxhighlight>

You can also use third-parties projects like [[Flake Utils|flake-utils]] or [[Flake Parts|flake-parts]] that automatically provide code to avoid this boilerplate. To avoid re-defining the program multiple times, refer to [[Flake Utils#Defining a flake for multiple architectures]]

=== Using overlays ===

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

=== Enable unfree software === 

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

<syntaxhighlight lang="nix">
{
inputs.nixpkgs.url = "github:nixos/nixpkgs?ref=nixos-unstable";
outputs = { self, nixpkgs, flake-compat }:
let
system = "x86_64-linux";
pkgs = import nixpkgs { inherit system; config.allowUnfree = true;};
in {
...
};
}
</syntaxhighlight>

== NixOS configuration with flakes ==

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

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

== Development tricks == 

=== Automatically switch nix shells with direnv === 


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

=== Pushing Flakes to Cachix === 

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

=== Flake support in projects without flakes === 


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

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

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

=== Efficiently build multiple flake outputs ===


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

=== Build a package added in a PR === 

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


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:

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


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

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

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

</translate>
<syntaxHighlight lang=bash>
cd ~/libdep-src-checkout/
nix develop # Or `nix-shell` if applicable.
export prefix="./install" # configure nix to install it here
buildPhase # build it like nix does
installPhase # install it like nix does
</syntaxHighlight>
<translate>


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

</translate>
<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>
<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.

== See also == 

=== Official sources ===


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


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


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


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

=== Guides ===


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

=== Useful flake modules ===


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

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

* [[Flake Compat|flake-compat]]: A compatibility layer for flakes


* [https://github.com/nix-community/todomvc-nix building Rust and Haskell flakes]

</translate>
[[Category:Software]]
[[Category:Nix]]
[[Category:Nix Language]]
[[Category:Flakes]]

NixOS as a desktop

2025-06-08T17:59:26Z

Pigs: Move module configuration to the system configuration page

<languages/>
<translate>

[[NixOS]] is a versatile operating system suitable for a wide range of use cases. This page is intended for users who wish to run NixOS as their primary desktop environment, either on physical hardware or within a virtual machine. Additionally, users planning to deploy NixOS in [[NixOS friendly hosters|cloud]] environments or on specialized server infrastructure may find it helpful to begin with the concepts and practices introduced here, as they provide a useful foundation for working within the broader [[Nix ecosystem]].

== Installation == 


Refer to [[NixOS Installation Guide]] to get started. Keep in mind that, for a desktop installation, you will probably want to make sure you start with at least 30 GiB of available disk space to allow for the [[:Category:Desktop environment|desktop environments]], [[:Category:Web Browser|web browsers]], and other [[:Category:Applications|graphical applications]], that would be typical of daily use. 15 GiB might be enough for a fairly bare-bones setup.

== Managing your configuration == 


As described in the [[Overview of the NixOS Linux distribution#Declarative Configuration]], NixOS is designed to be configured declaratively. This means the entire system configuration, including installed packages, system services, kernel parameters, and user accounts is defined in configuration files, typically in <code>/etc/nixos/configuration.nix</code>. These settings can then be applied consistently and reproducibly across machines.

The process for managing your configuration is documented in the {{NixOS Manual|name=NixOS official manual|anchor=#ch-configuration}}.

=== System Configuration ===

The primary configuration file, <code>/etc/nixos/configuration.nix</code>, defines system-wide settings. This includes options like enabling services, managing system users, setting hardware options, and specifying installed packages. Changes are applied with:

<syntaxhighlight lang="console">
# nixos-rebuild switch
</syntaxhighlight>

=== User configuration with Home Manager ===

For managing per-user configurations such as application preferences, command-line tools, and dotfiles, [[Home Manager]] provides a convenient, declarative approach. It allows users to define which programs should be installed and how they should be configured, without needing to include those settings in the system-wide [https://nixos.org/manual/nixos/stable/#sec-changing-config configuration.nix].

Home Manager can be used independently of the system configuration and works with both traditional setups and newer [[Flakes]]-based configurations.

=== With Flakes === 


For users looking for a more streamlined and reproducible way to manage NixOS configurations, the [[Flakes]] feature has been gaining popularity within the community. While Flakes introduce some new concepts compared to traditional workflows, many users find them a convenient and organized approach to managing system and development configurations.

Refer to [[Flakes#NixOS configuration with flakes]] for details on getting started.

== Beyond initial setup == 


Once your basic NixOS installation is complete and functional, you can further customize your system with a variety of optional configurations tailored for desktop use. For a list of recommended initial system configurations, see [[NixOS Installation Guide#NixOS configuration]].

Common configuration areas include:

==== Desktop Environments ====

Install and configure full-featured environments such as [[GNOME]], [[KDE Plasma]], or [[Xfce]].

See [[:Category:Desktop environment]] for a full list.

==== Window Managers ====

Set up lightweight or tiling window managers like [[i3]], [[Sway]], [[Hyprland]], or [[xmonad]].

See [[:Category:Window managers]] for a full list.

==== Display Managers (Login Managers) ====

Configure graphical session managers such as [[Gnome|GDM]], [[KDE|SDDM]], or [[LightDM]].

==== Audio Setup ====

Enable and configure [[:Category:Audio|audio]] systems like [[PipeWire]], [[PulseAudio]], or [[ALSA]].

==== Network Management ====

Use tools such as [[NetworkManager]] or [[systemd-networkd]] for managing [[Networking|network]] connections.

==== Bluetooth Support ====

Set up [[Bluetooth]] with blueman or other management tools.

==== Power Management ====

Configure [[laptop]] [[Power Management|battery management]], suspend, and hibernation with tools like [[Laptop#tlp|tlp]] or [[systemd]] services.

==== Printing and Scanning ====

Enable [[Cups]] for printer support and tools like Sane for [[Scanners|scanning]] devices.

== Tips and tricks == 

=== Modularizing your configuration with modules === 

{{main|NixOS system configuration#Modularizing your configuration with modules}}

== See also == 


* [[Overview of the NixOS Linux distribution]]
* [[Comparison of NixOS setups]] for a table comparing some popular choices.
* [[Configuration Collection]] for a long list within the wiki.
* [https://github.com/topics/nix-flake nix-flake], [https://github.com/topics/nixos-configuration nixos-configuration], [https://github.com/topics/nixos-dotfiles nixos-dotfiles] Github topics
* [[Wil T Nix Guides]] Youtube video format guide

[[Category:Desktop]]
[[Category:Guide]]
[[Category:NixOS]]
</translate>

NixOS

2025-06-08T17:59:12Z

Pigs: /* Declarative Configuration */ simplify section for newcommers, move more in-depth information into new page

{{Expansion|Incomplete (reason: it needs to be an easy introduction, because its one of the first articles new users read here. Thats why it needs to be simplified a bit and more complex topics should be moved to other articles))}}

[https://nixos.org/ NixOS] is a Linux distribution based on the [[Nix]] package manager and build system. It supports [https://en.wikipedia.org/wiki/Declarative_programming declarative] system-wide [https://en.wikipedia.org/wiki/Configuration_management configuration management] as well as [https://en.wikipedia.org/wiki/Atomicity_(database_systems) atomic] upgrades and rollbacks, although it can additionally support [https://en.wikipedia.org/wiki/Imperative_programming imperative] package and user management. In NixOS, all components of the distribution — including the [https://en.wikipedia.org/wiki/Linux_kernel kernel], installed [https://en.wikipedia.org/wiki/Package_manager packages] and system configuration files — are built by [[Nix]] from [[Wikipedia:Pure function|pure functions]] called [[Nix Expression Language|Nix expressions]].

Since Nix uses [https://en.wikipedia.org/wiki/Executable binary] caching, this provides a unique compromise between the binary-oriented approach used by distributions such as Debian and the [https://en.wikipedia.org/wiki/Source_code source]-oriented approach used by distributions such as Gentoo. Binaries can be used for standard components, and custom-built packages and modules can be used automatically when a pre-built binary is not available.

Stable NixOS releases are delivered twice a year (around the end of May and the end of November). NixOS was created by [https://edolstra.github.io/ Eelco Dolstra] and [https://en.wikipedia.org/wiki/Armijn_Hemel Armijn Hemel], and initially released in 2003. It is community developed and maintained under the stewardship of the [[Nix_Community#NixOS_Foundation|NixOS Foundation]].

== Installation ==

For a full installation guide, see the [https://nixos.org/nixos/manual/index.html#ch-installation Installation chapter of the NixOS manual]. This wiki also includes alternative or supplemental guides, such as [[NixOS as a desktop]].

Most users will install NixOS via [https://nixos.org/download/#nixos-iso one of the ISO images.] Both "graphical" and "minimal" ISO variants are available for each supported architecture; the "graphical" images are suitable for users intending to install a desktop environment, and the "minimal" images are suitable for users intending to install NixOS in a server role or desiring a smaller ISO image. The ISO images are hybrid images which can be burnt to optical media or copied raw to a USB drive and booted as-is. See the installation guide for details.

In addition to the ISO images, the [https://nixos.org/download/#nixos-iso download page] provides a number of alternative methods for installing NixOS. These include:

* Virtual appliances in OVA format (compatible with VirtualBox);
* Amazon EC2 AMIs;

Additionally, many existing Linux installations can be converted into NixOS installations using [https://github.com/elitak/nixos-infect nixos-infect] or [https://github.com/jeaye/nixos-in-place nixos-in-place]; this is particularly useful for installing NixOS on hosting providers which do not natively support NixOS.

For information on installing NixOS on various ARM devices, see [[NixOS on ARM]].

== Usage ==

=== Declarative Configuration ===

One of NixOS's defining features is its declarative configuration model, where the entire system state — including installed packages, system services, and settings — is described in configuration files. The primary file is typically located at <code>/etc/nixos/configuration.nix</code>.

Changes to the configuration are applied atomically using <code>nixos-rebuild switch</code>, ensuring reproducibility and the ability to roll back to previous states. Most users track their configuration files in a version control system, enabling consistent and portable system setups. These shortcomings are often rectified after-the-fact if at all by configuration management solutions such as Puppet, Ansible or Chef. These tools reconcile system configuration with a description of the expected state. However, these tools are not integrated into the operating system design and are simply layered on top, and OS configuration may still vary where an aspect of OS configuration has not been specified in the description of expected state.

Unlike conventional distributions, where system configuration is often scattered across manually edited files, NixOS integrates configuration management directly into the operating system. This eliminates configuration drift and makes NixOS particularly well-suited for automated, reproducible deployments.

For more details and examples on NixOS configurations, see [[NixOS system configuration]].

=== Imperative Operations ===

While NixOS is typically configured declaratively as much as possible, these are a few domains where imperative operations are still necessary; these include user environment management and channel management.

==== User Environments ====

In addition to declarative system configuration, NixOS users can utilize Nix's imperative <code>nix-env</code> command to install packages at the user level, without changing the system state. See the [[Nix#User Environments| user environments section of the Nix article]] for more information.

==== Channels ====

NixOS, as well as Nix packages and NixOS modules are distributed through Nix channels: mechanisms for distributing Nix expressions as well as the associated binary caches for them. These channels are what determine which version of NixOS you are using, and they can be broadly categorized into ''stable'' and ''unstable'' channels, and ''large'' and ''small'' channels. Most users will want the stable/large channel, currently <code>nixos-24.05</code>. For more information on channels and how to choose them, see the [[Channel branches]] article.

Like packages installed via <code>nix-env</code>, channels are managed at user-level. NixOS uses the channels set for the <code>root</code> user to update the system-wide configuration; channels set for other users control only the user environment for that user. If you wish to change the channel used by the system-level configuration (<code>/etc/nixos/configuration.nix</code>), ensure you run the correct <code>nix-channel</code> command as root:

{| class="wikitable"
|+ Common nix-channel commands
|-
|Listing current channels
|<code>nix-channel --list</code>
|-
| Adding a primary channel
|<code><nowiki>nix-channel --add https://nixos.org/channels/channel-name nixos</nowiki></code>
|-
| Adding other channels
|<code><nowiki>nix-channel --add https://some.channel/url my-alias</nowiki></code>
|-
| Remove a channel
|<code>nix-channel --remove channel-alias</code>
|-
| Updating a channel
|<code>nix-channel --update channel-alias</code>
|-
| Updating all channels
|<code>nix-channel --update</code>
|-
| Rollback the last update (useful if the last update breaks the <code>nixos-rebuild</code>)
|<code>nix-channel --rollback</code>
|}

Note that updating channels won't cause a rebuild in itself; if you want to update channels and rebuild, you can run <code>nixos-rebuild --upgrade switch</code> to do both in one step.

== Internals ==

=== Comparison with traditional Linux Distributions ===

''Main Article: [[Nix vs. Linux Standard Base]]''

The main difference between NixOS and other Linux distributions is that NixOS does not follow the [https://en.wikipedia.org/wiki/Linux_Standard_Base Linux Standard Base] file system structure. On LSB-compliant systems software is stored under <code>/{,usr}/{bin,lib,share}</code> and configuration is generally stored in <code>/etc</code>. Software binaries are available in the user environment if they are placed in one of the LSB's <code>/bin</code> directories. When a program references dynamic libraries it will search for the required libraries in the LSB folders (<code>/lib</code>, <code>/usr/lib</code>).

In NixOS however <code>/lib</code> and <code>/usr/lib</code> do not exist. Instead all system libraries, binaries, kernels, firmware and configuration files are placed in the [[Nix#Nix store|Nix store]]. The files and directories in <code>/nix/store</code> are named by hashes of the information describing the built data. All of the files and directories placed in the Nix store are immutable. <code>/bin</code> and <code>/usr/bin</code> are almost absent: they contain only <code>/bin/sh</code> and <code>/usr/bin/env</code> respectively, to provide minimal compatibility with existing scripts using shebang lines. User-level environments are implemented using a large number of symbolic links to all required packages and auxiliary files. These environments are called [[Nix#Profiles|profiles]] and are stored in <code>/nix/var/nix/profiles</code>, each user having their own profiles. Structuring the system in this way is how NixOS obtains its key advantages over conventional Linux distributions, such as atomicity and rollback support.

=== Usage of the Nix store ===

A lot of confusion for newcomers arises from the fact that configuration is stored in the read-only <code>/nix/store</code> tree along with all the installed packages. This fact makes it impossible to manually edit system configuration; all configuration changes must be performed by editing the <code>/etc/nixos/configuration.nix</code> file and executing <code>nixos-rebuild switch</code>. NixOS provides the [[NixOS_modules|module system]] for editing all required configurations. Users should first use [https://search.nixos.org/options the option search tool] to check if the option they need exists before attempting to manually add files or configuration via low-level NixOS features like activation scripts.

The system purity makes it possible to keep system configuration in a central place, without the need to edit multiple files. This configuration can be distributed or version controlled as desired. It also provides for determinism; if you provide the same inputs, the same version of Nixpkgs and the same <code>/etc/nixos/configuration.nix</code> you will get the exact same system state.

=== Modules ===

The [[NixOS modules|NixOS module system]] as defined in [[Nixpkgs]] provides the means necessary to customize the configuration of the OS. It is used to enable and customize services such as nginx, enable firmware and customize the kernel.

All module configuration is generally performed by adding options to <code>/etc/nixos/configuration.nix</code>. Most of the examples in the wiki show how this file can be used to configure the OS.

The NixOS module system implements a typing system which allows typechecking of option settings. It also enables options defined in multiple places to be merged automatically. This allows you to spread your configuration over multiple files, and the options you set across all of those files will be merged together:

{{file|/etc/nixos/configuration.nix|nix|<nowiki>
{
imports = [
./basic-webserver.nix
./blog.nix
];
}
</nowiki>}}
{{file|/etc/nixos/basic-webserver.nix|nix|<nowiki>
{
services.nginx.enable = true;
services.nginx.virtualHosts."example.com" = {
root = "/var/www/example.com";
};
}
</nowiki>}}
{{file|/etc/nixos/blog.nix|nix|<nowiki>
{
services.nginx.virtualHosts."blog.example.com" = {
root = "/var/www/blog.example.com";
};
}
</nowiki>}}

See the [https://nixos.org/nixos/manual/index.html#sec-writing-modules Modules section of the NixOS Manual] for more details.

=== Generations ===

Every time the system state is rebuilt using <code>nixos-rebuild switch</code>, a new generation is created. You can revert to the previous generation at any time, which is useful if a configuration change (or system update) turns out to be detrimental.

You can roll back via:

<syntaxHighlight lang=shell>
$ nix-env --rollback # roll back a user environment
$ nixos-rebuild switch --rollback # roll back a system environment
</syntaxHighlight>

NixOS also places entries for previous generations in the bootloader menu, so as a last resort you can always revert to a previous configuration by rebooting. To set the currently booted generation as the default run

<syntaxHighlight lang=shell>
$ /run/current-system/bin/switch-to-configuration boot
</syntaxHighlight>

Because NixOS keeps previous generations of system state available in case rollback is desired, old package versions aren't deleted from your system immediately after an update. You can delete old generations manually:

<syntaxHighlight lang=shell>
# delete generations older than 30 days
$ nix-collect-garbage --delete-older-than 30d

# delete ALL previous generations - you can no longer rollback after running this
$ nix-collect-garbage -d
</syntaxHighlight>

List generations:
<syntaxHighlight lang=shell>
# as root
$ nix-env --list-generations --profile /nix/var/nix/profiles/system
</syntaxHighlight>

Switch generations:
<syntaxHighlight lang=shell>
# as root switch to generation 204
$ nix-env --profile /nix/var/nix/profiles/system --switch-generation 204
</syntaxHighlight>

delete broken generation(s):
<syntaxHighlight lang=shell>
# as root delete broken generations 205 and 206
$ nix-env --profile /nix/var/nix/profiles/system --delete-generations 205 206
</syntaxHighlight>

You can configure automatic garbage collection by setting the [https://search.nixos.org/options?query=nix.gc nix.gc] options in <code>/etc/nixos/configuration.nix</code>. This is recommended, as it keeps the size of the Nix store down.

== See also ==

* [[NixOS modules]], a library for modular [[Overview of the Nix Expression Language#Expressions|Nix expressions]] which powers [[#Declarative Configuration|the declarative configuration of NixOS]].
* [[NixOS VM tests]], a library for creating reproducible infrastructure tests, based on [[Nixpkgs]], [[NixOS]], QEMU and Perl.
* [https://github.com/ryan4yin/nixos-and-flakes-book NixOS & Flakes Book] (Ryan4yin, 2023) - 🛠️ ❤️ An unofficial NixOS & Flakes book for beginners.

[[Category:Pedias]]
[[Category:NixOS]]
[[Category:Nix]]

NixOS system configuration

2025-06-08T17:58:54Z

Pigs: Create page, move some content from Flakes, NixOs as a desktop, and Overview of the NixOS Linux distributions pages to here

[[NixOS]] uses a declarative configuration system that allows users to manage their entire operating system setup including installed packages, system services, user accounts, hardware settings, and more through configuration files. This page serves as an overview of how to work with and manage NixOS system configurations.

For an introduction to declarative configuration, see the [[Overview of the NixOS Linux distribution#Declarative Configuration]] and the {{NixOS Manual|name=NixOS official manual|anchor=#ch-configuration}}.

== Usage ==

When you install NixOS, a default system configuration template is generated by the [[nixos-generate-config]] tool. This creates a basic <code>configuration.nix</code> file along with a corresponding <code>hardware-configuration.nix</code>, which captures detected hardware settings and filesystem definitions. After making changes to <code>configuration.nix</code>, you can apply them using [[nixos-rebuild]]:

<syntaxhighlight lang="console">
# nixos-rebuild switch
</syntaxhighlight>

Here is a simple example of a NixOS system configuration:

{{file|/etc/nixos/configuration.nix|nix|<nowiki>
{ config, pkgs, ... }:

{
# Import other configuration modules
# (hardware-configuration.nix is autogenerated upon installation)
# paths in nix expressions are always relative the file which defines them
imports = [
./hardware-configuration.nix
./my-dev-tools.nix
./my-desktop-env.nix
./etc.nix
];

# Name your host machine
networking.hostName = "mymachine";

# Set your time zone.
time.timeZone = "Europe/Utrecht";

# Enter keyboard layout
services.xserver.layout = "us";
services.xserver.xkbVariant = "altgr-intl";

# Define user accounts
users.users.myuser = {
extraGroups = [ "wheel" "networkmanager" ];
isNormalUser = true;
};

# Install some packages
environment.systemPackages = with pkgs; [
ddate
testdisk
];

# Enable the OpenSSH daemon
services.openssh.enable = true;

}
</nowiki>}}

To find NixOS module options, see https://search.nixos.org/options.

== Defining NixOS as a flake ==

[[Flakes]] offer an alternative, modern way to configure NixOS systems using a standardized and reproducible structure. With flakes, the system configuration — along with any additional inputs such as Nixpkgs or external modules — is managed declaratively within a <code>flake.nix</code> file.

Unlike the traditional configuration model, which relies on <code>/etc/nixos/configuration.nix</code> and channels, flakes explicitly define their dependencies and configurations, making it easier to share, version, and reproduce complete NixOS system setups.

By default, [[Nixos-rebuild|<code>nixos-rebuild switch</code>]] will read its [[Overview_of_the_NixOS_Linux_distribution#Declarative_Configuration system configuration|configuration]] from <code>/etc/nixos/flake.nix</code> if it is present.

An example basic [[NixOS]] flake:

{{file|flake.nix|nix|
<nowiki>
{
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 ];
};
};
}
</nowiki>
}}

=== Accessing flake inputs ===

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

{{file|flake.nix|nix|<nowiki>
{
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 ];
};
};
}
</nowiki>
}}

Then, you can access the flake inputs from your system configuration:

{{file|configuration.nix|nix|<nowiki>
{ config, lib, inputs, ... }: {
# do something with home-manager here, for instance:
imports = [ inputs.home-manager.nixosModules.default ];
...
}
</nowiki>
}}

=== Specifying hostname ===

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

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

To switch a remote host you can use:

<syntaxhighlight lang="console">
$ nixos-rebuild --flake .#mymachine \
--target-host mymachine-hostname \
--build-host mymachine-hostname --fast \
switch
</syntaxhighlight>

{{note|Remote building has an issue that's [https://github.com/NixOS/nixpkgs/issues/134952#issuecomment-1367056358 resolved by setting the <code>--fast</code> flag].}}

== Tips and tricks ==

=== Using a non-default configuration location ===

By default, NixOS expects system configuration files to be located in <code>/etc/nixos/</code>, with the primary configuration file at <code>/etc/nixos/configuration.nix</code>. However, it is possible to manage your configuration from a different location.

You can specify a different configuration file when rebuilding the system by providing the path via the <code>-I</code> option:

<syntaxhighlight lang="console">
# nixos-rebuild switch -I nixos-config=/path/to/configuration.nix
</syntaxhighlight>

If you are using [[Flakes]], specify the flake path instead:

<syntaxhighlight lang="console">
# nixos-rebuild switch --flake /path/to/flake.nix
</syntaxhighlight>

To set a custom configuration location declaratively, you can configure the <code>nix.nixPath</code> option in your system configuration:

{{file|/etc/nixos/configuration.nix|nix|
<nowiki>
{
nix.nixPath = [ "path to config" ];
...
}
</nowiki>
}}

Alternatively, you may also set the location with <code>NIX_PATH="nixos-config=/path/to/configuration.nix"</code> environment variable or by symlinking <code>/etc/nixos/configuration.nix</code>.

=== Modularizing your configuration with modules ===

The <code>configuration.nix</code> file itself is an instance of a [[NixOS modules|NixOS module]], and the NixOS module system makes it straightforward to split your configuration into multiple files for better organization and reusability. Modules can:

* Import other modules
* Declare new configuration options
* Provide values for existing options (this is what most of a standard configuration.nix does)
* Reference option values from other modules (via the <code>config</code> attribute passed to all modules)

By declaring options for any values you wish to share between modules, you can structure your configuration into as many files as you like, importing them directly or indirectly from your root <code>configuration.nix</code> file. This makes it easier to manage large or complex configurations by keeping related settings together.

Additionally, you can import modules from remote sources if desired, for example using </code>builtins.fetchTarball</code> or similar functions, which is particularly useful for sharing configurations across multiple machines or pulling in reusable modules maintained elsewhere.

Refer to [[NixOS modules]] page and {{NixOS Manual|name=NixOS Manual: Chapter - Package Management|anchor=#sec-writing-modules}} for more information on modules.

=== Flake-specific tips ===

==== Importing packages from multiple nixpkgs branches ====

A NixOS config flake could be as follows (replace <hostname> with your hostname):

{{file|flake.nix|nix|<nowiki>
{
description = "NixOS configuration with two or more channels";

inputs = {
nixpkgs.url = "github:NixOS/nixpkgs/nixos-24.11";
nixpkgs-unstable.url = "github:NixOS/nixpkgs/nixos-unstable";
};

outputs =
{ nixpkgs, nixpkgs-unstable, ... }:
{
nixosConfigurations."<hostname>" = nixpkgs.lib.nixosSystem {
modules = [
{
nixpkgs.overlays = [
(final: prev: {
unstable = nixpkgs-unstable.legacyPackages.${prev.system};
# use this variant if unfree packages are needed:
# unstable = import nixpkgs-unstable {
# inherit prev;
# system = prev.system;
# config.allowUnfree = true;
# };
})
];
}
./configuration.nix
];
};
};
}
</nowiki>
}}

{{file|flake.nix|nix|<nowiki>
# can now use "pkgs.package" or "pkgs.unstable.package"
{ pkgs, ... }:
{
environment.systemPackages = [
pkgs.firefox
pkgs.unstable.chromium
];
# ...
}
</nowiki>
}}

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>

==== Pinning the flake registry on NixOS ====

When you use flakes, Nix resolves flake inputs using the [https://github.com/NixOS/flake-registry flake registry], a mapping of named flake URLs to specific locations (e.g. what <code>nixpkgs</code> resolves to).

By default, <code>nixpkgs</code> tracks <code>nixpkgs-unstable</code>. This can lead to silent changes in dependency resolution and increase build times as it has to fetch the latest versions.

You can lock the registry to your current system's Nixpkgs version by:

{{file|configuration.nix|nix|<nowiki>
{ inputs, ... }:
{
nix.registry = {
nixpkgs.flake = inputs.nixpkgs;
};
}
</nowiki>
}}

To make sure the registry entry is "locked" by checking against a hash, use the following:

{{file|configuration.nix|nix|<nowiki>
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");
};
};
</nowiki>
}}

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

==== 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=console>
$ 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 Scripts|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>

== See Also ==

* [[Updating NixOS]] - Updating the set of [[Nixpkgs]] the system uses

* [[NixOS as a dekstop]] - Configuration tips for setting up NixOS as a desktop

* [[Nixos-rebuild]] - Command to apply changes to system configuration

* [[Home Manager]] - A system for per-user configuration environments

* [[NixOS configuration editors]] - Recommendations for improving NixOS configuration experience

* [[Configuration Collection]] - Community member's NixOS confiugration files for inspiration

[[Category:NixOS]]

Btrfs

2025-06-08T05:48:27Z

Pigs: Include trim support section

[https://btrfs.readthedocs.io/en/latest/ btrfs] is a modern copy on write (CoW) filesystem for Linux aimed at implementing advanced features while also focusing on fault tolerance, repair and easy administration.

{{note| Use [https://github.com/nix-community/disko/ disko] to manage your NixOS storage layout declaratively. The following shows a manual approach as seen in traditional Linux distributions.}}

= Installation of NixOS on btrfs =

{{note|The following example is for EFI enabled systems. Adjust commands accordingly for a BIOS installation.}}

== Partition the disk ==
<syntaxhighlight lang="console">
# printf "label: gpt\n,550M,U\n,,L\n" | sfdisk /dev/sdX
</syntaxhighlight>

== Format partitions and create subvolumes ==
<syntaxhighlight lang="console">
# nix-shell -p btrfs-progs
# mkfs.fat -F 32 /dev/sdX1

# mkfs.btrfs /dev/sdX2
# mkdir -p /mnt
# mount /dev/sdX2 /mnt
# btrfs subvolume create /mnt/root
# btrfs subvolume create /mnt/home
# btrfs subvolume create /mnt/nix
# umount /mnt
</syntaxhighlight>

== Mount the partitions and subvolumes ==
<syntaxhighlight lang="console">
# mount -o compress=zstd,subvol=root /dev/sdX2 /mnt
# mkdir /mnt/{home,nix}
# mount -o compress=zstd,subvol=home /dev/sdX2 /mnt/home
# mount -o compress=zstd,noatime,subvol=nix /dev/sdX2 /mnt/nix

# mkdir /mnt/boot
# mount /dev/sdX1 /mnt/boot
</syntaxhighlight>

== Install NixOS ==
<syntaxhighlight lang="console">
# nixos-generate-config --root /mnt
# nano /mnt/etc/nixos/configuration.nix # manually add mount options (see Compression below for an example)
# nixos-install
</syntaxhighlight>

= Configuration =

== Compression ==

<code>nixos-generate-config</code> doesn't detect mount options automatically. To enable compression, you must specify them manually and other mount options in your <code>configuration.nix</code>:

{{file|/etc/nixos/configuration.nix|nix|
<nowiki>
fileSystems = {
"/".options = [ "compress=zstd" ];
"/home".options = [ "compress=zstd" ];
"/nix".options = [ "compress=zstd" "noatime" ];
"/swap".options = [ "noatime" ];
};
</nowiki>
}}

Btrfs supports a few compression algorithms, each with different trade-offs:

* <code>zstd</code>: Good compression ratio and performance, especially for general-purpose workloads. You can specify compression levels, as example <code>compress=zstd:3</code>.

* <code>lzo</code>: Faster but provides lower compression ratios. Good for low powered systems or where performance is important.

* <code>zlib</code>: Higher compression ratio but slower performance. Less commonly used nowadays in favor of zstd.

You can find more details on the official [https://btrfs.readthedocs.io/en/latest/Compression.html Btrfs Compression Documentation].

{{note| Compression is applied only to newly written data. Existing data won't be compressed unless rewritten. (e.g., <code>btrfs filesystem defrag -r -v -czstd /path</code>)}}

== Swap file ==

Creating a separate subvolume for the swap file is optional. It is not required for functionality but can help with organization or snapshot management. Be sure to regenerate your <code>hardware-configuration.nix</code> if you choose to do this.

<syntaxhighlight lang="console">
# mkdir -p /mnt
# mount /dev/sdXY /mnt
# btrfs subvolume create /mnt/swap
# umount /mnt
# mkdir /swap
# mount -o noatime,subvol=swap /dev/sdXY /swap
# nixos-generate-config
</syntaxhighlight>

Finally, define a swap file in your configuration and run <code>nixos-rebuild switch</code>:

{{file|/etc/nixos/configuration.nix|nix|
<nowiki>
swapDevices = [{
device = "/swap/swapfile";
size = 8*1024; # Creates an 8GB swap file
}];
</nowiki>
}}

NixOS will automatically create the swap file with the appropriate attributes for Btrfs including disabling copy on write.

{{note| On systems where you do need to manually prepare a swap file on Btrfs, you can use <code>btrfs filesystem mkswapfile</code> utility, e.g.: <code># btrfs filesystem mkswapfile --uuid clear /swap/swapfile</code>}}

For more NixOS swap configuration options, see [[Swap]]. Additonal Btrfs swapfile usage can be found at [https://btrfs.readthedocs.io/en/latest/Swapfile.html the Btrfs docs].

== Scrubbing ==

Btrfs filesystems by default keep checksums for all files, to monitor if the file has changed due to hardware malfunctions or other external effects.

Scrubbing is the process of checking file consistency, which may use checksums and/or duplicated copies of data, from raid for example. Scrubbing may be done "online", meaning you don't need to unmount a subvolume to scrub it.

You can enable automatic scrubbing withː
<syntaxhighlight lang="nix">
services.btrfs.autoScrub.enable = true;
</syntaxhighlight>

Automatic scrubbing by default is performed once a month, but you can change that withː
<syntaxhighlight lang="nix">
services.btrfs.autoScrub.interval = "weekly";
</syntaxhighlight>
<code>interval</code> syntax is defined by [https://www.freedesktop.org/software/systemd/man/systemd.time.html#Calendar%20Events systemd.timer's Calendar Events]

By default, autoscrub will scrub all detected btrfs mount points. However, in case of mounted nested subvolumes (e.g. the example above where <code>/nix</code> and <code>/home</code> are nested subvolumes under <code>/</code>), you only need to scrub the topmost one. So an example configuration may look like this:
<syntaxhighlight lang="nix">
services.btrfs.autoScrub = {
enable = true;
interval = "monthly";
fileSystems = [ "/" ];
};
</syntaxhighlight>

The result of the periodic auto scrub will be saved to the system journal, and you can check the status of the last scrubː
<syntaxhighlight lang="bash">
btrfs scrub status /
</syntaxhighlight>

You can also start a scrub in the background manuallyː
<syntaxhighlight lang="bash">
btrfs scrub start /
</syntaxhighlight>
You can check the status of the ongoing scrubbing process with the same <code>status</code> command as above.

== Deduplication ==

Files with (partially) equal contents can be deduplicated using [https://github.com/Zygo/bees bees] or [https://github.com/markfasheh/duperemove duperemove].

bees can be configured in <code>configuration.nix</code>:

<syntaxhighlight lang="nix">
services.beesd.filesystems = {
root = {
spec = "LABEL=root";
hashTableSizeMB = 2048;
verbosity = "crit";
extraOptions = [ "--loadavg-target" "5.0" ];
};
};
</syntaxhighlight>

This will run the daemon in the background. To disable auto-start, use <code>systemd.services."beesd@root".wantedBy = lib.mkForce [ ];</code> for each filesystem.

= Usage =

== Subvolumes ==

To display all subvolumes within a mounted btrfs filesystem:

<syntaxhighlight lang="bash">
btrfs subvolume list -t /mnt
</syntaxhighlight>

To create a new subvolume at a specified location:

<syntaxhighlight lang="bash">
btrfs subvolume create /mnt/nixos
</syntaxhighlight>

To remove an existing subvolume:

<syntaxhighlight lang="bash">
btrfs subvolume delete /mnt/nixos
</syntaxhighlight>

=== Top level vs nested subvolumes ===

In btrfs, subvolumes can be created either at the top level of the filesystem or within other subvolumes

* Top level subvolumes are created directly under the filesystem's root. By default, the root volume id is 5. Top level subvolumes are easier to snapshotted, rolled back or destroyed independently. This is good for things such as <code>/home</code> or <code>/nix</code>.

* Nested subvolumes are created inside an existing subvolume or directory within the filesystem. All nested subvolumes inherit the mount status of their parent unless mounted seperately. This layout is useful for organizing related subvolumes under a common namespace. For example, a top-level subvolume such as <code>/srv/nfs</code> can contain multiple nested subvolumes like <code>/srv/nfs/export1</code> and <code>/srv/nfs/export2</code>.

== Snapshots ==

A snapshot in btrfs is simply a subvolume that shares its data (and metadata) with some other subvolume, using btrfs's CoW capabilities. Because of that, there is no special location for snapshots and you can decide where you want to store them. It can be a simple directory inside the root subvolume, or a directory inside a dedicated "snapshots" subvolume.

For this example we are going to store snapshots in a directory <code>/snapshots</code>, that has to be created beforehand with <code>sudo mkdir /snapshots</code>

To take a read-only (<code>-r</code>) snapshot called <code>home_snapshot_202302</code> of the subvolume mounted at <code>/home</code>

<syntaxhighlight lang="bash">
btrfs subvolume snapshot -r /home /snapshots/home_snapshot_202302
</syntaxhighlight>

You can also snapshot the root subvolume. But keep in mind that nested subvolumes are '''not''' part of a snapshot. So if you have subvolumes <code>/nix /home</code>, taking a snapshot of <code>/</code> will not include them.

<syntaxhighlight lang="bash">
btrfs subvolume snapshot -r / /snapshots/nixos_snapshot_202302
</syntaxhighlight>

Make snapshot read-write againː

<syntaxhighlight lang="bash">
btrfs property set -ts /snapshots/home_snapshot_202302 ro false
</syntaxhighlight>

However, changing read-only property of a snapshot in-place may [//lore.kernel.org/linux-btrfs/06e92a0b-e71b-eb21-edb5-9d2a5513b718@gmail.com/ causes issues] with any future incremental send/receive. Instead, a read-only snapshot itself (being a simple subvolume) can be snapshotted again as a read-write snapshot like this:<syntaxhighlight lang="bash">
btrfs subvolume snapshot /snapshots/home_snapshot_202302 /snapshots/home_snapshot_202302_rw
</syntaxhighlight>

Or it can be restored directly to <code>/home</code> straight away like this:
{{warning|1=this will delete the current <code>/home</code> and restore the snapshot! <code>/home</code> must be unmounted for this operation}}

<syntaxhighlight lang="bash">
btrfs subvolume delete /home
btrfs subvolume snapshot /snapshots/home_snapshot_202302 /home
</syntaxhighlight>
After this you can mount <code>/home</code> again.

== Transfer snapshot ==

Sending the snapshot <code>/snapshots/nixos_snapshot_202302</code> compressed to a remote host via ssh at <code>root@192.168.178.110</code> and saving it to a subvolume mounted on a directory at <code>/mnt/nixos</code>

<syntaxhighlight lang="bash">
sudo btrfs send /snapshots/nixos_snapshot_202302 | zstd | ssh root@192.168.178.110 'zstd -d | btrfs receive /mnt/nixos'
</syntaxhighlight>

If both the sender and receiver side have Btrfs with the same compression algorithm and level, you can instead use <code>send --compressed-data</code> to avoid decompressing and recompressing the data.

= Tips and tricks =

== Backup ==

[[Btrbk]] is a tool for creating snapshots and remote backups of btrfs subvolumes.

== Installation with encryption ==

Using [https://en.wikipedia.org/wiki/Linux_Unified_Key_Setup Luks2]:
<syntaxhighlight lang="bash">
cryptsetup --verify-passphrase -v luksFormat "$DISK"p2

cryptsetup open "$DISK"p2 enc
</syntaxhighlight>

You can use any device partition for your bootloader. Note that this bootloader is unencrypted by default:

<code>mkfs.vfat -n BOOT "$DISK"p1</code>

=== Creating subvolumes ===

<syntaxhighlight lang="bash">
mkfs.btrfs /dev/mapper/enc # Creating btrfs partition

mount -t btrfs /dev/mapper/enc /mnt

# Create the subvolumes

btrfs subvolume create /mnt/root # The subvolume for /

btrfs subvolume create /mnt/home # The subvolume for /home, which should be backed up

btrfs subvolume create /mnt/nix # The subvolume for /nix, which needs to be persistent but is not worth backing up, as it’s trivial to reconstruct

btrfs subvolume create /mnt/log # The subvolume for /var/log.
</syntaxhighlight>

Unmount to mount on the subvolumes for the next steps:

<code>umount /mnt</code>

Once the subvolumes have been created, mount them with the desired options.

Example with [https://facebook.github.io/zstd/ Zstandard compression] and noatime:
<syntaxhighlight lang="bash">
mount -o subvol=root,compress=zstd,noatime /dev/mapper/enc /mnt

mkdir /mnt/home

mount -o subvol=home,compress=zstd,noatime /dev/mapper/enc /mnt/home

mkdir /mnt/nix

mount -o subvol=nix,compress=zstd,noatime /dev/mapper/enc /mnt/nix

mkdir -p /mnt/var/log

mount -o subvol=log,compress=zstd,noatime /dev/mapper/enc /mnt/var/log

# do not forget to create and mount the bootloader

mkdir /mnt/boot

mount "$DISK"p1 /mnt/boot
</syntaxhighlight>

Configure <code>hardware-configuration.nix</code>
<syntaxhighlight lang="nix">
# enable btrfs support
boot.supportedFilesystems = [ "btrfs" ];

fileSystems."/var/log" =
{ device = "/dev/disk/by-uuid/X";
fsType = "btrfs";
# enable noatime and zstd to the other subvolumes aswell
options = [ "subvol=log" "compress=zstd" "noatime" ];
# to have a correct log order
neededForBoot = true;
};
</syntaxhighlight >
Generate Nixconfig:
<syntaxhighlight lang="bash">
nixos-generate-config --root /mnt
</syntaxhighlight >

== Convert Ext3/Ext4 system partition to Btrfs ==

{{Warning|Note that migrating your existing root filesystem can cause data loss or make your system unbootable. Make sure to backup the partition or your files. Proceed only if you know what you're doing!}}

To convert the existing filesystem (Ext3/4) to Btrfs, boot into a NixOS live system and run the following commandː<syntaxhighlight lang="sh">
fsck -f /dev/sdXY
btrfs-convert /dev/sdXY
</syntaxhighlight>Replace the device path with the target partition. Converting larger filesystems can take a long time.

Next, mount the converted filesystem and chroot into itː<syntaxhighlight lang="sh">
mount /dev/sdXY /mnt
nixos-enter --root /mnt
</syntaxhighlight>Replace the partition UUID with the new one, which can be obtained using the command <code>blkid</code>, in <code>/etc/nixos/hardware-configuration.nix</code> and also change the filesystem to <code>btrfs</code>.<syntaxhighlight lang="nix">
fileSystems."/" =
{ device = "/dev/disk/by-uuid/44444444-4444-4444-8888-888888888888";
fsType = "btrfs";
};

</syntaxhighlight>Apply the changes<syntaxhighlight lang="sh">
nixos-rebuild boot
</syntaxhighlight>If the Grub bootloader is used and it doesn't get reinstalled correctly, you can run the following command inside chrootː<syntaxhighlight lang="sh">
grub-install /dev/sdX
</syntaxhighlight>If the conversion was successful and no rollback is required, the backup image which was stored by btrfs-convert can be removed withː<syntaxhighlight lang="sh">
btrfs subvolume delete /btrfs/ext2_saved
</syntaxhighlight>

=== TRIM support ===

{{main|Filesystems#SSD TRIM support}}

Refer to [https://btrfs.readthedocs.io/en/latest/Trim.html btrfs docs] on how Trim works with btrfs through the <code>discard</code> mount option.

[[Category: Configuration]]
[[Category:Filesystem]]

Filesystems

2025-06-08T05:41:11Z

Pigs: /* SSD TRIM support */ don't mention filesystem specific mount options

[[category:filesystem]]
{{ic|fileSystems}} is a NixOS[[Category:NixOS]] option that allows the user to mount filesystems at specific mount points. The mounted filesystems may also be encrypted. Also see [https://nixos.org/manual/nixos/stable/options.html#opt-fileSystems the fileSystem option documentation].

For boot mount options, [https://manpages.ubuntu.com/manpages/noble/en/man8/mount.8.html#filesystem-independent%20mount%20options check here].

Common example filesystem mount. You can put this in configuration.nix:
<syntaxhighlight lang="nix">
fileSystems."/mnt/exampleDrive" = {
device = "/dev/disk/by-uuid/4f999afe-6114-4531-ba37-4bf4a00efd9e";
fsType = "exfat";
options = [ # If you don't have this options attribute, it'll default to "defaults"
# boot options for fstab. Search up fstab mount options you can use
"users" # Allows any user to mount and unmount
"nofail" # Prevent system from failing if this drive doesn't mount
"exec" # Permit execution of binaries and other executable files
];
};
</syntaxhighlight>

== Making disk visible in your file explorer ==
You might not see the disk in your file explorer (ie GNOME Nautilus). Add to the options: <code>x-gvfs-show</code> and it'll show up.

== Porting /etc/fstab ==

The options specified in /etc/fstab may not be fully compatible with NixOS fileSystems options. For example, here are some options NixOS doesn't recognize that are available on some Linux distributions:
* iocharset
* rw (but it seems to not be needed)
* uid with username rather than actual uid

== Mount order ==

Without any specification, the mount order is up to the implementation (probably alphabetic).

Should the order in which filesystems are mounted is important, users should make use of the [https://nixos.org/manual/nixos/stable/options.html#opt-fileSystems._name_.depends {{ic|fileSystems.<mount>.depends}} option]. This is useful for example in [[#Bind mounts]]

== Bind mounts ==

<blockquote>
Bind mounting allows a filesystem hierarchy or a file to be mounted at a different mount point. Unlike a symbolic link, a bind mount does not exist on the filesystem itself.<ref>[https://en.wikipedia.org/wiki/Mount_(Unix)#Bind_mounting Wikipedia - Bind mount]</ref>
</blockquote>

These are used to make files or folders available in other parts of the filesystem hierarchy. In order to do so both source and target filesystems have to be mounted first.
<syntaxhighlight lang="nix">
fileSystems."/mnt/datastore".label = "datastore";
fileSystems."/mnt/aggregator".label = "aggregator";

####################
# Bind mounts

# Mount /mnt/datastore/applications/app1 on /mnt/aggregator/app1
# Accessing /mnt/aggregator/app1 will actually access /mnt/datastore/...
fileSystems."/mnt/aggregator/app1" = {
depends = [
# The mounts above have to be mounted in this given order
"/mnt/datastore"
"/mnt/aggregator"
];
device = "/mnt/datastore/applications/app1";
fsType = "none";
options = [
"bind"
"ro" # The filesystem hierarchy will be read-only when accessed from /mnt/aggregator/app1
];
};
</syntaxhighlight>

== Tips and tricks ==

=== SSD TRIM support ===

On NixOS, [https://en.wikipedia.org/wiki/Trim_(computing) TRIM] support is enabled by default by the {{nixos:option|services.fstrim.enable}} option. This periodically discards unused blocks on supported storage devices, helping to maintain SSD performance over time.

The trimming schedule is controlled by the {{nixos:option|services.fstrim.interval}} option. Continuous trimming (as set by the <code>discard</code>, see <code>man mount(8)</code>) mount option is not recommended as it can negatively impact SSD performance.

Additionally, setting <code>noatime</code> can reduce the number of disk writes and can improve system performance.

{{file|/etc/nixos/configuration.nix|nix|
<nowiki>
fileSystems."/".options = [ "noatime" ];
</nowiki>
}}

= References =
<references />