nix-book

Understanding Nix Functions

2026-08-01T00:00:00+00:00

Chapter 2

✔️ Table of Contents

Understanding Nix Functions

Functions are the building blocks of Nix, appearing everywhere in Nix expressions and configurations. Mastering them is essential for writing effective Nix code and understanding tools like NixOS and Home Manager. This chapter explores how Nix functions work, focusing on their single-argument nature, currying, partial application, and their role in modules.

What are Nix Functions?

A Nix Function is a rule that takes an input (called an argument) and produces an output based on that input. Unlike many programming languages, Nix functions are designed to take exactly one argument at a time. This unique approach, combined with a technique called currying, allows Nix to simulate multi-argument functions in a flexible and reusable way.

Builtins

✔️ Nix Builtin Functions (Click to Expand)

The Nix expression evaluator has a bunch of functions and constants built in:

toString e: (Convert the expression e to a string)
import path: (Load, parse and return the Nix expression in the file path)
throw x: (Throw an error message x. Usually stops evaluation)
map f list: (Apply the function f to each element in the list)
Built-in Functions
Nix Operators

Lambdas

Nix functions are anonymous (lambdas) (e.g., x: x + 2), and technically take a single parameter. However, that single parameter is very often an attribute set, allowing you to effectively pass multiple named inputs by destructuring (e.g., { arg1, arg2 }: arg1 + arg2).

Type the parameter name, followed by a colon, and finally the body of the function.

nix-repl> param: param * 2
<<lambda @ <<string>>:1:1>>

nix-repl> (param: param * 2) 2
4

The above example shows that everything in Nix returns a value. When you call a function directly (without first assigning the function itself to a variable), the result of that call is immediately evaluated and displayed/used.

In order to make our function reusable and be able to pass different values at different times we have to assign our function to a variable:

nix-repl> twoTimes = param: param * 2

Now, we can reference our function by it’s name and pass our required parameter:

nix-repl> twoTimes
«lambda @ «string»:1:2»
nix-repl> twoTimes 2
4
nix-repl> twoTimes 4
8

We defined a function param: param * 2 takes one parameter param, and returns param * 2. We then assigned this function to the variable twoTimes. Lastly, we called the function with a few different arguments showing it’s reusability.

Understanding Function Structure: The Role of the Colon

The colon (:) acts as a clear separator within a function definition:

Left of the Colon: This is the function’s argument. It’s a placeholder name for a value that will be provided when the function is called.
Right of the Colon: This is the function body. It’s the expression that will be evaluated when the function is invoked.

Think of function arguments as naming values that aren’t known in advance. These names are placeholders that get filled with specific values when the function is used.

Example:

greet = personName: "Hello, ${personName}!";

Here, personName is the argument (the placeholder).
"Hello, ${personName}!", is the function body (which uses the placeholder to create the greeting).

When you call the function, (click to see Output):

greet "Anonymous"
~ "Hello, Anonymous!"

The value "Anonymous" is substituted for the personName placeholder within the function body.
This structure is the foundation of all Nix functions, whether simple or complex.

Single-Argument Functions: The Basics

The simplest form of a Nix function takes a single argument. In Nix, function definitions like x: x + 1 or personName: "Hello, ${personName}!"; are anonymous lambda functions. They exist as values until they are assigned to a variable.

Click to see Output:

# This is an anonymous lambda function value:
# x: x + 1
inc = x: x + 1;          # here we assigned our lambda to a variable `inc`
inc 5
~ 6

x is the argument.
x + 1 is the function body.

This straightforward design makes single-argument functions easy to understand and use. But what if you need a function that seems to take multiple arguments? That’s where currying comes in.

Simulating Multiple Arguments: Currying

To create functions that appear to take multiple arguments, Nix uses currying. This involves nesting single-argument functions, where each function takes one argument and returns another function that takes the next argument, and so on.

nix-repl> multiply = x: (y: x*y)
nix-repl> multiply
«lambda»
nix-repl> multiply 4
«lambda»
nix-repl> (mul 4) 5
20

We defined a function that takes the parameter x, the body returns another function. This other function takes a parameter y and returns x*y. Therefore, calling multiply 4 returns a function like: x: 4*y. In turn, we call the returned function with 5, and get the expected result.

Currying example 2

# concat is equivalent to:
# concat = x: (y: x + y);
concat = x: y: x + y;
concat 6 6    # Evaluates to 12
12

Here, concat is actually two nested functions

The first function takes x and returns another function.
The second function takes y and performs x + y

Nix interprets the colons (:) as separators for this chain of single-argument functions.

Here’s how it works step by step:

When you call concat 6, the outer function binds x to 6 and returns a new function: y: 6 + y.
When you call that function with 6 (i.e., concat 6 6), it computes 6 + 6, resulting in 12.

This chaining is why Nix functions are so powerful—it allows you to build flexible, reusable functions.

Currying is a powerful feature in Nix that enables you to partially apply arguments to functions, leading to increased reusability. This behavior is a direct consequence of Nix functions being “first-class citizens” (a concept we’ll delve into later), and it proves invaluable for decomposing intricate logic into a series of smaller, more focused functions.

Key Insight: Every colon in a function definition separates a single argument from its function body, even if that body is another function definition.

Greeting Example

Let’s explore currying with a more relatable example in the nix repl:

nix repl
nix-repl> greeting = prefix: name: "${prefix}, ${name}!";

nix-repl> greeting "Hello"
<<lambda @ <<string>>:1:10>> # partial application returns a lambda

nix-repl> greeting "Hello" "Alice"
"Hello, Alice!"         # providing both arguments returns the expected result

This function is a chain of two single-argument functions:

The outer function takes prefix (e.g. "Hello") and returns a function that expects name.
The inner function takes name (e.g. "Alice") and combines it with prefix to produce the final string.

Thanks to lexical scope (where inner functions can access variables from outer functions), the inner function “remembers” the prefix value.

Partial Application: Using Functions Incrementally

Because of currying, you can apply arguments to a Nix function one at a time. This is called partial application. When you provide only some of the expected arguments, you get a new function that “remembers” the provided arguments and waits for the rest.

[!EXAMPLE]

Using our greeting function again:
nix repl
nix-repl> greeting = prefix: name: "${prefix}, ${name}!";
nix-repl> helloGreeting = greeting "Hello";
nix-repl> helloGreeting "Alice"
"Hello, Alice"
helloGreeting is now a new function. It has already received the prefix argument ("Hello"), when we provide the second argument we get "Hello, Alice!"

Benefits of Partial Application:

Partial application provides significant benefits by enabling you to derive specialized functions from more general ones through the process of fixing certain parameters. Additionally, it serves as a powerful tool for adapting existing functions to fit the precise argument requirements of higher-order functions like map and filter.

Nix Functions being “first class citizens”

In the context of Nix, the phrase “Nix treats functions as first-class citizens” means that functions in Nix are treated as values, just like numbers, strings, or lists. They can be manipulated, passed around, and used in the same flexible ways as other data types. This concept comes from functional programming and has specific implications in Nix.

What It Means in Nix

Functions Can Be Assigned to Variables:

You can store a function in a variable, just like you would store a number or string.

[!EXAMPLE]
greet = name: "Hello, ${name}!";
Here, greet is a variable that holds a function.

Functions Can Be Passed as Arguments:

You can pass a function to another function as an argument, allowing for higher-order functions (functions that operate on other functions).

[!EXAMPLE]
applyTwice = f: x: f (f x);
inc = x: x + 1;
applyTwice inc 5 # Output: 7 (increments 5 twice: 5 → 6 → 7)
~ 7
Here, applyTwice takes a function f (in this case, inc) and applies it to x twice.

Functions Can Be Returned from Functions:

Functions can produce other functions as their output, which is key to currying in Nix.

[!EXAMPLE]
greeting = prefix: name: "${prefix}, ${name}!";
helloGreeting = greeting "Hello";  # Returns a function
helloGreeting "Alice"  # Output: "Hello, Alice!"
~ "Hello, Alice!"
The greeting function returns another function when partially applied with prefix.

Functions Are Values in Expressions:

Functions can be used anywhere a value is expected, such as in attribute sets or lists.

[!EXAMPLE]
myFuncs = {
  add = x: y: x + y;
  multiply = x: y: x * y;
};
myFuncs.add 3 4  # Output: 7
~ 7
Here, functions are stored as values in an attribute set.

To try this in the repl just remove the semi-colon (;)

Why This Matters in Nix:

This functional approach is fundamental to Nix’s unique build system. In Nix, package builds (called derivations) are essentially functions. They take specific inputs (source code, dependencies, build scripts) and deterministically produce outputs (a built package).

This design ensures atomicity: if a build does not succeed completely and perfectly, it produces no output at all. This prevents situations common in other package managers where partial updates or corrupted builds can leave your system in an inconsistent or broken state.

Many NixOS and Home Manager modules are functions, and their first-class status means they can be combined, reused, or passed to other parts of the configuration system.

Now that we understand the “first-class” nature of Nix Functions let’s see how they fit into NixOS and Home Manager modules.

The Function Nature of NixOS and Home Manager Modules

It’s crucial to understand that most NixOS and Home Manager modules are fundamentally functions.

These module functions typically accept a single argument: an attribute set (remember this, it’s important to understand).

Example:

A practical NixOS module example for Thunar with plugins:

# thunar.nix
{pkgs, ...}: {
  programs = {
    thunar = {
      enable = true;
      plugins = with pkgs.xfce; [
        thunar-archive-plugin
        thunar-volman
      ];
    };
  };
}

To use this module I would need to import it into my configuration.nix or equivalent, shown here for completeness.

# configuration.nix
# ... snip ...
imports = [ ../nixos/thunar.nix ];
# ... snip ...

This is actually a pretty good example of with making it a bit harder to reason where the plugins are from. You might instinctively try to trace a path like programs.thunar.plugins.pkgs.xfce because you saw pkgs.xfce in the with statement. But that’s now how with works. The pkgs.xfce path exists outside the plugins list, defining the source of the items, not their nested structure within the list.
To follow best practices you could write the above plugins section as:

plugins = [
  pkgs.xfce.thunar-archive-plugin
  pkgs.xfce.thunar-volman
];

Now it’s clear that each plugin comes directly from pkgs and each will resolve to a derivation.
- To be clear either way is fine, especially in such a small self contained module. If it were in a single file configuration.nix it would be a bit more confusing to trace. Explicitness is your friend with Nix and maintaining reproducability. with isn’t always bad but should be avoided at the top of a file for example to bring nixpkgs into scope, use let instead.

The entire module definition is a function that takes one argument (an attribute set):{ pkgs, ... }. When this module is included in your configuration, the NixOS module system calls this function with a specific attribute set. This attribute set contains the available packages (pkgs), and other relevant information. The module then uses these values to define parts of your system.

Understanding passing and getting back arguments

For this example we will build the Hello derivation from the Nix Pills series.

Create an autotools.nix with the following contents:

pkgs: attrs: let
  defaultAttrs = {
    builder = "${pkgs.bash}/bin/bash";
    args = [./builder.sh];
    baseInputs = with pkgs; [
      gnutar
      gzip
      gnumake
      gcc
      coreutils
      gawk
      gnused
      gnugrep
      binutils.bintools
    ];
    buildInputs = [];
    system = builtins.currentSystem;
  };
in
  derivation (defaultAttrs // attrs)

Let’s create the hello derivation:

let
  pkgs = import <nixpkgs> {};
  mkDerivation = import ./autotools.nix pkgs;
in
  mkDerivation {
    name = "hello";
    src = ./hello-2.12.1.tar.gz;
  }

You can get the tarball here, place it in the same directory as autotools.nix

And finally the builder.sh that autotools.nix declares for the args attribute:

#!/bin/bash
set -e
unset PATH
for p in $buildInputs $baseInputs; do
    export PATH=$p/bin${PATH:+:}$PATH
done

tar -xf $src

for d in *; do
    if [ -d "$d" ]; then
        cd "$d"
        break
    fi
done

./configure --prefix=$out
make
make install

When you write:

mkDerivation = import ./autotools.nix pkgs;

import ./autotools.nix: This evaluates the autotools.nix file. Because it starts with pkgs: attrs: ..., it means that autotools.nix evaluates to a function that expects one argument named pkgs.
... pkgs: We are immediately calling that function (the one returned by import ./autotools.nix) and passing it our pkgs variable (which is the result of import <nixpkgs> {}).

This illustrates the concept of Currying in Nix:

The function defined in autotools.nix (pkgs: attrs: ...) is a curried function. It’s a function that, when given its first argument (pkgs), returns another function (which then expects attrs).

The result of import ./autotools.nix pkgs is that second, inner function: attrs: derivation (defaultAttrs // attrs). This inner function is then bound to the mkDerivation variable, making it ready to be called with just the specific attributes for your package (like name and src).

Understanding the attrs Argument

Now let’s focus on the second argument of our autotools.nix function: attrs.

Recall the full function signature in autotools.nix:

pkgs: attrs: let
  # ... defaultAttrs definition ...
in
  derivation (defaultAttrs // attrs)

What attrs Represents:

Once autotools.nix has received its pkgs argument (and returned the inner function), this inner function is waiting for its final argument, which we call attrs.
attrs is simply an attribute set (a key-value map in Nix). It’s designed to receive all the specific properties of the individual package you want to build using this helper.

How attrs is Used:

Look at the final line of autotools.nix: derivation (defaultAttrs // attrs).
The // operator in Nix performs an attribute set merge. It takes all attributes from defaultAttrs and combines them with all attributes from attrs.
Crucially, if an attribute exists in both defaultAttrs and attrs, the value from attrs (the second operand) takes precedence and overrides the default value.

Applying attrs in the hello Derivation:

In the hello derivation, we call mkDerivation like this:

        mkDerivation {
          name = "hello";
          src = ./hello-2.12.1.tar.gz;
        }

The attribute set { name = "hello"; src = ./hello-2.12.1.tar.gz; } is what gets passed as the attrs argument to the mkDerivation function (which, remember, is the inner function returned by autotools.nix).
When derivation (defaultAttrs // attrs) is evaluated for “hello”, the name and src provided in the attrs set will be merged with all the defaultAttrs (like builder, args, baseInputs, etc.).

In summary:

The pkgs argument configures the general environment and available tools for the builder.
The attrs argument is where you provide the unique details for each specific package you intend to build using this autotools.nix helper. It allows you to specify things like the package’s name, source code, version, and any custom build flags, while still benefiting from all the sensible defaults provided by autotools.nix. This separation makes autotools.nix a reusable and flexible “template” for creating derivations.

Conclusion

Having explored the fundamental nature of functions in Nix, we can now see this concept applies to more complex areas like NixOS configuration and derivations. In the next chapter, NixOS Modules Explained. We will learn about NixOS Modules which are themselves functions most of the time.

Resources

✔️ Resources (Click to Expand)

Hardening NixOS

2026-06-17T00:00:00+00:00

Hardening NixOS

✔️ Table of Contents

Securing your NixOS system begins with a philosophy of minimalism, explicit configuration, and proactive control. As desktop Linux attracts more novice users, it has become an increasingly valuable target for attackers. This makes it crucial to adopt security best practices early to protect your desktop from common attack vectors and to avoid configuration mistakes that could expose vulnerabilities.

I am not a security expert. This guide presents various options for hardening NixOS, but it is your responsibility to evaluate whether each adjustment suits your specific needs and environment. Security hardening and process isolation can introduce stability challenges, compatibility issues, or unexpected behavior. Additionally, these protections often come with performance tradeoffs. Always conduct thorough research, there are no plug and play one size fits all security solutions.

That said, I typically write about what I’m implementing myself to deepen understanding and share what works for me. --Source means the proceeding paragraph came from --Source, you can often click to check for yourself. If you use some common sense with a bit of caution you could end up with a more secure NixOS system that fits your needs.

Much of this guide draws inspiration or recommendations from the well-known Linux Hardening Guide by Madaidan’s Insecurities. Madaidan’s work is widely regarded in technical and security circles as one of the most comprehensive and rigorously researched sources on practical Linux security, frequently cited for its depth and actionable advice. For example, much of the original basis for hardening for nix-mineral came from this guide as well. This can be a starting point but shouldn’t be blindly followed either, always do your own research, things change frequently. Madaidan is also a contributor to both Kicksecure and Whonix.

For an article with apposing perspectives, see debunking-madaidans-insecurities. We can learn from both and hopefully find something in between that is closer to the truth.

❗ Note on SELinux and AppArmor: While NixOS can provide a high degree of security through its immutable and declarative nature, it’s important to understand the limitations regarding Mandatory Access Control (MAC) frameworks. Neither SELinux nor AppArmor are fully supported or widely used in the NixOS ecosystem. You can do a lot to secure NixOS but if anonymity and isolation are paramount, I recommend booting into a Tails USB stick. Or using Whonix.

☝️ The unique file structure of NixOS, particularly the immutable /nix/store, makes it difficult to implement and manage the file-labeling mechanisms that these frameworks rely on. There are ongoing community efforts to improve support, but as of now, they are considered experimental and not a standard part of a typical NixOS configuration. For an immutable distro that implements SELinux by default at a system level as well as many other hardening techniques, see Fedora secureblue.

Containers and VMs are beyond the scope of this chapter but can also enhance security and sandboxing if configured correctly. See Running NixOS in a VM for more details on running NixOS in a Secureblue VM for additional security.

It’s crucial to document every change you make. By creating smaller, feature-complete commits, each with a descriptive message, you’re building a clear history. This approach makes it far simpler to revert a breaking change and quickly identify what went wrong. Over time, this discipline allows you to create security-focused checklists and ensure all angles are covered, building a more robust and secure system.

Don’t rely on single solutions or products, develop processes and defense in depth. Think ahead and fail securely so that a single failure doesn’t mean total insecurity.

Attackers often monitor the latest Linux CVEs (Common Vulnerabilities and Exposures) and check if and when specific distributions like NixOS have implemented fixes. The unstable branch will receive the security patches and fixes faster than stable which is another thing to keep in mind.

Check out the Hardening NixOS Baseline Hardening README for baseline hardening recommendations and best practices.

There is something to be said about the window manager you use. GNOME, KDE Plasma, and Sway secure privileged Wayland protocols like screencopy. This means that on environments outside of GNOME, KDE, and Sway, applications can access screen content of the entire desktop. This implicitly includes the content of other applications. It’s primarily for this reason that Silverblue, Kinoite, Sericea, and COSMIC images are recommended. ~~COSMIC has plans to fix this.~~ –secureblue Images

This is a little misleading, hyprland takes a different approach that also works. Disabling wlroots portal does not block screencopy for all apps, but only with sandboxed clients. Unsandboxed apps (like grim) can still access ext-image-copy-capture directly on Sway without going through the portal.

Hyprland Permissions

For example, to disable Xwayland for sway on home-manager you would add:

wayland.windowManager.sway = {
  enable = true;
  extraConfig = ''
    xwayland disable
  '';
}

You may get an error saying you’re only able to disable xwayland at boot, restart your system and you’ll be all set.

You can explicitly disable xdg-desktop-portal-wlr with systemd in your configuration.nix like this:

# configuration.nix
systemd.user.services."xdg-desktop-portal-wlr" = {
  enable = false;  # Masks/stops the wlr service
};
xdg.portal.wlr.enable = false;

Common Attack Vectors for Linux

✔️ Common Attack Vectors in Linux

Privilege escalation: The unauthorized act of gaining elevated permissions rather than legitimate, controlled privilege use. It’s a very common tactic that threat actors use to take over a system, steal data, delete files, and more.

Processes to protect against Privilege escalation

Adopt the principle of least privilege, only giving users the permissions that they require to perform their duties.
Harden your system: Minimize the attack surface, use strong passwords, and follow best practices.
Monitor relevant sources such as the NIST National Vulnerability Database, NixOS Security Advisories, and NixOS Discourse Security So you’ll know the latest CVEs and vulnerabilities in Linux and NixOS.
While not made for NixOS the linPEAS Privilege Escalation Awesome Script gives you some useful info such as active capabilities and potential risks.
Remove unnecessary SUID binaries to reduce the attack surface.

Use after Free/Double free:

Use-After-Free (UAF) is a type of software vulnerability that occurs in memory unsafe languages (C C++) when a program continues to use a memory location after it has been freed or deallocated.

Double free: is a flaw where a program frees the same memory block twice using free() or delete, leading to undefined behavior and potential exploitation.

Mitigation techniques include the use of hardened allocators such as hardened_malloc, which improve memory management to detect and prevent UAF and double-free bugs. Recent versions of glibc also incorporate built-in checks to catch double frees.

Unauthorized Access:

Unauthorized access is the entry or use of your system, networks, or data by individuals without permission. It’s a common way for adversaries to exfiltrate data, execute malicious code, and cause damage.

Protections against Unauthorized Access

Strong Passwords, MFA, and robust Secrets management. In 2025, 22% of breaches involved stolen credentials overall; in basic web app attacks, 88% used stolen credentials. –StrongDM data-breach-statistics
Close unused ports with a Firewall
Encrypt data in transit and at rest
Watch your Logs, and deploy intrusion detection systems such as AIDE.
SQL Injection CWE, SQL injection is the most common critical web application vulnerability.
Cross Site Scripting (XSS)

Misconfiguration

With many new users trying NixOS, misconfiguration is common and an easy way for an attacker to gain control over your system.
It is recommended to start slowly and try to ensure that you understand your configuration. Avoid copy-pasting config files that you don’t understand yet.

Zero Day Exploits:

The term “Zero-Day” refers to a security vulnerability or flaw that is unknown to the software developers or security teams, meaning they have had zero days to create a patch or fix for it. This term is often associated with concepts such as Vulnerabilities, Exploits, and Threats, and it’s important to distinguish among them:

A Zero-Day Vulnerability is a previously undiscovered security weakness or flaw in software that malicious actors can exploit.
A Zero-Day Exploit describes the specific method or technique attackers use to take advantage of that vulnerability to compromise a system.
A Zero-Day Attack happens when malicious actors launch an attack using a zero-day exploit before the software vendor has had a chance to patch or fix the vulnerability.
Project Zero’s 0day spreadsheet. You’ll see that a majority of zero-days are Memory Corruption bugs.
Zero-Day tracking project
Trend Micro’s zero day inituative

Minimal Installation with LUKS

Begin with NixOS’s minimal installation image. This gives you a base system with only essential tools and no extras that could introduce vulnerabilities.

NixOS’s declarative model makes auditing the installed packages and services easy, do so regularly.

Manual Encrypted Install Following the Manual

Encryption is the process of using an algorithm to scramble plaintext data into ciphertext, making it unreadable except to a person who has the key to decrypt it.

Data at rest is data in storage, such as a computer’s or a servers hard disk.

Data at rest encryption (typically hard disk encryption), secures the documents, directories, and files behind an encryption key. Encrypting your data at rest prevents data leakage, physical theft, unauthorized access, and more as long as the key management scheme isn’t compromised.

Minimal ISO Download (64-bit Intel/AMD)
NixOS Manual Installation
NixOS Wiki Full Disk Encryption
The NSA, CISA, and NIST warn that nation-state actors are likely stockpiling encrypted data now, preparing for a future when quantum computers could break today’s most widely used encryption algorithms. Sensitive data with long-term secrecy needs is especially at risk.
NSA/CSS Preparing for Post-Quantum
This is a wake-up call to use the strongest encryption available today and to plan early for post-quantum security.
NIST First 3 Post-Quantum Encryption Standards Organizations and individuals should prepare to migrate cryptographic systems to these new standards as soon as practical.
They chose Four Quantum-Resistant Cryptographic Algorithms warning that public-key cryptography is especially vulnerable and widely used to protect digital information.

Guided Encrypted BTRFS Subvol install using disko

Use LUKS encryption to protect your data at rest, the following guide is a minimal disko encrypted installation: Encrypted Install

Installing Software

Nixpkgs cooldowns, this is a great addition after all of the AUR compromises. “nixpkgs-weekly still updates once a week, but deliberately introduces a seven-day “cooldown” period, updating to a new revision of Nixpkgs released by upstream only after seven days have elapsed. This introduces a buffer period where major vulnerabilities or attacks can be identified prior to it arriving in our users’ hands.“
Checkout cooldowns.dev for more info on cooldowns.

The 2025 Edgescan study examined full-stack applications and found that one-third contained critical or severe vulnerabilities, putting them at risk. Over 45% of large enterprises leave unresolved vulnerabilities for more than a year. This shows the necessity of containing your apps in sandboxes when possible. –edgescan Vulnerability Report

⚠️ For system security it is strongly advised to not install proprietary, non-freedom software. Instead, use of Free Software is recommended –Kicksecure

Proprietary Software is Often Malware NOTE: While I respect the importance of software freedom, I choose to focus on practical, technical solutions rather than engage with the ideological tone often present in related advocacy.

# configuration.nix
nixpkgs.config.allowUnfree = false;

To explicitly disable it for flakes:

# ...snip...
pkgs = import nixpkgs {
  system = "x86_64-linux";
  config = {
    allowUnfree = false;
  };
};
# ...snip...

Most users don’t fully understand that running any software without sandboxing gives it unrestricted access to their user data and system resources. There is a widespread lack of awareness that Linux apps generally run with the full permissions of the user. It’s easy to overlook the fact that “trusted source” doesn’t mean “safe to run uncontained”. –summarized from kicksecure docs

Pre-Install Recommendations

NixOS Security

When installing software, first check search.nixos, and follow the Homepage link to ensure that said package is maintained.

For example, when I search for doas, and go to the Homepage link, I can see that the most recent commit was made 3 years ago. For certain software this might not be an issue but doas isn’t one of them.

Looking at the sudo-rs Homepage I can see that it was updated yesterday (11-19-25) and might be a better alternative. It’s maintained and written in a memory safe language.

For critical apps like sudo, you should also check for vulnerabilities in said software. If you did so for sudo-rs, you’d see CVE-2025-64170 and see that it’s been patched. You can then look at the sudo-rs package.nix to ensure that the versions match. (As of 11-20-25 they match).

nixpkgs-unstable Security Overview

nixpkgs-unstable tracks the master branch of the Nixpkgs repo and is constantly updated.
This branch gets security updates faster, patching vulnerabilities faster.
Since it’s a rolling-release, packages are less thoroughly tested. This increases the risk of new, undiscovered bugs or regressions. Some of which could have security implications.
The packages are generally the most recent upstream versions, which is important for security-sensitive software like browsers and kernels, as old versions may have publicly known, unpatched vulnerabilities.
As the name states, nixpkgs-unstable is less stable and an update is more likely to cause your system to fail to build due to breaking changes in Nix expressions.
I personally use unstable for everything, but I don’t mind having to fix issues that arise.

Stable (e.g., nixos-24.05) Security Overview

Stable Nixpkgs channels correspond to point release (e.g., released every 6 months) and are supported for a limited period (typically one month past the next release).

Stable channels generally only receive conservative bug and security fixes. Major version bumps for features are typically avoided to maintain “stability against deliberate changes”, which means you won’t get the latest upstream features or general bug fixes.
While critical security updates are backported quickly, updates for less critical packages may be slower or not happen at all if they require a significant refactoring or version bump.
Stable channels are generally more stable, meaning updates are less likely to introduce breaking changes to your configuration or system environment.
Many packages will be older versions. If a critical security vulnerability requires a major upstream version update (which is often avoided in a stable channel), the maintainers must backport the patch, a process which can introduce its own set of risks and delays.

What should you use?

The primary security trade-off is between patching speed for known vulnerabilities and stability/exposure to new bugs:

Choose unstable if you prioritize getting the latest security fixes (especially for end-user apps like browsers) as soon as they are available upstream, accepting a higher risk of non-security-related system breakage or new, undiscovered bugs.
Choose stable if you prioritize system predictability and stability, relying on dedicated backports for critical vulnerabilities, while accepting that non-critical security and bug fixes will be delayed or absent until the next major release.

A common hybrid approach is to use the stable channel as the base for the OS and selectively pin specific packages from unstable to ensure they receive rapid security updates.

With flakes it’s easy to add both stable and unstable as flake inputs and access each with some simple logic.

✔️ Click to Expand Flake example using both stable & unstable

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

 inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-25.05";
    nixpkgs-unstable.url = "github:NixOS/nixpkgs/nixos-unstable";
  };

  outputs =
    { nixpkgs, nixpkgs-unstable, ... }:
    {
      nixosConfigurations."your-host" = 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
        ];
      };
    };
}

This is also how you enable unfree packages for flakes rather than in your configuration.nix.

Now you can specify which packages are to be installed with which channel like so:

# configuration.nix
{ pkgs, ... }:
{
  environment.systemPackages = [
    pkgs.firefox
    pkgs.unstable.helix
  ];
  # ...
}

Users and SUID Binaries

Replacing sudo with run0

The point here is to avoid using the setuid binary (sudo), run0 is a wrapper over systemd-run which speaks over Inter-process Communication Mechanisms (IPC) to PID1 which is considered safer than running a setuid binary. We separate our daily user from administration tasks and authenticate through our admin account. This reduces the attack surface by removing sudo as well as reduces the risk of local privilege escalation.

IPC is the mechanism that allows processes to communicate. There are two methods of IPC, shared memory and message passing. An OS can implement both.
PID 1 is the first userspace process the kernel starts (the init system), which becomes the ancestor and reaper of all other processes; because it runs as root, is always present, and controls the system lifecycle, any bugs or design issues in PID 1 have outsized security impact and can translate into system-wide compromise or denial of service.

Click to Expand SUID and run0 resources

run0 explained by Lennart
setuid Wikipedia
Using run0 removes of these classes of attacks
The following lists some of the downsides kicksecure vs secureblue

run0 is not a SUID, it asks the service manager to invoke a command or shell under the target user’s UID. The target command is invoked in an isolated exec context, freshly forked off PID1 without inheriting any context from the client.

The core danger of setuid (Set User ID) lies in its ability to allow a low-privilege user to execute a program with the permissions of the file’s owner, which is most often the powerful root user.

💥 The Danger of setuid

For granting limited, controlled privilege escalation to apps, the primary choices are broadly between traditional setuid/setgid permissions and more modern Linux capabilities. Jump to Capabilities

Understanding setuid/setgid

Use the following command to find all SUID binaries:

sudo find / -perm -4000 -type f -ls 2>/dev/null

The setuid permission is dangerous because it creates a privilege escalation pathway that can be exploited for malicious purposes.

Temporary Root Access: When a file has the setuid bit set and is owned by root, any user who executes that program instantly and temporarily gains the full power of the root user while the program runs.
If a setuid program (such as passwd, or sudo) contain a security flaw, such as a buffer overflow (Common in C) or improper input validation, an attacker can exploit the flaw.
Since the program is running with root privileges, the attacker can execute shell code or commands with root access, completely compromising the entire system.

Normally the root user (UID 0) gets unrestricted access to almost everything on the entire system.

I rebuild/update way too often to completely separate the accounts and allow no admin tasks for my daily user. That may be a better option for servers, etc.

Create an admin user for administrative tasks and remove your daily user from the wheel group, and disable the sudo, su, and pkexec SUIDs:

(Edited: 2026-02-01): Changed from disabling the setuid bits to disabling the wrapper entirely. Caught by SuperSandro2000

{ config, pkgs, lib }:
{
users.users.admin = {
    isNormalUser = true;
    description  = "System administrator";
    extraGroups  = [ "wheel" ];   # wheel = sudo
    # run `mkpasswd --method=yescrypt` and replace "changeme" w/ the result
    initialHashedPassword = "changeme";           # change with `passwd admin` later
    openssh.authorizedKeys.keys = [
      # (optional) paste your SSH public key here
      # "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI..."
    ];
  };
    users.groups.admin = {};
    users.mutableUsers = false;

  # --------------------------------------------------------------------
  # 2. Existing daily user – remove from wheel, keep everything else
  # --------------------------------------------------------------------
  users.users.daily = {
    isNormalUser = true;
    description  = "Daily driver account";
    extraGroups  = lib.mkForce [ "networkmanager" "audio" "video" ]; # keep useful groups
    initialHashedPassword = "changeme";
    # Remove `wheel` by *not* listing it (mkForce overrides any default)
  };
  users.groups.daily = {};

security = {
# alias sudo = 'run0'
run0.enableSudoAlias = true;
polkit.enable = true;
# Disable sudo
sudo.enable = false;
wrappers = {
    su.enable = lib.mkForce false;
    sudoedit.enable = lib.mkForce false;
    sg.enable = lib.mkForce false;
    fusermount.enable = lib.mkForce false;
    fusermount3.enable = lib.mkForce false;
    pkexec.setuid = lib.mkForce false;
    newgrp.setuid = lib.mkForce false;
    newgidmap.setuid = lib.mkForce false;
    newuidmap.setuid = lib.mkForce false;
    # `mount` Needed for `fileSystems.options`
    # mount.enable = lib.mkForce false;
    # Optional: if you disable mount, disable umount as well
    # umount.enable = lib.mkForce false;
};
# Or hyprlock, required for swaylock to accept your password
pam.services.swaylock = {
  text = ''
    auth include login
    account include login
    password include login
    session include login
  '';
  };
};

The security.wrappers... removes the setuid bit making the commands unusable removing the SUID vulnerabilities for su and pkexec. You can find the other SUID wrappers in /run/wrappers/bin/, such as fusermount and more.

SUID’s that can be disabled:

umount: Allows unprivileged users to unmount devices listed in your fstab.
mount: Same as above but for mounting. It is recommended to set fileSystems."/boot".options = [ "fmask=0077" "dmask=0077" ]; this won’t work without mounts setuid.
sg: Executes a command as a different group.
mtr-packet: Used by mtr to create network sockets.
fusermount, fusermount3: Allows unprivileged users to mount FUSE filesystems. Can be disabled if you don’t use FUSE (e.g., Appimages, etc.)
newuidmap, newgidmap: Used for user namespace creation (Often used for unprivileged containers). (Disable if you don’t use unprivileged containers/namespaces)

Never Disable:

unix_chkpwd: This is a core PAM helper to securely check user passwords against the root-readable /etc/shadow.

Check again which SUID binaries are active:

sudo find / -perm -4000 -type f -ls 2>/dev/null
# Example
-rwsr-xr-x  root  root  /run/wrappers/bin/fusermount
   ^-- This 's' means setuid bit is set

ls -la /run/wrappers/bin/
# Or
find /run/wrappers -perm -4000 -ls

Only enable the wrappers you actually use!

You will have to use run0 to authenticate your daily user, for example:

run0 nixos-rebuild switch --flake .

Since run0 doesn’t cache results and nixos-rebuild calls on Polkit 3 times, so on every rebuild, you will be asked for your password 3 times which isn’t ideal. I found the following workaround that will only ask for your password once.

Add the following to your configuration.nix, replacing user-name with your username:

 security.polkit.extraConfig = ''
     polkit.addRule(function(action, subject) {
       if (subject.user == "user-name") {
         if (action.id.indexOf("org.nixos") == 0) {
           polkit.log("Caching admin authentication for single NixOS operation");
           return polkit.Result.AUTH_ADMIN_KEEP;
         }
       }
     });
   '';

Create a zsh function for easy access:

# zsh.nix
#...snip...
initContent = ''
  fr() {
    run0 nixos-rebuild switch --flake "/home/$USER/flake#"$(hostname)
  }
'';

Needless to say, this is less secure but much more convenient than entering your password 3 times on every single rebuild.

Without the pam settings for swaylock, it won’t accept your password to log back in.

run0 Usage Example

When you are in a privileged shell, run0 changes the color of the background to red to remind you of this.

Example creating a user:

run0
adduser admin
usermod -aG wheel admin
passwd admin
exit
reboot

This is just an example, since we manage our users declaratively the user created would be discarded on the next rebuild because of the users.mutableUsers = false; setting. You could of course change this to true to manage your users imperatively but I don’t recommend it.

Capabilities

✔️ Click to expand capabilities examples

One way to help get rid of setuid binaries is to replace them with capabilities. I personally only remove the SUID bit and don’t try to replace with capabilities as of now. You can still use the commands from security.wrappers such as run0 su -.

Capabilities provide a subset of what is available to root to a process. This breaks up root privileges into smaller units that can independently grant access to processes. This reduces the full set of privileges, decreasing the risk of exploitation.

(This is just an example):

{
  # a setuid root program
  doas =
    { setuid = true;
      owner = "root";
      group = "root";
      source = "${pkgs.doas}/bin/doas";
    };

  # a setgid program
  locate =
    { setgid = true;
      owner = "root";
      group = "mlocate";
      source = "${pkgs.locate}/bin/locate";
    };

  # a program with the CAP_NET_RAW capability
  ping =
    { owner = "root";
      group = "root";
      capabilities = "cap_net_raw+ep";
      source = "${pkgs.iputils.out}/bin/ping";
    };
}

List the highest capability number for your kernel with:

cat /proc/sys/kernel/cap_last_cap
# Output:
40

List available Linux capabilities:

capsh --print

List processes:

ps
# Example Output
PID    TTY     TIME   CMD
8063   pts/1    02     zsh

cat /proc/8063/status | grep Cap
# Output
CapInh: 0000000800000000
CapPrm: 0000000000000000
CapEff: 0000000000000000
CapBnd: 000001ffffffffff
CapAmb: 0000000000000000

capsh --decode=000001ffffffffff
# Output
0x000001ffffffffff=cap_chown,cap_dac_override,cap_dac_read_search,cap_fowner,cap_fsetid,cap_kill,cap_setgid,cap_setuid,cap_setpcap,cap_linux_immutable,cap_net_bind_service,cap_net_broadcast,cap_net_admin,cap_net_raw,cap_ipc_lock,cap_ipc_owner,cap_sys_module,cap_sys_rawio,cap_sys_chroot,cap_sys_ptrace,cap_sys_pacct,cap_sys_admin,cap_sys_boot,cap_sys_nice,cap_sys_resource,cap_sys_time,cap_sys_tty_config,cap_mknod,cap_lease,cap_audit_write,cap_audit_control,cap_setfcap,cap_mac_override,cap_mac_admin,cap_syslog,cap_wake_alarm,cap_block_suspend,cap_audit_read,cap_perfmon,cap_bpf,cap_checkpoint_restore

cap_net_raw: Allows the program to use raw and unbuffered network sockets, which is what ping and mtr-packet need to send ICMP packets.

cap_sys_admin: Grants a variety of system administration operations, including the ability to perform FUSE mounts. This is a powerful capability, but it’s still more restrictive than full root SUID.

+ep: This is crucial. It stands for:
- e (Effective): The set of capabilities actually used by the process when running.
- p (Permitted): The set of capabilities that can be enabled by the process.

By using this approach, you are following the security principle of least privilege, significantly reducing the attack surface compared to traditional SUID binaries.

Impermanence

Impermanence, especially when using a tmpfs as the root filesystem, provides several significant security benefits. The core principle is that impermanence defeats persistence, a fundamental goal for any attacker.

When you use a root-as-tmpfs setup on NixOS, the boot process loads the entire operating system from the read-only Nix store into a tmpfs in RAM. The mutable directories, such as /etc and /var, are then created on this RAM disk. When the system is shut down, the tmpfs is wiped, leaving the on-disk storage untouched and secure.

This means you get a fresh, secure boot every time, making it much harder for an attacker to maintain a presence on your system.

Erase your Darlings (ZFS)
Encrypted BTRFS Impermanence Guide Only follow this guide if you also followed the encrypted disko install, impermanence is designed to be destructive and needs to match your config exactly.

Replace timesyncd with a chron job that enables Network Time Security (NTS)

This is implementing the GrapheneOS/secureblue NTS chrony settings to NixOS:

{ config
, ...
}:
{
  services.chrony = {
    enable = true;
    enableNTS = true;
    servers = [
        "server time.cloudflare.com iburst nts"
        "server ntppool1.time.nl iburst nts"
        "server nts.netnod.se iburst nts"
        "server ptbtime1.ptb.de iburst nts"
        "server time.dfm.dk iburst nts"
        "server time.cifelli.xyz iburst nts"
     ];
    # havent worked out the kinks yet
  #  extraConfig = ''
  #      minsources 3
  #      authselectmode require

  #      # EF
  #      dscp 46

  #      driftfile /var/lib/chrony/drift
  #      dumpdir /var/lib/chrony
  #      ntsdumpdir /var/lib/chrony

  #      leapseclist /usr/share/zoneinfo/leap-seconds.list
  #      makestep 1.0 3

  #      rtconutc

  #      cmdport 0

  #      noclientlog
  #  '';
  };
}

Ensure NTS is being used with:

sudo chronyc -N authdata

Secure Boot

Enable a UEFI password or Administrator password where it requires authentication in order to access the UEFI/BIOS.

Secure Boot helps ensure only signed, trusted kernels and bootloaders are executed at startup.

Useful Resources:

✔️ Click to Expand Secure Boot Resources

Practical Lanzaboote Secure Boot setup for NixOS: Guide:Secure Boot on NixOS with Lanzaboote

The Kernel

The Kernel Self Protection Project:

KSPP Recommended_Settings

Given the kernel’s central role, it’s a frequent target for malicious actors, making robust hardening essential.

NixOS provides a hardened profile that applies a set of security-focused kernel and system configurations.

For flakes, you could do something like the following in your configuration.nix or equivalent to import hardened.nix and enable profiles.hardened:

# configuration.nix
{ pkgs, inputs, ... }: let
   modulesPath = "${inputs.nixpkgs}/nixos/modules";

in {
  imports = [ "${modulesPath}/profiles/hardened.nix" ];

}

There is a proposal to remove it completely that has gained ground, the following thread discusses why: Discourse Thread
PR #383438 Proposed removal PR.
Check hardened.nix to see exactly what adding it enables to avoid duplicates and conflicts moving on. I included this for completeness, the choice is yours if you want to use it or not.

Choosing your Kernel

See which kernel you’re currently using with:

# show the kernel release
uname -r
# show kernel version, hostname, and architecture
uname -a

Show the configuration of your current kernel:

zcat /proc/config.gz
# ...snip...
#
# Compression
#
CONFIG_CRYPTO_DEFLATE=m
CONFIG_CRYPTO_LZO=y
CONFIG_CRYPTO_842=m
CONFIG_CRYPTO_LZ4=m
CONFIG_CRYPTO_LZ4HC=m
CONFIG_CRYPTO_ZSTD=y
# end of Compression
# ...snip...

The NixOS Manual states that the default Linux kernel configuration should be fine for most users.

The Linux kernel is typically released under two forms: stable and long-term support (LTS). Choosing either has consequences, do your research. Stable vs. LTS kernels

The Linux Kernel Archives Active kernel releases

OR, you can choose the hardened kernel for a kernel that prioritizes security over everything else.

The Hardened Kernel

Expect breakage when using the hardened kernel. linux-hardened completely disables unprivileged user namespaces, which are required for Flatpak, chromium-based browsers, and more.

The linuxPackages_latest_hardened attribute has been deprecated. If you want to use a hardened kernel, it is now recommended to use linux_hardened, which is aliased to linux_default.kernel.

You can find the latest available hardened kernel packages by searching pkgs/top-level/linux-kernels.nix.

It is recommended to use linux_hardened without specifying a version, such as:

boot.kernelPackages = pkgs.linuxPackages_hardened;

linux_hardened is aliased to the linux_default.kernel.

Note that this not only replaces the kernel, but also packages that are specific to the kernel version, such as NVIDIA video drivers. This also removes your ability to use the .extend kernel attribute, they are only available to kernel package sets (e.g., linuxPackages_hardened)

If you decide to use this, read further before rebuilding.

You can inspect nixpkgs/pkgs/os-specific/linux/kernel/hardened/patches.json to see the metadata of the patches that are applied. You can then follow the links in the .json file to see the patch diffs.

sysctl

A tool for checking the security hardening options of the Linux kernel:

environment.systemPackages = [ pkgs.kernel-hardening-checker ];

sysctl is a tool that allows you to view or modify kernel settings and enable/disable different features.

Check all sysctl parameters against the kernel-hardening-checker recommendations:

sudo sysctl -a > params.txt
kernel-hardening-checker -l /proc/cmdline -c /proc/config.gz -s ./params.txt

Check the value of a specific parameter:

sudo sysctl -a | grep "kernel.kptr_restrict"
# Output:
kernel.kptr_restrict = 2

Check Active Linux Security Modules:

cat /sys/kernel/security/lsm
# Output:
File: /sys/kernel/security/lsm
capability,landlock,yama,bpf,apparmor

Check Kernel Configuration Options:

zcat /proc/config.gz | grep CONFIG_SECURITY_SELINUX
zcat /proc/config.gz | grep CONFIG_HARDENED_USERCOPY
zcat /proc/config.gz | grep CONFIG_STACKPROTECTOR

Since it is difficult to see exactly what enabling the hardened_kernel does. Before rebuilding, you could do something like this to see exactly what is added:

sudo sysctl -a > before.txt

And after the rebuild:

sudo sysctl -a > after.txt

And finally run a diff on them:

diff before.txt after.txt

You can also diff against after.txt for future changes to avoid duplicates, this seems easier to me than trying to parse through the patches.

Kernel Security Settings

security = {
      protectKernelImage = true;
      lockKernelModules = false; # this breaks iptables, wireguard, and virtd

      # force-enable the Page Table Isolation (PTI) Linux kernel feature
      forcePageTableIsolation = true;

      # User namespaces are required for sandboxing.
      # this means you cannot set `"user.max_user_namespaces" = 0;` in sysctl
      allowUserNamespaces = true;

      # Disable unprivileged user namespaces, unless containers are enabled
      unprivilegedUsernsClone = config.virtualisation.containers.enable;
      allowSimultaneousMultithreading = true;
}

Further Hardening with sysctl

sysctl hardening settings further reinforce kernel-level protections. The hardened kernel includes security patches and stricter defaults, but it doesn’t cover all runtime tunables. Refer to the above commands to get a diff of the changes.

boot.kernel.sysctl: Runtime parameters of the Linux kernel, as set by sysctl(8). Note that the sysctl parameters names must be enclosed in quotes. Values may be a string, integer, boolean, or null.

Check what each setting does sysctl-explorer

Refer to madadaidans-insecurities#sysctl-kernel for the following settings and their explainations.

Also see the Kernel Self Protection Projects sysctls

  boot.kernel.sysctl = {
    "fs.suid_dumpable" = 0;
    # prevent pointer leaks
    "kernel.kptr_restrict" = 2;
    # restrict kernel log to CAP_SYSLOG capability
    "kernel.dmesg_restrict" = 1;
    # Note: certian container runtimes or browser sandboxes might rely on the following
    # restrict eBPF to the CAP_BPF capability
    "kernel.unprivileged_bpf_disabled" = 1;
    # should be enabled along with bpf above
    # "net.core.bpf_jit_harden" = 2;
    # restrict loading TTY line disciplines to the CAP_SYS_MODULE
    "dev.tty.ldisk_autoload" = 0;
    # prevent exploit of use-after-free flaws
    "vm.unprivileged_userfaultfd" = 0;
    # kexec is used to boot another kernel during runtime and can be abused
    "kernel.kexec_load_disabled" = 1;
    # Kernel self-protection
    # SysRq exposes a lot of potentially dangerous debugging functionality to unprivileged users
    # 4 makes it so a user can only use the secure attention key. A value of 0 would disable completely
    "kernel.sysrq" = 4;
    # disable unprivileged user namespaces, Note: Docker, NH, and other apps may need this
    # "kernel.unprivileged_userns_clone" = 0; # Set to 1 because it makes NH and other programs fail
    # This should be set to 0 if you don't rely on flatpak, NH, Docker, etc.
    "kernel.unprivileged_userns_clone" = 1;
    # restrict all usage of performance events to the CAP_PERFMON capability
    "kernel.perf_event_paranoid" = 3;

    # Network
    # protect against SYN flood attacks (denial of service attack)
    "net.ipv4.tcp_syncookies" = 1;
    # protection against TIME-WAIT assassination
    "net.ipv4.tcp_rfc1337" = 1;
    # enable source validation of packets received (prevents IP spoofing)
    "net.ipv4.conf.default.rp_filter" = 1;
    "net.ipv4.conf.all.rp_filter" = 1;

    "net.ipv4.conf.all.accept_redirects" = 0;
    "net.ipv4.conf.default.accept_redirects" = 0;
    "net.ipv4.conf.all.secure_redirects" = 0;
    "net.ipv4.conf.default.secure_redirects" = 0;
    # Protect against IP spoofing
    "net.ipv6.conf.all.accept_redirects" = 0;
    "net.ipv6.conf.default.accept_redirects" = 0;
    "net.ipv4.conf.all.send_redirects" = 0;
    "net.ipv4.conf.default.send_redirects" = 0;

    # prevent man-in-the-middle attacks
    "net.ipv4.icmp_echo_ignore_all" = 1;

    # ignore ICMP request, helps avoid Smurf attacks
    "net.ipv4.conf.all.forwarding" = 0;
    "net.ipv4.conf.default.accept_source_route" = 0;
    "net.ipv4.conf.all.accept_source_route" = 0;
    "net.ipv6.conf.all.accept_source_route" = 0;
    "net.ipv6.conf.default.accept_source_route" = 0;
    # Reverse path filtering causes the kernel to do source validation of
    "net.ipv6.conf.all.forwarding" = 0;
    "net.ipv6.conf.all.accept_ra" = 0;
    "net.ipv6.conf.default.accept_ra" = 0;

    ## TCP hardening
    # Prevent bogus ICMP errors from filling up logs.
    "net.ipv4.icmp_ignore_bogus_error_responses" = 1;

    # Userspace
    # restrict usage of ptrace
    "kernel.yama.ptrace_scope" = 2;

    # ASLR memory protection (64-bit systems)
    "vm.mmap_rnd_bits" = 32;
    "vm.mmap_rnd_compat_bits" = 16;

    # only permit symlinks to be followed when outside of a world-writable sticky directory
    "fs.protected_symlinks" = 1;
    "fs.protected_hardlinks" = 1;
    # Prevent creating files in potentially attacker-controlled environments
    "fs.protected_fifos" = 2;
    "fs.protected_regular" = 2;

    # Randomize memory
    "kernel.randomize_va_space" = 2;
    # Exec Shield (Stack protection)
    "kernel.exec-shield" = 1;

    ## TCP optimization
    # TCP Fast Open is a TCP extension that reduces network latency by packing
    # data in the sender’s initial TCP SYN. Setting 3 = enable TCP Fast Open for
    # both incoming and outgoing connections:
    "net.ipv4.tcp_fastopen" = 3;
    # Bufferbloat mitigations + slight improvement in throughput & latency
    "net.ipv4.tcp_congestion_control" = "bbr";
    "net.core.default_qdisc" = "cake";
  };

❗ Note: The above settings are fairly aggressive and can break common programs, read the comment warnings.

Hardening Boot Parameters

boot.kernelParams can be used to set additional kernel command line arguments at boot time. It can only be used for built-in modules.

You can find the following settings in the Boot parameters section

# boot.nix
      boot.kernelParams = [
        # make it harder to influence slab cache layout
        "slab_nomerge"
        # enables zeroing of memory during allocation and free time
        # helps mitigate use-after-free vulnerabilaties
        "init_on_alloc=1"
        "init_on_free=1"
        # randomizes page allocator freelist, improving security by
        # making page allocations less predictable
        "page_alloc.shuffel=1"
        # enables Kernel Page Table Isolation, which mitigates Meltdown and
        # prevents some KASLR bypasses
        "pti=on"
        # randomizes the kernel stack offset on each syscall
        # making attacks that rely on a deterministic stack layout difficult
        "randomize_kstack_offset=on"
        # disables vsyscalls, they've been replaced with vDSO
        "vsyscall=none"
        # disables debugfs, which exposes sensitive info about the kernel
        "debugfs=off"
        # certain exploits cause an "oops", this makes the kernel panic if an "oops" occurs
        "oops=panic"
        # only alows kernel modules that have been signed with a valid key to be loaded
        # making it harder to load malicious kernel modules
        # can make VirtualBox or Nvidia drivers unusable
        "module.sig_enforce=1"
        # prevents user space code excalation
        "lockdown=confidentiality"
        # "rd.udev.log_level=3"
        # "udev.log_priority=3"
      ];

This is a thoughtful start to hardening boot parameters, there are more recommendations in the guide.

Kernel modules for hardware devices are generally loaded automatically by udev. You can force a module to be loaded via boot.kernelModules.

Hardening Modprobe

You can use both extraModprobeConfig & blacklistedKernelModules to disable different features. If you prefer, you can place these in the next section as well.

boot.extraModprobeConfig = ''
     # firewire and thunderbolt
    install firewire-core /bin/false
    install firewire_core /bin/false
    install firewire-ohci /bin/false
    install firewire_ohci /bin/false
    install firewire_sbp2 /bin/false
    install firewire-sbp2 /bin/false
    install firewire-net /bin/false
    install thunderbolt /bin/false
    install ohci1394 /bin/false
    install sbp2 /bin/false
    install dv1394 /bin/false
    install raw1394 /bin/false
    install video1394 /bin/false
'';
# OR
#boot.blacklistedKernelModules = [
#  "firewire-core"
#  # ... snip ...
#];

Blacklisting Kernel Parameters

Blacklisting unused kernel modules reduces the attack surface.

boot.blacklistedKernelModules: List of names of kernel modules that should not be loaded automatically by the hardware probing code.

You can find the following settings in the Blacklisting Kernel Modules Section

      boot.blacklistedKernelModules = [
        # Obscure networking protocols
        "dccp"   # Datagram Congestion Control Protocol
        "sctp"  # Stream Control Transmission Protocol
        "rds"  # Reliable Datagram Sockets
        "tipc"  # Transparent Inter-Process Communication
        "n-hdlc" # High-level Data Link Control
        "ax25"  # Amateur X.25
        "netrom"  # NetRom
        "x25"     # X.25
        "rose"
        "decnet"
        "econet"
        "af_802154"  # IEEE 802.15.4
        "ipx"  # Internetwork Packet Exchange
        "appletalk"
        "psnap"  # SubnetworkAccess Protocol
        "p8023"  # Novell raw IEE 802.3
        "p8022"  # IEE 802.3
        "can"   # Controller Area Network
        "atm"
        # Various rare filesystems
        "cramfs"
        "freevxfs"
        "jffs2"
        "hfs"
        "hfsplus"
        "udf"

        # "squashfs"  # compressed read-only file system used for Live CDs
        # "cifs"  # cmb (Common Internet File System)
        # "nfs"  # Network File System
        # "nfsv3"
        # "nfsv4"
        # "ksmbd"  # SMB3 Kernel Server
        # "gfs2"  # Global File System 2
        # vivid driver is only useful for testing purposes and has been the
        # cause of privilege escalation vulnerabilities
        # "vivid"
      ];

As with the kernelParameters above, there are more suggestions in the guide, I have used the above parameters along with the commented out ones and had no issues.

Also see SecureBlue’s blacklist.conf for more ideas.

Hardened Memory Allocator

There is a performance cost to enabling a hardened memory allocator, and some apps will not work without a workaround such as Firefox, Thunderbird, Torbrowser, LibreWolf, and ZenBrowser to name a few.

With memory corruption bugs being the leading zero day category, it’s clearly something that you should be concerned with.

The grapheneOS hardened_malloc is available for NixOS in two variants, add either to your configuration.nix or equivalent to apply them:

environment.memoryAllocator.provider = "graphene-hardened";: This is the default configuration template that has all normal optional security features enabled. It’s aggressive, you can expect app breakage and a performance cost.
environment.memoryAllocator.provider = "graphene-hardened-light";: The light template disables the slap quarantines, write after free check, slot randomization and raises the guard slab interval from 1 to 8 but leaves zero-on-free and slab canaries enabled. This version has solid performance and is still far more secure than the standard allocator.

libhardened_malloc.so is typically installed to /usr/local/lib/libhardened_malloc.so and referenced from /etc/ld.so.preload.

Hardening Systemd

systemd is the core “init system” and service manager that controls how services, daemons, and basic system processes are started, stopped and supervised on modern Linux distributions, including NixOS. It provides a suite of basic building blocks for a Linux system as well as a system and service manager that runs as PID 1 and starts the rest of the system.

Stage 1 (initrd) is now based on systemd by default, the old scripted implimentation is deprecated.

Because it launches and supervises almost all system services, hardening systemd means raising the baseline security of your entire system.

Disable coredumps:

systemd.coredump.enable = false;
# ➡️ Sets the kernel's resource limit (ulimit -c 0)
  security.pam.loginLimits = [
    {
      domain = "*"; # Applies to all users/sessions
      type = "-"; # Set both soft and hard limits
      item = "core"; # The soft/hard limit item
      value = "0";   # Core dumps size is limited to 0 (effectively disabled)
    }
  ];

Disabling coredumps helps save space and improves security/privacy because when a program fails, a coredump contains an exact copy of a programs running memory at the time of the crash. This can inadvertently expose sensitive data.

If a program is handling private information when it crashes, the core dump file could contain:

Passwords: Stored in memory before being sent or hashed.
Encryption Keys: Used for securing network connections.
Personal Info: Chat messages, website forms, etc.

It can give a minor performance upgrade and does reduce the attack surface. If a malicious program were to gain access to your system, one of the first things it might look for are core dump files to extract sensitive data. By disabling them, you eliminate this potential source of information leakage.

~~dbus-broker is generally considered more secure and robust but isn’t the default as of yet.~~

dbus-broker is now the default, it’s faster and more reliable.

  users.groups.netdev = {};
  services = {
    dbus.implementation = "broker";
    logrotate.enable = true;
    journald = {
      storage = "volatile"; # Store logs in memory
      upload.enable = false; # Disable remote log upload (the default)
      extraConfig = ''
        SystemMaxUse=500M
        SystemMaxFileSize=50M
      '';
    };
  };

dbus-broker is more resilient to resource exhaustion attacks and integrates better with Linux security features.
Rethinking-the-dbus-message-bus
Setting storage = "volatile" tells journald to keep log data only in memory. There is a tradeoff though, If you need long-term auditing or troubleshooting after a reboot, this will not preserve system logs.
upload.enable is for forwarding log messages to remote servers, setting this to false prevents accidental leaks of potentially sensitive or internal system information.
Enabling logrotate prevents your disk from filling with excessive legacy/service log files. These are the classic plain-text logs.
Systemd uses journald which stores logs in a binary format

You can check the security status with:

systemd-analyze security
# or for a detailed view of individual services security posture
systemd-analyze security NetworkManager

Optionally disable vulnerable services to reduce the attack surface, obviously don’t disable what you need, or change your habits:

services = {
    # mDNS/DNS-SD
    avahi.enable = false;
    # Geoclue (location services)
    geoclue2.enable = false;
    udisks2.enable = false;
    accounts-daemon.enable = false;
  };
  # Only needed for WWAN/3G/4G modems, otherwise it runs `mmcli` unnecessarily
  networking.modemmanager.enable = false;
  # Bluetooth has a long history of vulnerabilities
  hardware.bluetooth.enable = false;
  # Prefer manual upgrades on a hardened system
  system.autoUpgrade.enable = false;

Lynis and other tools

Lynis is a security auditing tool for systems based on UNIX like Linux, macOS, BSD, and others.–lynis repo

chkrootkit was removed as it is unmaintained and archived upstream.

Installation:

environment.systemPackages = [
pkgs.lynis
pkgs.clamav
pkgs.aide
 ];

✔️ Click to Expand AIDE Example

AIDE is an intrusion detection system (IDS) that will notify us whenever it detects that a potential intrusion has occurred. When a system is compromised, attackers typically will try to change file permissions and escalate to the root user account and start to modify system files, AIDE can detect this.

To set up AIDE on your system follow these steps:

Create the aide.conf:

sudo mkdir -p /var/lib/aide && cd /var/lib/aide/
sudo hx aide.conf

Add the following content to /var/lib/aide/aide.conf:

# aide.conf
# Example configuration file for AIDE.

@@define DBDIR /var/lib/aide

# The location of the database to be read.
database_in=file:@@{DBDIR}/aide.db.gz

# The location of the database to be written.
#database_out=sql:host:port:database:login_name:passwd:table
#database_out=file:aide.db.new
database_out=file:@@{DBDIR}/aide.db.new.gz

# Whether to gzip the output to database
gzip_dbout=yes

log_level=info

report_url=file:/var/log/aide/aide.log
report_url=stdout
#report_url=stderr
#NOT IMPLEMENTED report_url=mailto:root@foo.com
#NOT IMPLEMENTED report_url=syslog:LOG_AUTH

# These are the default rules.
#
#p:      permissions
#i:      inode:
#n:      number of links
#u:      user
#g:      group
#s:      size
#b:      block count
#m:      mtime
#a:      atime
#c:      ctime
#S:      check for growing size
#md5:    md5 checksum
#sha1:   sha1 checksum
#rmd160: rmd160 checksum
#tiger:  tiger checksum
#haval:  haval checksum
#gost:   gost checksum
#crc32:  crc32 checksum
#R:      p+i+n+u+g+s+m+c+md5
#L:      p+i+n+u+g
#E:      Empty group
#>:      Growing logfile p+u+g+i+n+S

# You can create custom rules like this.

NORMAL = R+b+sha512

DIR = p+i+n+u+g

# Next decide what directories/files you want in the database.

/boot   NORMAL
/bin    NORMAL
/sbin   NORMAL
/lib    NORMAL
/opt    NORMAL
/usr    NORMAL
/root   NORMAL

# Check only permissions, inode, user and group for /etc, but
# cover some important files closely.
/etc    p+i+u+g
!/etc/mtab
/etc/exports  NORMAL
/etc/fstab    NORMAL
/etc/passwd   NORMAL
/etc/group    NORMAL
/etc/gshadow  NORMAL
/etc/shadow   NORMAL

/var/log   p+n+u+g

# With AIDE's default verbosity level of 5, these would give lots of
# warnings upon tree traversal. It might change with future version.
#
#=/lost\+found    DIR
#=/home           DIR

Create the logfile:

sudo mkdir -p /var/log/aide
sudo touch /var/log/aide/aide.log

Generate the initial database, this will store the checksums of all files that it’s configured to monitor. Take note of the location of the new database, mine was /etc/aide.db.new

sudo aide --config /var/lib/aide/aide.conf --init

Move the new database and remove the .new:

sudo mv /var/lib/aide/aide.db.new.gz /var/lib/aide/aide.db.gz

ls /var/lib/aide/
aide.conf   aide.db.gz

Check with AIDE:

sudo aide --check --config /var/lib/aide/aide.conf
Start timestamp: 2025-09-05 09:50:07 -0400 (AIDE 0.19.2)
AIDE found NO differences between database and filesystem. Looks okay!!

Whenever you make changes to system files, or especially after running a system update or installing new tools, you have to rescan all files to update their checksums in the AIDE database:

sudo aide --update --config /var/lib/aide/aide.conf

Unfortunately, AIDE doesn’t automatically replace the old database so you have to rename the new one again:

sudo mv /var/lib/aide/aide.db.new.gz /var/lib/aide/aide.db.gz

And finally check again:

sudo aide --check --config /var/lib/aide/aide.conf

aide(1) man page

✔️ Click to Expand clamav.nix Example

{pkgs, ...}: {
  environment.systemPackages = with pkgs; [
    clamav
  ];
  services.clamav = {
    # Enable clamd daemon
    daemon.enable = true;
    updater.enable = true;
    updater.frequency = 12; # Number of database checks per day
    scanner = {
      enable = true;
      # 4:00 AM
      interval = "*-*-* 04:00:00";
      scanDirectories = [
        "/home"
        "/var/lib"
        "/tmp"
        "/etc"
        "/var/tmp"
      ];
    };
  };
}

Lynis Usage:

sudo lynis show commands
# Output:
Commands:
lynis audit
lynis configure
lynis generate
lynis show
lynis update
lynis upload-only

sudo lynis audit system
# Output:
  Lynis security scan details:

  Hardening index : 79 [###############     ]
  Tests performed : 234
  Plugins enabled : 0

  Components:
  - Firewall               [V]
  - Malware scanner        [V]

  Scan mode:
  Normal [V]  Forensics [ ]  Integration [ ]  Pentest [ ]

  Lynis modules:
  - Compliance status      [?]
  - Security audit         [V]
  - Vulnerability scan     [V]

The “Lynis hardening index” is an overall impression on how well a system is hardened. However, this is just an indicator on measures taken - not a percentage of how safe a system might be. A score over 75 typically indicates a system with more than average safety measures implemented.
Lynis will give you more recommendations for securing your system as well.

If you use clamscan, create the following log file:

sudo touch /var/log/clamscan.log

Example cron job for clamav & aide:

{pkgs, ...}: {
  services.cron = {
    enable = true;
    # messages.enable = true;
    systemCronJobs = [
      # Every day at 2:00 AM, run clamscan as root and append output to a log file
      "0 2 * * * root ${pkgs.clamav}/bin/clamscan -r /home >> /var/log/clamscan.log"
      "0 11 * * * ${pkgs.aide}/bin/aide --check --config /var/lib/aide/aide.conf"
    ];
  };
}

ClamAV usage:

You can run clamav manually with:

# Recursive Scan:
sudo clamscan -r ~/home

You only need either the individual pkgs.clamav with the cron job OR the clamd-daemon module. clamdscan is for software integration and uses a different user that doesn’t have permission to scan your files. You can use clamdscan --fdpass /path/to/scan to pass the necessary file permissions. clamdscan runs in the background, you can watch it with top.

Securing SSH

Security information: Changing SSH configuration settings can significantly impact the security of your system(s). It is crucial to have a solid understanding of what you are doing before making any adjustments. Avoid blindly copying and pasting examples, including those from this Wiki page, without conducting a thorough analysis. Failure to do so may compromise the security of your system(s) and lead to potential vulnerabilities. Take the time to comprehend the implications of your actions and ensure that any changes made are done thoughtfully and with care. –NixOS Wiki

Choose one, either ssh-agent or gpg-agent

Use normal SSH keys generated with ssh-keygen, this is recommended unless you have a good reason for not using it.

Use a GPG key with gpg-agent (which acts as your SSH agent). Complex, and harder to understand in my opinion.

My setup caused conflicts when enabling programs.ssh.startAgent so I chose gpg-agent personally.

There are situations where you are required to use one or the other like for headless CI/CD environments, ssh-keygen is required.

Click Here for GnuPG and gpg-agent chapter

Key generation

ssh-keygen

The ed25519 algorithm is significantly faster and more secure when compared to RSA. You can also specify the key derivation function (KDF) rounds to strengthen protection even more.

For example, to generate a strong key for GitHub:

ssh-keygen -t ed25519 -a 32 -f ~/.ssh/id_ed25519_github_$(date +%Y-%m-%d) -C "SSH Key for GitHub"

-t is for type
-a 32 sets the number of KDF rounds. The standard is usually good enough, adding extra rounds can make it harder to brute-force.
-f is for filename

OpenSSH Server

First of all, if you don’t use SSH don’t enable it in the first place. If you do use SSH, it’s important to understand what that opens you up to.

The following are some recommendations from Mozilla on OpenSSH:

Mozilla OpenSSH guidelines

The following OpenSSH setup is based on the above guidelines with strong algorithms, and best practices: (EDITED: 10-07-25 to follow best-practices on post-quantum crypto)

{config, ...}: {
  config = {
    services = {
      fail2ban = {
        enable = true;
        maxretry = 5;
        bantime = "1h";
        # ignoreIP = [
        # "172.16.0.0/12"
        # "192.168.0.0/16"
        # "2601:881:8100:8de0:31e6:ac52:b5be:462a"
        # "matrix.org"
        # "app.element.io" # don't ratelimit matrix users
        # ];

        bantime-increment = {
          enable = true; # Enable increment of bantime after each violation
          multipliers = "1 2 4 8 16 32 64 128 256";
          maxtime = "168h"; # Do not ban for more than 1 week
          overalljails = true; # Calculate the bantime based on all the violations
        };
      };
      openssh = {
        enable = true;
        settings = {
          PasswordAuthentication = false;
          PermitEmptyPasswords = false;
          PermitTunnel = false;
          UseDns = false;
          KbdInteractiveAuthentication = false;
          X11Forwarding = config.services.xserver.enable;
          MaxAuthTries = 3;
          MaxSessions = 2;
          ClientAliveInterval = 300;
          ClientAliveCountMax = 0;
          AllowUsers = ["your-user"];
          TCPKeepAlive = false;
          AllowTcpForwarding = false;
          AllowAgentForwarding = false;
          LogLevel = "VERBOSE";
          PermitRootLogin = "no";
          KexAlgorithms = [
            # Post-Quantum: https://www.openssh.org/pq.html
            "mlkem768x25519-sha256"
            "sntrup761x25519-sha512"
            "curve25519-sha256@libssh.org"
            "ecdh-sha2-nistp521"
            "ecdh-sha2-nistp384"
            "ecdh-sha2-nistp256"
            "diffie-hellman-group-exchange-sha256"
          ];
          Ciphers = [
            "aes256-gcm@openssh.com"
            "aes128-gcm@openssh.com"
            # stream cipher alternative to aes256, proven to be resilient
            # Very fast on basically anything
            "chacha20-poly1305@openssh.com"
            # industry standard, fast if you have AES-NI hardware
            "aes256-ctr"
            "aes192-ctr"
            "aes128-ctr"
          ];
          Macs = [
            # Combines the SHA-512 hash func with a secret key to create a MAC
            "hmac-sha2-512-etm@openssh.com"
            "hmac-sha2-256-etm@openssh.com"
            "umac-128-etm@openssh.com"
            "hmac-sha2-512"
            "hmac-sha2-256"
            "umac-128@openssh.com"
          ];
        };
        # These keys will be generated for you
        hostKeys = [
          {
            path = "/etc/ssh/ssh_host_ed25519_key";
            type = "ed25519";
          }
        ];
      };
    };
  };
}

TCP port 22 (ssh) is opened automatically if the SSH daemon is enabled (services.openssh.enable = true;)

Much of the SSH hardening settings came from ryanseipp’s secure-ssh Guide with some additions of my own.

Fail2Ban is an intrusion prevention software framework. It’s designed to prevent brute-force attacks by scanning log files for suspicious activity, such as repeated failed login attempts.

As of 26.05, reaction was added to nixpkgs. “A daemon that scans program outputs for repeated patterns, and takes action.” It labels itself as a more modern alternative to fail2ban, implemented in Rust. The initial rust commit was authored May 20, 2024 and it has not received an external security audit yet. Worth checking out, probably not a primary recommendation yet.

OpenSSH is the primary tool for secure remote access for NixOS. Enabling it activates the OpenSSH server on the system, allowing incoming SSH connections.

The above configuration is a robust setup for securing an SSH server by:

Preventing brute-force attacks with Fail2Ban
Eliminating password authentication in favor of more secure SSH keys
Restricting user access and preventing root login
Disabling potentially risky forwarding features (tunnel, TCP, agent)
Enforce the use of strong, modern cryptographic algorithms for all SSH communications.
Enhanced logging for better auditing.

Encrypted Secrets

Never store secrets in plain text in repositories. Use something like sops-nix, which lets you keep encrypted secrets under version control declaratively.

Another option is agenix

NixOS Wiki Agenix

Sops-nix Guide

Protect your secrets, the following guide is on setting up Sops on NixOS: Sops Encrypted Secrets

Auditd

To enable the Linux Audit Daemon (auditd) and define a very basic rule set, you can use the following NixOS configuration. This example demonstrates how to log every program execution (execve) on a 64-bit architecture.

# modules/security/auditd-minimal.nix (or directly in configuration.nix)
{
  # start as early in the boot process as possible
  boot.kernelParams = ["audit=1"];
  security.auditd.enable = true;
  security.audit.enable = true;
  security.audit.rules = [
    # Log all program executions on 64-bit architecture
    "-a exit,always -F arch=b64 -S execve"
  ];
}

audit=1 Enables auditing at the kernel level very early in the boot process. Without this, some events could be missed.
security.auditd.enable = true; Ensures the auditd userspace daemon is started.
While often enabled together, security.audit.enable specifically refers to enabling the NixOS module for audit rules generation.
execve (program executions)
This is just a basic configuration, there is much more that can be tracked.

USB Port Protection

It’s important to protect your USB ports to prevent BadUSB attacks, data exfiltration, unauthorized device access, malware injection, etc.

To get a list of your connected USB devices you can use lsusb from the usbutils package.

lsusb

To list the devices recognized by USBGuard, run:

sudo usbguard list-devices

MyNixOS services.usbguard

Change your-user to your username:

# usbguard.nix
{
  config,
  pkgs,
  lib,
  ...
}: let
  inherit (lib) mkIf;
  cfg = config.custom.security.usbguard;
in {
  options.custom.security.usbguard = {
    enable = lib.mkEnableOption "usbguard";
  };

  config = mkIf cfg.enable {
    services.usbguard = {
      enable = true;
      IPCAllowedUsers = ["root" "your-user"];
    # presentDevicePolicy refers to how to treat USB devices that are already connected when the daemon starts
      presentDevicePolicy = "allow";
      rules = ''
        # allow `only` devices with mass storage interfaces (USB Mass Storage)
        allow with-interface equals { 08:*:* }
        # allow mice and keyboards
        # allow with-interface equals { 03:*:* }

        # Reject devices with suspicious combination of interfaces
        reject with-interface all-of { 08:*:* 03:00:* }
        reject with-interface all-of { 08:*:* 03:01:* }
        reject with-interface all-of { 08:*:* e0:*:* }
        reject with-interface all-of { 08:*:* 02:*:* }
      '';
    };

    environment.systemPackages = [pkgs.usbguard];
  };
}

The above settings can be found in RedHat UsbGuard

The only allow rule is for devices with only mass storage interfaces (08:*:*) i.e., USB Mass storage devices, devices like keyboards and mice (which use interface class 03:*:*) implicitly not allowed.

The reject rules reject devices with a suspicious combination of interfaces. A USB drive that implements a keyboard or a network interface is very suspicious, these reject rules prevent that.

The presentDevicePolicy = "allow"; allows any device that is present at daemon start up even if they’re not explicitly allowed. However, newly plugged in devices must match an allow rule or get denied implicitly.

The presentDevicePolicy should be one of: # one of "apply-policy"(default, evaluate the rule set for every present device), "block", "reject", "keep" (keep whatever state the device is currently in), or "allow", which is used in the example.

There is also the usbguard-notifier

And enable it with the following in your configuration.nix or equivalent:

# configuration.nix
imports = [
    ./usbguard.nix
];
custom.security.usbguard.enable = true;

❗ If you are ever unsure about a setting that you want to harden and think that it could possibly break your system you can always use a specialisation reversing the action and choose it’s generation at boot up. For example, to force-reverse the above settings you could:
# configuration.nix
specialisation.no-usbguard.configuration = {
    services.usbguard.enable = lib.mkForce false;
};
This is a situation where I recommend this, it’s easy to lock yourself out of your keyboard, mouse, etc. when trying to configure this.

Doas over sudo (Warning Doas is unmaintained)

✔️ Click to Expand Unmaintained Doas example

I have moved to run0 for authentication which is included by default with systemd. It’s actually a symlink to the existing systemd-run tool. It behaves like a secure sudo alternative: it spawns a transient service under PID 1 for privilege escalation, without relying on SUID (set user ID) binaries.

the Nixpkgs version of doas,OpenDoas is unmaintained and hasn’t been updated in 3 to 4 years. If you don’t like run0, consider using sudo-rs. I’m leaving this here for now, may remove it in the future to not promote using unmaintained software, you’ve been warned.

Why run0
SUID = “Set User ID”: When a binary has the SUID bit set, it runs with the privileges of the file’s owner (often root). There is a long history of vulnerabilities with SUID binaries.

For a more minimalist version of sudo with a smaller codebase and attack surface, consider doas. Replace userName with your username:

# doas.nix
{
  lib,
  config,
  pkgs, # Add pkgs if you need to access user information
  ...
}: let
  cfg = config.custom.security.doas;
in {
  options.custom.security.doas = {
    enable = lib.mkEnableOption "doas";
  };

  config = lib.mkIf cfg.enable {
    # Disable sudo
    security.sudo.enable = false;

    # Enable and configure `doas`.
    security.doas = {
      enable = true;
      extraRules = [
        {
          # Grant doas access specifically to your user
          users = ["userName"]; # <--- Only give access to your user
          # persist = true; # Convenient but less secure
          # noPass = true;    # Convenient but even less secure
          keepEnv = true; # Often necessary
          # Optional: You can also specify which commands they can run, e.g.:
          # cmd = "ALL"; # Allows running all commands (default if not specified)
          # cmd = "/run/current-system/sw/bin/nixos-rebuild"; # Only allow specific command
        }
      ];
    };

    # Add an alias to the shell for backward-compat and convenience.
    environment.shellAliases = {
      sudo = "doas";
    };
  };
}

You would then import this into your configuration.nix and enable/disable it with the following:

# configuration.nix

imports = [
    ./doas.nix
];

custom.security.doas.enable = true;

[!NOTE]: Many people opt for the less secure groups = ["wheel"]; in the above configuration instead of users = ["userName"]; to give wider access, the choice is yours.

Firejail

❗️ Critics such as madaidan say that Firejail worsens security by acting as a privilege escalation hole. Firejail requires the executable to be setuid, meaning it runs with root privileges.This is risky because any vulnerability in Firejail can lead to privilege escalation. This combined with many convenience features and complicated command line flags leads to a large attack surface.

I haven’t personally tried nix-bwrapper myself yet, but it’s another sandboxing option that looks interesting. Bubblewrap is known for having a more minimal design and smaller attack surface.
- Also see: Flatpak section for another option for sandboxing.
nix-bubblewrap is another option.
NixOS Wiki Firejail
Arch Wiki Firejail

Running untrusted code is never safe, sandboxing cannot change this. –Arch Wiki

# firejail.nix
{
  pkgs,
  lib,
  ...
}: {
  programs.firejail = {
    enable = true;
    wrappedBinaries = {
      # Sandbox a web browser
      librewolf = {
        executable = "${lib.getBin pkgs.librewolf}/bin/librewolf";
        profile = "${pkgs.firejail}/etc/firejail/librewolf.profile";
      };
      # Sandbox a file manager
      thunar = {
        executable = "${lib.getBin pkgs.xfce.thunar}/bin/thunar";
        profile = "${pkgs.firejail}/etc/firejail/thunar.profile";
      };
      # Sandbox a document viewer
      zathura = {
        executable = "${lib.getBin pkgs.zathura}/bin/zathura";
        profile = "${pkgs.firejail}/etc/firejail/zathura.profile";
      };
    };
  };
}

wrappedBinaries is a list of applications you want to run inside a sandbox. Only the apps in the wrappedBinaries attribute set will be automatically firejailed when launched the usual way.

Other apps may be started manually using firejail <app>, or added to wrappedBinaries if you want automatic sandboxing, just make sure the profile exists.

To inspect which profiles are available, after rebuilding go to /nix/store/, I used Yazi to search for /firejail and followed it to firejail/etc, where the profiles are.

There are many flags and options available with firejail, I suggest checking out man firejail.

There are comments explaining what’s going on in: firejail/package.nix

Firejail is a SUID program that reduces the risk of security breaches by restricting the running environment of untrusted applications using Linux namespaces and seccomp-bpf–Firejail Security Sandbox

It provides sandboxing and access restriction per application, much like what AppArmor/SELinux does at a kernel level. However, it’s not as secure or comprehensive as kernel-enforced MAC systems (AppArmor/SELinux), since it’s a userspace tool and can potentially be bypassed by privilege escalation exploits.

Flatpak

You cannot effectively use Firejail with Flatpak apps because of how their sandboxing technologies operate. Flatpak also won’t work with the hardened kernel because they require unprivileged user namespaces which the hardened kernel completely disables.

Flatpak permissions & What they Do Reference this while setting permissions with Flatseal, many apps come with more permissions than they need to function effectively breaking the sandbox.
Portals provide mediated, user-controlled access to host resources outside the sandbox, so apps don’t need broad blanket permissions.

Apps that don’t have a flatpak equivalent can be further hardened with bubblewrap independently but bubblewrap is not needed on Flatpak apps.

Because of this limited native MAC (Mandatory Access Control) support on NixOS, using Flatpak is often a good approach to get sandboxing and isolation for many GUI apps.

Flatpak bundles runtimes and sandbox mechanisms that provide app isolation independently of the host system’s AppArmor or SELinux infrastructure. This can improve security and containment for GUI applications running on NixOS despite the system lacking full native MAC coverage.
Flatpak apps benefit from sandboxing through bubblewrap, which isolate apps and restrict access to user/home and system resources.

Add Flatpak with the FlatHub repository for all users:

services.flatpak.enable = true;
  systemd.services.flatpak-repo = {
    wantedBy = [ "multi-user.target" ];
    path = [ pkgs.flatpak ];
    script = ''
      flatpak remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo
      # Only apps that are verified
      # flatpak remote-add --if-not-exists --subset=verified flathub-verified https://flathub.org/repo/flathub.flatpakrepo
    '';
  };
xdg = {
  portal = {
    enable = true;
    extraPortals = [ pkgs.xdg-desktop-portal-gtk ];
    config.common.default = [ "gtk" ];
  };
};
# Disables screencopy
systemd.user.services."xdg-desktop-portal-wlr" = {
  enable = false;
};

✔️ declarative-flatpak

Add the flake input to your flake.nix:

inputs = {
  flatpaks.url = "github:in-a-dil-emma/declarative-flatpak/latest";
};

The following is a NixOS module that installs Firefox & Bitwarden:

# flatpak.nix
{
  pkgs,
  inputs,
  ...
}: {
  imports = [
    inputs.flatpaks.nixosModules.default
  ];
  services.flatpak = {
    enable = true;
    remotes = {
      "flathub" = "https://dl.flathub.org/repo/flathub.flatpakrepo";
      # "flathub-beta" = "https://dl.flathub.org/beta-repo/flathub-beta.flatpakrepo";
    };
    packages = [
      "flathub:app/org.mozilla.firefox//stable"
      "flathub:app/com.bitwarden.desktop//stable"
      # "flathub-beta:app/org.kde.kdenlive/x86_64/stable"
      # ":${./foobar.flatpak}"
      "flathub:/root/testflatpak.flatpakref"
    ];
    overrides = {
      # note: "global" is a flatpak thing
      # if you ever ran "flatpak override" without specifying a ref you will know
      "global".Context = {
        filesystems = [
          "home"
        ];
        sockets = [
          "!wayland"
          "!fallback-x11"
        ];
      };
      "org.mozilla.Firefox" = {
        Environment = {
          "MOZ_ENABLE_WAYLAND" = 1;
        };
        Context.sockets = [
          "!wayland"
          "!fallback-x11"
          # "x11"
        ];
      };
    };
  };
  xdg.portal = {
    enable = true;
    extraPortals = [
      pkgs.xdg-desktop-portal-gtk
    ];
    config = {
      common.default = ["gtk"];
    };
  };
}

I got the above configuration to build successfully, one of the hardening steps I took isn’t allowing either app to launch. I’ll update once I find which setting it is exactly. (01-13-26)

Then you can either find apps through FlatHub or on the cmdline with flatpak search <app>. Flatpak is best used for GUI apps, some CLI apps can be installed through it but not all.

There is also nix-flatpak, which enables you to manage your flatpaks declaratively.
Flatseal is GUI utility that enables you to review and modify permissions from your Flatpak apps. Many apps by default come with smart-card support, X11 & Wayland support, and more, disabling unnecessary permissions is recommended.
Warehouse provides a simple UI to control complex Flatpak options, no cmdline required.

I have heard that it is not recommended to use Flatpak browsers because in order for flatpak to work it has to disable some of the built-in browser sandboxing which can reduce security. I haven’t found any examples of Flatpak browsers being exploited but it’s something to keep in mind.

SeLinux/AppArmor MAC (Mandatory Access Control)

AppArmor is available on NixOS, but is still in a somewhat experimental and evolving state. There are only a few profiles that have been adapted to NixOS, see here Discourse on default-profiles Which guides you here apparmor/includes.nix where you can see some of the abstractions and tunables to follow progress.

SELinux: Experimental, not fully integrated, recent progress for advanced/curious users; expect rough edges and manual intervention if you want to try it. Most find SELinux more complex to configure and maintain than AppArmor.

This isn’t meant to be a comprehensive guide, more to get people thinking about security on NixOS.

See the following guide on hardening networking:

Hardening Networking

Resources

Advanced Hardening with `nix-mineral` (Community Project)

✔️ Click to Expand section on `nix-mineral`

For users seeking a more comprehensive and opinionated approach to system hardening beyond the built-in hardened profile, the community project nix-mineral offers a declarative NixOS module.

nix-mineral aims to apply a wide array of security configurations, focusing on tweaking kernel parameters, system settings, and file permissions to reduce the attack surface.

Community Project Status: nix-mineral is a community-maintained project and is not officially part of the Nixpkgs repository or NixOS documentation. Its development status is explicitly stated as “Alpha software,” meaning it may introduce stability issues or unexpected behavior.

For detailed information on nix-mineral’s capabilities and current status, refer directly to its GitHub repository.

✔️ Click to Expand Resources

neal.codes vulnerability scan script:

nix-shell -p grype sbomnix --run '
  sbomnix /run/current-system --csv /dev/null --spdx /dev/null --cdx sbom.cdx.json;
  grype sbom.cdx.json
'

Government Resources 1st 6 come from gentoo’s Security_Handbook)

The Austrailian Cyber Security Centre’s Informational Security Manual (ISM)
The Australian Government’s Protective Security Policy Framework (PSPF)
The Australian Cyber Security Centre’s Protect Yourself page
The UK Government’s Security Policy Framework (SPF)
The UK Government’s Information Security Policy Framework (ISF)
The US National Institute of Standards and Technology’s Cybersecurity page
NixOS STIG
STIGs are configuration standards developed by the Defense Information Systems Agency (DISA) to secure systems and software for the U.S. Department of Defense (DoD). They are considered a highly authoritative source for system hardening.There are recommendations for hardening all kinds of software in the Stig Viewer
CIS Benchmarks
NSA Cybersecurity Directorate
bentopdf: looks interesting, haven’t checked it out yet though.
Non-Secret Encryption a “SECRET” no longer
Post-Quantum Cybersecurity Resources

Top-Level Attributes

2026-05-31T00:00:00+00:00

Chapter 5

✔️ Click to Expand Table of Contents

Understanding Top-Level Attributes in NixOS Modules

This explanation is based on insights from Infinisil, a prominent figure in the Nix community, to help clarify the concept of top-level attributes within NixOS modules.

[!NOTE] “top-level attributes” here refers to the attributes at the top level of a module file (imports, options, config), not to be confused with system.build.toplevel, which is the final system derivation everything builds toward.

To understand why top-level module attributes matter, it helps to first understand what they’re ultimately building toward: system.build.toplevel, the final derivation that represents your entire NixOS system.

The Core of a NixOS System: `system.build.toplevel`

✔️ `system.build.toplevel` Explained (Click to Expand)

In a NixOS system, everything is built from a single “system derivation.” The command nix-build '<nixpkgs/nixos>' -A system initiates this build process.

The -A system part tells Nix to focus on the system attribute defined in the '<nixpkgs/nixos>' file (which is essentially ./default.nix within the Nixpkgs repository).

This system attribute is specifically the NixOS option system.build.toplevel . Think of system.build.toplevel as the very top of the configuration hierarchy for your entire NixOS system. Almost every setting you configure eventually influences this top-level derivation, often through a series of intermediate steps.

How Options Relate: A Chain of Influence

Options in NixOS are not isolated; they often build upon each other.

Example: Nginx Option Chain (Click to Expand)

Here’s an example of how a high-level option can lead down to a low-level system configuration:

You enable Nginx with services.nginx.enable = true;.
This setting influences the lower-level option systemd.services.nginx.
Which, in turn, affects the even lower-level option systemd.units."nginx.service".
Ultimately, this leads to the creation of a systemd unit file within environment.etc."systemd/system".
Finally, this unit file ends up as result/etc/systemd/system/nginx.service within the final system.build.toplevel derivation.

The NixOS Module System: Evaluating Options

So, how do these options get processed and turned into the final system configuration? That’s the job of the NixOS module system, located in the ./lib directory of Nixpkgs (specifically in modules.nix, options.nix, and types.nix).

Interestingly, the module system isn’t exclusive to NixOS; you can use it to manage option sets in your own Nix projects.

Here’s a simplified example of using the module system outside of NixOS:

let
  systemModule = { lib, config, ... }: {
    options.toplevel = lib.mkOption {
      type = lib.types.str;
    };

    options.enableFoo = lib.mkOption {
      type = lib.types.bool;
      default = false;
    };

    config.toplevel = ''
      Is foo enabled? ${lib.boolToString config.enableFoo}
    '';
  };

  userModule = {
    enableFoo = true;
  };

in (import <nixpkgs/lib>).evalModules {
  modules = [ systemModule userModule ];
}

You can evaluate the config.toplevel option from this example using:

nix-instantiate --eval file.nix -A config.toplevel

How the Module System Works: A Simplified Overview

The module system processes a set of “modules” through these general steps:

Importing Modules: It recursively finds and includes all modules specified in imports = [ ... ]; statements.
Declaring Options: It collects all option declarations defined using options = { ... }; from all the modules and merges them. If the same option is declared in multiple modules, the module system handles this (details omitted for simplicity).
Defining Option Values: For each declared option, it gathers all the value assignments (defined using config = { ... }; or directly at the top level if no options or config are present) from all modules and merges them according to the option’s defined type.

[!NOTE] Option evaluation is lazy, meaning an option’s value is only computed when it’s actually needed. It can also depend on the values of other options.

Top-Level Attributes in a Module: imports, options, and config

Within a NixOS module (the files that define parts of your system configuration) , the attributes defined directly at the top level of the module’s function have specific meanings:

imports: This attribute is a list of other module files to include. Their options and configurations will also be part of the evaluation.
options: This attribute is where you declare new configuration options. You define their type, default value, description, etc., using functions like lib.mkOption or lib.mkEnableOption.
config: This attribute is where you assign values to the options that have been declared (either in the current module or in imported modules).

The Rule: Move Non-Option Attributes Under config

If you define either an options or a config attribute at the top level of your module, any other attributes that are not option declarations must be moved inside the config attribute.

✔️ Examples of Correct and Incorrect Usage (Click to Expand)

Let’s look at an example of what not to do:

{ pkgs, lib, config, ... }:
{
imports = [];

# Defining an option at the top level

options.mine.desktop.enable = lib.mkEnableOption "desktop settings";

# This will cause an error because 'environment' and 'appstream'

# are not 'options' and 'config' is also present at the top level.

environment.systemPackages =
lib.mkIf config.appstream.enable [ pkgs.git ];

appstream.enable = true;
}

This will result in the error: error: Module has an unsupported attribute 'appstream' This is caused by introducing a top-level 'config' or 'options' attribute. Add configuration attributes immediately on the top level instead, or move all of them into the explicit 'config' attribute.

The Correct Way: Using the config Attribute

To fix the previous example, you need to move the value assignments for environment.systemPackages and appstream.enable inside the config attribute:

{ pkgs, lib, config, ... }:
{
imports = [];

# Defining an option at the top level

options.mine.desktop.enable = lib.mkEnableOption "desktop settings";

config = {
environment.systemPackages =
lib.mkIf config.appstream.enable [ pkgs.git ];

    appstream.enable = true;

};
}

Now, Nix knows that you are declaring an option (options.mine.desktop.enable) and then setting values for other options (environment.systemPackages, appstream.enable) within the config block.

Implicit config: When options is Absent

If your module does not define either options or config at the top level, then any attributes you define directly at the top level are implicitly treated as being part of the config.

For example, this is valid:

{ pkgs, lib, config, ... }:
{
environment.systemPackages =
lib.mkIf config.appstream.enable [ pkgs.git ];

appstream.enable = true;
}

Nix will implicitly understand that environment.systemPackages and appstream.enable are configuration settings.

Removing an Option: What Happens to config

Even if you remove the options declaration from a module that has a config section, the config = { environment.systemPackages = ... }; part will still function correctly, assuming the option it’s referencing (appstream.enable in this case) is defined elsewhere (e.g., in an imported module).

Conclusion

Understanding the nuances of top-level attributes within NixOS modules, particularly imports, options, and config, is fundamental to structuring and managing your system’s configuration effectively. As we’ve seen, the module system provides a powerful and declarative way to define and evaluate system settings, ultimately contributing to the construction of the system.build.toplevel derivation that represents your entire NixOS environment.

The concepts of option declaration and value assignment, along with the crucial rule of organizing non-option attributes under the config attribute when options is present, provide a clear framework for building modular and maintainable configurations.

Now that we have a solid grasp of how NixOS modules are structured and how they contribute to the final system derivation, it’s a natural next step to explore the tangible results of these configurations: the software and system components themselves. These are built and managed by a core concept in Nix, known as derivations.

In the next chapter, Package Definitions Explained we will shift our focus from the abstract configuration to the concrete software packages. We will learn how Nix uses package definitions to create derivations, which are the actual build plans that produce the software we use on our NixOS systems. This will bridge the gap between configuring your system and understanding how the software within it is managed.

Practical Jujutsu

2026-03-16T00:00:00+00:00

Practical Jujutsu

This post assumes basic understanding of Git and GitHub.

I’ve spent enough time hovering between the familiarity of Git and the potential of Jujutsu. It’s time to move past a ‘primitive’ workflow. By truly mastering one of these tools, I want to turn version control from a chore into a way to precisely navigate my development stages and build a history that future contributors can actually follow.

JJ simplifies keeping a linear history and makes it easy to break down big changes into smaller atomic changes.

Atomic commits & Linear History explained

Angular Commit Message Format
<header>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>
The header is mandatory.

The body is mandatory for all commits except “doc” type commits.

The footer is optional

Atomic Commits

An atomic commit is a single unit of work that cannot be broken down further without losing its meaning.
One commit should do one thing.
If you had to “undo” that commit later, would it break unrelated features? If “Yes,” it’s not atomic.

If you find a bug, you can pinpoint the exact 10 lines of code that caused it. In jj, the split -i and commit -i commands are the ultimate tools for “atomizing” a messy afternoon of coding.

Linear History

A linear history is a straight line of commits without “merge bubbles” (those criss-crossing lines you see in Git logs when people use git merge).

Every commit has exactly one parent and one child.
It reads like a story. You can follow the evolution of the project from bottom to top without getting lost in a maze of branches.
jj defaults to a rebase-heavy workflow. Instead of “merging” your work and creating a mess, you are constantly “sliding” your changes on top of the latest work, keeping that line perfectly straight.

You can even insert a commit anywhere in your history with jj new -A (--insert-after), and jj new -B (--insert-before) and JJ will rebase every child in the history.

Use jj show -r <revision> to see a diff of the changes made at that Change ID, and trivially craft it with jj edit -r <revision>.

Let’s learn about jj by using it to version control a system Nix Flake.

Quick Overview

Jujutsu docs Glossary

Key Terms

“One of the first things to wrap your head around when first coming to Jujutsu is its approach to its revisions and revsets, i.e. “sets of revision”. Revisions are the fundamental elements of changes in Jujutsu, not “commits” as in Git. Revsets are then expressions in a functional language for selecting a set of revisions.” –Chris Krycho jj init

Term	What it is	Git Equivalent	JJ Behavior
Working Copy (`@`)	Your current editable commit. Everything you do affects `@` by default. Auto‑amends as you save files.	Untracked files + staging area + HEAD	Always a full commit. No staging. `jj st` shows changes relative to `@-`.
Change ID	Stable ID for a logical unit of work (the `k`, `y` labels in logs). Survives edits/rebases.	N/A	Prefix like `k` or `y`. Use `jj edit k1234` to jump to any change.
Commit ID	Unique ID for a specific snapshot (the long hex like `41deb985`). Changes when you amend.	Commit hash	Full ID for exact snapshots. Rarely used directly.
Bookmarks	Named pointers to commits (like `main`, `feature-x`). Don’t auto‑move like Git branches.	Branches	`jj bookmark set main -r @` moves it. `*` shows if local/remote match.
Parent (`@-`)	The commit `@` is built on top of.	Previous commit	Use `-r @-` to target it. Key for squash workflow.
Immutable (`◆`)	Commits that shouldn’t be rewritten (pushed changes, trunk).	Protected branches	`jj log` shows `◆`. Still editable with force flags.
Revset	Query language for commits (`main..@`, `mine()`).	`git log --grep`	Super powerful. `jj log -r "main..@"` = changes since main.
Revision	“revision” is synonymous with “commit”	Commit	A synonym for Commit

Pro tip: @ is always your current position. jj new, jj desc, jj squash all default to it. Bookmarks like main are just labels - move them explicitly with jj bookmark set.

See zerowidths jj-tips-and-tricks, for a more intuitive --interactive workflow (The git add -p Hunk-wise style).

Getting Started

It’s helpful to grasp a few Git concepts to fully understand some of the benefits and strengths of jujutsu. I highly suggest reading W3Tutorials.net How to Compare Working Copy, Staging Copy, and Committed Copy of a File in Git, it covers most of the concepts that make understanding jj easier.

The Working Copy is the version of the file you’re actively editing in your filesystem. It’s the “live” version you see in your text editor or IDE. –W3Tutorials.net
Jujutsu’s Working copy commit

“Unlike most other VCSs, Jujutsu will automatically create commits from the working-copy contents when they have changed. Most jj commands you run will commit the working-copy changes if they have changed. The resulting revision will replace the previous working-copy revision.”

In Git, HEAD is a pointer (usually to a branch like main), and that branch points to the current commit.

In jj, the working copy @ is itself the current commit. Bookmarks like main simply point at other commits in the graph, so your working copy is often a child of a bookmark, but it can also be off on its own.

❯ will indicate a command that I ran, the rest is output.

Let’s start by cloning a project of mine to see how jj works:

❯ jj git clone git@github.com:sayls8/nix-snake.git
Fetching into new repo in "/home/jr/projects/nix-snake"
remote: Enumerating objects: 88, done.
remote: Total 88 (delta 38), reused 78 (delta 30), pack-reused 0 (from 0)
bookmark: main@origin [new] tracked
Setting the revset alias `trunk()` to `main@origin`
Working copy  (@) now at: s f143a1da (empty) (no description set)
Parent commit (@-)      : l 3b759dfe main | feat: fix clippy lints & optimize
Added 12 files, modified 0 files, removed 0 files
Hint: Running `git clean -xdf` will remove `.jj/`!

We can see above that the main@origin bookmark is automatically tracked with a revset alias of trunk().

NOTE: My jj commands show the shortest possible IDs because of the setting:
programs.jujutsu.settings = {
   template-aliases = {
       "format_short_change_id(id)" = "id.shortest()";
   };
};

Running jj st & jj log:

❯  jj st
The working copy has no changes.
Working copy  (@) : s f143a1da (empty) (no description set)
Parent commit (@-): l 3b759dfe main | feat: fix clippy lints & optimize

❯  jj log
@  s sayls8@proton.me 2026-03-21 16:31:59 f143a1da
│  (empty) (no description set)
◆  l sayls8@proton.me 2026-01-29 16:50:51 main 3b759dfe
│  feat: fix clippy lints & optimize
~

To show all ancestors of the most recent commit, s in this case:

jj log -r ::s

The @ indicates the working-copy commit. The first ID on a line (e.g. “s” above) is the change ID. The second ID is the commit ID (“f143a1da”). You can give either ID to commands that take revisions as arguments.
jj log defaults to the ui.default-revset setting, or @ | ancestors(immutable_heads().., 2) | heads(immutable_heads()) if it’s not set. (A revset)
jj commands default to operating on the working copy, @. jj undo, undoes your previous jj command. List all previous jj commands with jj op log.

In JJ, you are never “on” a branch. You are always “on” a specific change, building a stack of changes. Until you push those changes, you can continue to jump around and edit them with jj edit. Once you push those changes to a remote, they then become immutable.

You don’t have to merge Change A into Change B, because Change B is already built on top of Change A. It inherits every line of code from the floors below it.

In Git, the working copy is the files on disk; changes only become part of the next commit when you stage them in the index with git add. In Jujutsu, the working copy is the current commit: your edits live in a “working copy commit” (@), which jj automatically updates from the files on disk, and there is no separate staging area.

When you’re ready to push to GitHub, make sure you know where your changes are. In the example above, the working copy is empty, so to push I’d run jj bookmark set main -r @- to point the main bookmark at the latest changes, then jj git push.

jj git push: By default, pushes tracking bookmarks pointing to remote_bookmarks(remote=<remote>)..@. Use --bookmark to push specific bookmarks. Use --all to push all bookmarks. Use --change to generate bookmark names based on the change IDs of specific commits.

If the working copy isn’t empty and those changes are what I want to push, I’d instead run jj bookmark set main -r @, followed by jj git push. Once you understand this distinction, the rest of the workflow feels fairly intuitive.

jj is smart enough to know that: If main is on your Working Copy (@) and you have uncommitted changes, it pushes those.
If your Working Copy (@) is empty , and main is on the Parent (@-), it pushes the parent.

In the above example, if I remove the config argument to the configuration.nix and remove a few comments, then run jj diff:

The squash workflow would benefit especially from jj diff. It’s like saying “take the diff I’m looking at right now and bake it directly into the parent”.
A change is a commit that can evolve while keeping a stable identifier, the change ID.

Version Control Best Practices

It’s helpful to use Conventional Commits, a set of rules for creating an explicit commit history.

Commit message standard syntax:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Example:

feat: implement dendretic pattern for boot module

Useful Utils

There is a new project that helps you create conventional commits for jj, jj-commit.
commitlint-rs can be used as a Git hook on push to enforce conventional commits.
semantic-release automates the whole package release workflow.

Using Tags

Tags are just named pointers to commits. Create one pointing to your latest change:

jj st
The working copy has no changes.
Working copy  (@) : ysrlmzlt 7d093162 (empty) (no description set)
Parent commit (@-): wmuwoply ea03805e chore: add 'release version' to justfile

jj tag set v0.1.5 --revision @-
jj git push --tags
cargo publish

When you publish next, create a new tag v0.1.6.

The simple order:

Write code, commit, jj git push as normal (many times)
When ready to release:

bump version in Cargo.toml to 0.1.6
update CHANGELOG
commit
jj git push
jj tag set v0.1.6 --revision @-
jj git push --tag v0.1.6 # This only pushes the tag, not the commit again
cargo publish

That’s it. Tags only appear at step 2, once per release.

One tag per release, on the commit you publish. Everything in between is just normal commits with no tags involved.

You can also use -dev tags between releases. Right after the release, set your version in your Cargo.toml to 0.1.7-dev and that will make clear which commit’s haven’t been published yet.

The edit workflow

Initialize and colocate the repository:

❯  mkdir learn-jj

  ~/projects
❯  cd learn-jj


  ~/projects/learn-jj
❯  nix flake new . -t github:nix-community/home-manager#nixos
wrote: "/home/jr/projects/learn-jj/flake.nix"

  ~/projects/learn-jj  ✗
❯  jj git init --colocate
Initialized repo in "."
Hint: Running `git clean -xdf` will remove `.jj/`!

  learn-jj   main [?]
❯  jj git remote add origin git@github.com:sayls8/learn-jj.git

  learn-j   main [?]
❯  jj bookmark create main -r @
Done importing changes from the underlying Git repo.
Created 1 bookmarks pointing to l bd3847c0 main | (no description set)

  learn-jj   refs/jj/root [!]
❯  jj bookmark track main --remote=origin
Started tracking 1 remote bookmarks.

Let’s give it our current change a description:

❯  jj desc -m "chore: Initialize system flake"
Working copy  (@) now at: l 743b170d main* | chore: Initialize system flake
Parent commit (@-)      : z 00000000 (empty) (no description set)

In this example, the Parent commit is the root commit. The root commit is a virtual commit at the root of every repository. It has a commit ID consisting of all ’0’s (00000000...) and a change ID consisting of all ’z’s (zzzzzzzz...). It can be referred to in revsets by the function root().

With this workflow, your working copy is typically at your current change.
JJ treats the working copy as a commit rather than having an index like Git.

If we wanted to push right now we could with jj git push (or equivalently jj git push --bookmark main), but let’s first learn a bit more about how jj works.

Let’s say we’re done with the current change and we’re ready to make it immutable and start a new change:

❯ jj new -m "chore: change username & hostname in flake.nix"
Working copy  (@) now at: p 6524f35a (empty) chore: change username & hostname in flake.nix
Parent commit (@-)      : l 743b170d main* | chore: Initialize system flake

As stated above, jj commands default to the working copy. So jj new is the same as jj new -r @. By running jj new repeatedly, we build a linear stack where each change is a child of the previous one. When we’re ready to ‘check in’ our work, we don’t merge; we simply move the main bookmark to our current position and push.
- If we want to start a separate task without including our current work, we can run jj new main (or any other Change ID). This creates a sibling change. Our previous stack isn’t “lost”; it stays exactly where it was in the graph, waiting to be described, rebased, or merged later.
Now our Working copy @ is at an (empty) change with the description “chore: change username & hostname in flake.nix”.
As you can see, running jj new, does not move the main bookmark. This is the hardest part to grasp when coming from Git IMO. Let’s make some more changes to hammer this home.

I’ve added my hostname and username to the flake.nix template, let’s make them a part of the permanent record.

I create a minimal configuration.nix, check my status and notice that I forgot to run jj new -m "feat: create minimal configuration.nix". Let’s see how to recover from this and keep our commits atomic.

jj split -i

This opens up a diff editor, I’ll only press y for the changes related to username and hostname. After you pass on what you don’t want in this change and press y on what you do want, your $EDITOR will open with your previous commit message. Save it and another commit message will open up in $EDITOR, this is whatever you didn’t press y on i.e., the configuration.nix changes, just give the second set of changes a different description and you’re all set.

Another cool thing about jj is that you can add a description whenever you want. Running jj desc -m "add configuration.nix" doesn’t finalize your commit like it does with Git. So, you can put the description first, last, or in the middle of a current change with no issue. The equivalent command to git commit -m "message" is jj commit -m "message" && jj new

Let’s see what the jj split -i command left us with:

❯  jj
Working copy changes:
A configuration.nix
Working copy  (@) : m b3cc09db feat: create minimal configuration.nix
Parent commit (@-): p cddde3b4 chore: change username & hostname in flake.nix

To see a diff of the changes in the parent commit:

jj show -r @-

And our log:

❯  jj log
@  m sayles8@proton.me 2026-03-15 13:43:31 b3cc09db
│  feat: create minimal configuration.nix
○  p sayls8@proton.me 2026-03-15 13:41:19 cddde3b4
│  chore: change username & hostname in flake.nix
○  l sayls8@proton.me 2026-03-15 13:37:29 main* 743b170d
│  chore: Initialize system flake
◆  z root() 00000000

As you can see, main* is all the way back at change l. Let’s move our main bookmark to our current Working copy.

❯  jj bookmark set main -r @
Moved 1 bookmarks to m b3cc09db main* | feat: create minimal configuration.nix

❯  jj log
@  m sayls8@proton.me 2026-03-15 13:43:31 main* b3cc09db
│  feat: create minimal configuration.nix
○  p sayls8@proton.me 2026-03-15 13:41:19 cddde3b4
│  chore: change username & hostname in flake.nix
○  l sayls8@proton.me 2026-03-15 13:37:29 743b170d
│  chore: Initialize system flake
◆  z root() 00000000

❯  jj git push
Changes to push to origin:
  Add bookmark main to b3cc09dba32c
git: Enumerating objects: 9, done.
git: Counting objects: 100% (9/9), done.
git: Delta compression using up to 16 threads
git: Compressing objects: 100% (7/7), done.
git: Writing objects: 100% (9/9), 1.99 KiB | 1019.00 KiB/s, done.
git: Total 9 (delta 1), reused 0 (delta 0), pack-reused 0 (from 0)
remote: Resolving deltas: 100% (1/1), done.
Warning: The working-copy commit in workspace 'default' became immutable, so a new commit has been created on top of it.
Working copy  (@) now at: u 551e83ad (empty) (no description set)
Parent commit (@-)      : m b3cc09db main | feat: create minimal configuration.nix

❯  jj log
@  u sayls8@proton.me 2026-03-15 13:47:27 551e83ad
│  (empty) (no description set)
◆  m sayls8@proton.me 2026-03-15 13:43:31 main b3cc09db
│  feat: create minimal configuration.nix

Notice jj log now shows main instead of main*, indicating that main and origin@main are in sync!
Also notice the ◆ next to the m change, this indicates that this change is now immutable. This is mentioned in the output of jj git push above.
- jj does this so you don’t accidentally rewrite history that others might have pulled. You can still force-edit if you need to but it’s jjs way of saying, “This is now part of the public record”.

I now need to add a minimal home.nix, then run nix flake check to see if I forgot anything.

If something isn’t being picked up by jj try running jj st and check again. Running any jj command updates the Working copy.

Since when running jj git push jj automatically creates a new commit on top of the last one, the next step is to describe this change.

I ran nix flake check and needed to add a hardware-configuration.nix, and networking.hostId required by ZFS, if I wanted to be a stickler about atomic commits I’d run jj split -i again but it’s fine by me to make 2 small changes to get the flake to pass the check.

The squash Workflow

The last section left me with:

❯  jj st
Working copy changes:
M configuration.nix
A flake.lock
A hardware-configuration.nix
A home.nix
Working copy  (@) : u e57a7a39 feat: add minimal home.nix
Parent commit (@-): m b3cc09db main | feat: create minimal configuration.nix

Let’s push what we have:

❯  jj bookmark set main -r @
Moved 1 bookmarks to u e57a7a39 main* | feat: add minimal home.nix

  learn-jj   HEAD [!]
❯  jj git push
Changes to push to origin:
  Move forward bookmark main from b3cc09dba32c to e57a7a39957a
git: Enumerating objects: 8, done.
git: Counting objects: 100% (8/8), done.
git: Delta compression using up to 16 threads
git: Compressing objects: 100% (6/6), done.
git: Writing objects: 100% (6/6), 1.98 KiB | 1.98 MiB/s, done.
git: Total 6 (delta 1), reused 0 (delta 0), pack-reused 0 (from 0)
remote: Resolving deltas: 100% (1/1), completed with 1 local object.
Warning: The working-copy commit in workspace 'default' became immutable, so a new commit has been created on top of it.
Working copy  (@) now at: y 53e8a3d9 (empty) (no description set)
Parent commit (@-)      : u e57a7a39 main | feat: add minimal home.nix

❯  jj st
The working copy has no changes.
Working copy  (@) : y 53e8a3d9 (empty) (no description set)
Parent commit (@-): u e57a7a39 main | feat: add minimal home.nix

Great, just what we need, an empty change! Let’s describe what we plan on doing:

jj desc -m "refactor: restructure flake to multi-host layout in hosts/magic"

Now we create a new change on top of this one:

❯  jj new
Working copy  (@) now at: w 43195106 (empty) (no description set)
Parent commit (@-)      : y c66bc991 (empty) refactor: restructure flake to multi-host layout in hosts/magic

Now we make our changes to the descriptionless Working copy and squash our changes into the parent commit.

mkdir -p hosts/magic

jj st
The working copy has no changes.
Working copy  (@) : w 43195106 (empty) (no description set)
Parent commit (@-): y c66bc991 (empty) refactor: restructure flake to multi-host layout in hosts/magic

Ahh, jj doesn’t pick up empty directories…

mv configuration.nix home.nix hosts/magic

 jj st
Working copy changes:
R {configuration.nix => hosts/magic/configuration.nix}
R {home.nix => hosts/magic/home.nix}
Working copy  (@) : w 8c49fc64 (no description set)
Parent commit (@-): y c66bc991 (empty) refactor: restructure flake to multi-host layout in hosts/magic

R = Renamed. jj is pretty clever here. Since I moved the files but their contents stayed the same, jj detected that I didn’t just “delete” one file and “add” a new one, I actually moved an object from point A to point B.
- The fact that jj shows R {home.nix => hosts/magic/home.nix} means it is keeping the history of that file intact. If you were to look at the log for hosts/magic/home.nix later, jj would know to look back into the history of the old home.nix as well.

I’m happy with the changes so far:

❯  jj squash
Working copy  (@) now at: k 41deb985 (empty) (no description set)
Parent commit (@-)      : y 2bee669a refactor: restructure flake to multi-host layout in hosts/magic

Notice how change w disappeared and y is no longer empty? That’s because we squashed the changes from our Working copy into the parent commit!

Pushing from the squash workflow

Let’s look at what we have:

❯  jj st
The working copy has no changes.
Working copy  (@) : k 41deb985 (empty) (no description set)
Parent commit (@-): y 2bee669a refactor: restructure flake to multi-host layout in hosts/magic

Since the working copy is at an (empty) change, it wouldn’t make sense to push it. We have to move our bookmark to the parent commit, and then push!

❯  jj bookmark set main -r @-
Moved 1 bookmarks to y 2bee669a main* | refactor: restructure flake to multi-host layout in hosts/magic

❯  jj git push
Changes to push to origin:
  Move forward bookmark main from e57a7a39957a to 2bee669ac276
git: Enumerating objects: 5, done.
git: Counting objects: 100% (5/5), done.
git: Delta compression using up to 16 threads
git: Compressing objects: 100% (3/3), done.
git: Writing objects: 100% (4/4), 452 bytes | 452.00 KiB/s, done.
git: Total 4 (delta 1), reused 0 (delta 0), pack-reused 0 (from 0)
remote: Resolving deltas: 100% (1/1), completed with 1 local object.

This was the biggest Aha moment I had. It makes perfect sense that you wouldn’t want to push a change that changes nothing. Since we squashed the contents of the Working copy into @-, that is where we need main to point.

I have an alias:

  la = [
    "log"
    "-r"
    "all()"
  ];

You can also list all commits with:

jj log -r ::
# or
jj log r 'all()'

Let’s check out our full history so far:

❯  jj la
@  k sayls8@proton.me 2026-03-15 14:30:43 41deb985
│  (empty) (no description set)
◆  y sayls8@proton.me 2026-03-15 14:30:43 main 2bee669a
│  refactor: restructure flake to multi-host layout in hosts/magic
◆  u sayls8@proton.me 2026-03-15 14:07:28 e57a7a39
│  feat: add minimal home.nix
◆  m sayls8@proton.me 2026-03-15 13:43:31 b3cc09db
│  feat: create minimal configuration.nix
◆  p sayls8@proton.me 2026-03-15 13:41:19 cddde3b4
│  chore: change username & hostname in flake.nix
◆  l sayls8@proton.me 2026-03-15 13:37:29 743b170d
│  chore: Initialize system flake
◆  z root() 00000000

Textbook linear history. Every single commit has exactly one parent, forming a single, unbroken chain from the root() up to the current working copy.
The diamonds ◆ show that everything from y down is now part of the permanent record (pushed to the remote).

In Git, achieving this usually requires git add, git commit --amend, or an interactive rebase. In jj, you just worked in the working copy and pushed, the tool handled the “shaping” of the history for you.

Bookmarks and Branches

Bookmarks are named pointers to revisions (just like branches are in Git). You can move them without affecting the target revision’s identity. – Jujutsu docs

Branches are just multiple “changes” with the same parent.

List all available bookmarks

❯  jj bookmark list --all
feat1 (deleted)
  @origin: xo 9067e7b7 mangowc flake-parts module
main: s b250e6ed testing the push-on-new non working bs
  @git: s b250e6ed testing the push-on-new non working bs
  @origin (behind by 2 commits): o 65e79e4b jj bookmarks push-on-new
Hint: Bookmarks marked as deleted can be *deleted permanently* on the remote by running `jj git push --deleted`. Use `jj bookmark forget` if you don't want that.

Every time you run jj git push, jj automatically runs jj new main for you because the working copy becomes immutable after the push.

Show heads of all anonymous branches:

jj log -r 'heads(all())'

To visualize an anonymous branch, Steve’s Jujutsu tutorial does a great job of displaying this:


                     ┌───┐ ┌───┐
                 ┌───┤ F ◄─┤ G │
                 │   └───┘ └───┘
                 │
 ┌───┐  ┌───┐  ┌─▼─┐ ┌───┐ ┌───┐
 │ A ◄──┤ B ◄──┤ C ◄─┤ D ◄─┤ E │
 └───┘  └───┘  └───┘ └───┘ └───┘

Here, we’d say that F and G are two changes that are “on a branch,” because it looks like they’re branching off from D and E. Steves Jujutsu tutorial What is a branch conceptually?

The above sentence confused me a bit. F and G are described as branching “off” of the line containing D and E. However, in the literal graph structure, they diverge from C.

Since F and D both point to C, they are “siblings”. Because no other commits point back to E and G, they are the only two heads.

In Jujutsu, a branch is just any path of commits that hasn’t been merged yet. Since E and G are both visible and unmerged, we have two “anonymous branches” currently active.

The output of jj log -r 'heads(all())' with the above example, would yield:

○  G
│
~
│
○  E
│
~

G and E are the heads of the anonymous branches.

Examples

Start at an empty change:

❯  jj log
@  p saylesss87@proton.me 2026-03-24 18:05:54 6469af06
│  (no description set)

Give the current change a description:

jj desc -m "refactor(waybar): waybar flake-parts module"

❯  jj log
@  p saylesss87@proton.me 2026-03-24 18:06:31 627d846c
│  refactor(waybar): waybar flake-parts module
○  yl saylesss87@proton.me 2026-03-24 17:55:00 56d13161
│  refactor(foot): foot flake-parts module

To create a branch we need 2 changes with the same parent, our current changes parent is yl so let’s make our new change off of that:

❯  jj new yl -m "chore: add better documentation to README"
Working copy  (@) now at: v 4697897a (empty) chore: add better documentation to README
Parent commit (@-)      : yl 56d13161 refactor(foot): foot flake-parts module
Added 1 files, modified 1 files, removed 1 files

Let’s check out our log to see our anonymous branches:

❯  jj
@  v saylesss87@proton.me 2026-03-24 18:12:04 4697897a
│  (empty) chore: add better documentation to README
│ ○  p saylesss87@proton.me 2026-03-24 18:06:31 627d846c
├─╯  refactor(waybar): waybar flake-parts module
○  yl saylesss87@proton.me 2026-03-24 17:55:00 56d13161
│  refactor(foot): foot flake-parts module

We can see that p branches off from yl, let’s make this change before switching to the other branch.

❯  jj st
Working copy changes:
M README.md
Working copy  (@) : v 23d94e56 chore: add better documentation to README
Parent commit (@-): yl 56d13161 refactor(foot): foot flake-parts module

# This effectively moves the working copy to the other "branch"
❯  jj edit p
Working copy  (@) now at: p 627d846c refactor(waybar): waybar flake-parts module
Parent commit (@-)      : yl 56d13161 refactor(foot): foot flake-parts module
Added 1 files, modified 2 files, removed 1 files

In Git, you checkout a branch name; in jj, you just move your working copy (@) to whichever commit you want to build on.

I’ve added the new flake-parts module and deleted the old home-manager style module:

❯  jj st
Working copy changes:
D home/waybar.nix
M hosts/magic/home.nix
A parts/waybar.nix
Working copy  (@) : p 627d846c refactor(waybar): waybar flake-parts module
Parent commit (@-): yl 56d13161 refactor(foot): foot flake-parts module

Let’s add another change on this branch to solidify these concepts:

❯  jj new -m "refactor(nh): nh flake-parts module"
Working copy  (@) now at: n ac086b55 (empty) refactor(nh): nh flake-parts module
Parent commit (@-)      : p 627d846c refactor(waybar): waybar flake-parts module

And our log to show that this branch has grown:

❯  jj log
@  n saylesss87@proton.me 2026-03-24 18:22:12 ac086b55
│  (empty) refactor(nh): nh flake-parts module
○  p saylesss87@proton.me 2026-03-24 18:06:31 627d846c
│  refactor(waybar): waybar flake-parts module
│ ○  v saylesss87@proton.me 2026-03-24 18:17:51 23d94e56
├─╯  chore: add better documentation to README
○  yl saylesss87@proton.me 2026-03-24 17:55:00 56d13161
│  refactor(foot): foot flake-parts module

Now, let’s first merge the README branch into this one. We are worried about the heads of the anonymous branches right now:

❯  jj log -r 'heads(all())'
@  n saylesss87@proton.me 2026-03-24 18:22:12 ac086b55
│  (empty) refactor(nh): nh flake-parts module
~

○  v saylesss87@proton.me 2026-03-24 18:17:51 23d94e56
│  chore: add better documentation to README

A merge is a new change that has more than one parent. With JJ, you make a change with jj new. We can see that we need to make a change with both n and v as parents from the log output above:

❯  jj new n v -m "feat: merge in README docs"
Working copy  (@) now at: yn a923db65 (empty) feat: merge in README docs
Parent commit (@-)      : n ac086b55 (empty) refactor(nh): nh flake-parts module
Parent commit (@-)      : v 23d94e56 chore: add better documentation to README
Added 0 files, modified 1 files, removed 0 files

❯  jj log
@    yn saylesss87@proton.me 2026-03-24 18:28:47 a923db65
├─╮  (empty) feat: merge in README docs
│ ○  v saylesss87@proton.me 2026-03-24 18:17:51 23d94e56
│ │  chore: add better documentation to README
○ │  n saylesss87@proton.me 2026-03-24 18:22:12 ac086b55
│ │  (empty) refactor(nh): nh flake-parts module
○ │  p saylesss87@proton.me 2026-03-24 18:06:31 627d846c
├─╯  refactor(waybar): waybar flake-parts module
○  yl saylesss87@proton.me 2026-03-24 17:55:00 56d13161
│  refactor(foot): foot flake-parts module

That messes up our perfectly linear history, let’s rebase instead.

❯  jj undo
Undid operation: a74a45f02043 (2026-03-24 18:28:47) new empty commit
Restored to operation: 848c180f2a04 (2026-03-24 18:22:12) new empty commit
Working copy  (@) now at: n ac086b55 (empty) refactor(nh): nh flake-parts module
Parent commit (@-)      : p 627d846c refactor(waybar): waybar flake-parts module
Added 0 files, modified 1 files, removed 0 files

Rebase is your tool for changing the ‘parent’ of a commit. If you have two parallel features (siblings) and you decide one should follow the other (linear stack), you rebase the second feature onto the first.

❯  jj rebase -r v -o n
Rebased 1 commits to destination

Now our history is back to being completely linear:

❯  jj log
○  v saylesss87@proton.me 2026-03-24 18:30:36 8101b0dd
│  chore: add better documentation to README
@  n saylesss87@proton.me 2026-03-24 18:22:12 ac086b55
│  (empty) refactor(nh): nh flake-parts module
○  p saylesss87@proton.me 2026-03-24 18:06:31 627d846c
│  refactor(waybar): waybar flake-parts module
○  yl saylesss87@proton.me 2026-03-24 17:55:00 56d13161
│  refactor(foot): foot flake-parts module

To move a stack of changes, use jj rebase -s [Source] -d [Destination]. If you want to move a feature to the very tip of your main line, destination is main. If you want to chain features together, destination is the previous feature’s head.

Pay attention to where @ is while rebasing, to continue on this linear stack I’ll have to run jj new v.

Collaborating and opening PRs

So far all the examples assumed you are the only person touching this repo. For collaboration (GitHub / GitLab PRs, code review, etc.), the mental model is:

GitHub only understands branches and commits.
Jujutsu gives you changes and bookmarks.
You use jj git push to translate your clean JJ history into a Git branch that others can review.

A simple pattern that works well for feature branches and PRs:

Start from main

Make sure main is up to date and your working copy is clean:

jj git fetch
jj edit main
jj st

You should see an (empty) working copy with main as the parent.

Create a named feature branch as a bookmark

In JJ, you don’t “checkout” a branch, you create a new change and (optionally) give it a bookmark name:

# Create a new change on top of main and start working there
jj new main -m "feat: add magic host"

# Optionally create a bookmark that GitHub will see as a branch
jj bookmark create feature/magic-host -r @

jj new main makes a sibling of any in‑progress work and starts a fresh change on top of main.
The bookmark feature/magic-host is what will become the Git branch name when you push.

Hack, split, squash as usual

Work in your normal JJ style:

# edit files
jj st
jj split -i
jj desc -m "feat: add magic host"
jj new
# more changes, more desc/split/squash, etc.

All of this is still local, fully mutable history.

Point your feature bookmark at the top of the stack

When you’re happy with the stack you want to send for review, move the bookmark to the tip:

# If your working copy @ is the commit you want reviewed:
jj bookmark set feature/magic-host -r @

# If you used the squash workflow and @ is empty:
jj bookmark set feature/magic-host -r @-

Rule of thumb:

If jj st shows actual changes or a non‑empty description at @, use @.
If @ is (empty) because you squashed into the parent, use @-.

Push to Git and open the PR

Now push just like before, but your feature bookmark will become a branch on the remote:

jj git push

This will:

Update origin/feature/magic-host to point at the same commit as your local feature/magic-host.
Leave main alone until you explicitly move and push it.

On GitHub/GitLab:

You’ll see a branch named feature/magic-host.
Open a PR from feature/magic-host into main as usual.

Iterate on review feedback

If a reviewer asks for changes:

Come back to your feature branch stack:

jj edit feature/magic-host

Make your edits, split/squash/reword history freely.
Move the bookmark to the new tip and push again:

jj bookmark set feature/magic-host -r @
jj git push

GitHub will show the PR updating in place, but you got to reshuffle history locally without git rebase -i pain.

“I just want a one‑off PR, no named bookmark”

If you don’t care about a persistent bookmark and just want a quick “one‑shot” PR from whatever you’re currently working on:

Make sure your stack is in the shape you want.
Put main on the top of that stack:

# Working copy @ is the tip you want:
jj bookmark set main -r @
# Or equivalently `jj bookmark set main` since commands default to the working copy
jj git push

On GitHub, create the PR from your fork’s main to upstream main.

This is essentially the same pattern we already use in the “squash workflow,” but applied with the mental model: “move the bookmark people care about (main or a feature name) to the commit I want them to review, then push.”

Workflow Considerations

You may want to change up how you work depending on your requirements…

The Tower Workflow (The “Dependent Stack”)

You use a tower when your changes build on top of each other.

main → Feature A → Feature B → Feature C
Use it when you are refactoring a Nix module (Feature A), and then you need to use that new module to configure your desktop (Feature B). You literally cannot do B without A.

The Collaborative Benefit: You can push the entire stack. Your teammates see the logical progression of your thought process. They can review “Feature A” while you are already working on “Feature C.”

The Sibling Workflow (jj new main) You use jj new main when you are working on independent ideas that have nothing to do with each other.

How it looks: * main → Fix-Helix-Keys
- main → Update-Nix-Channel
- main → New-Wallpaper-Script

When to use it: You’re in the middle of a massive system refactor, but you suddenly notice your Helix C-p bind is broken. You don’t want the Helix fix to be “trapped” behind the refactor.

The Collaborative Benefit: Isolation. If your “System Refactor” is buggy and takes three days to fix, you can still jj git push the “Helix Fix” to main immediately because it’s a direct child of main. It isn’t “waiting” for the other commits.

Fixing Divergent Branches

jj makes it easy to fix divergent branches with jj forget.

As an example imagine this scenario:

On your Laptop: You finish a feature and jj git push. Local main and origin/main are now at Revision B.
On your Desktop: You forgot to pull. Local main is still at Revision A. You start hacking and create Revision C.
The Mess: You run jj git fetch. Now your Desktop sees:

main (local) at C
main@origin at B
jj freaks out and marks the bookmark as diverged (main*).

jj bookmark forget main is the “I don’t want to think about it” button. It deletes the main* label on your Desktop so you can just fetch the “real” one from the Laptop/GitHub and rebase your new work (C) on top of it.

Tips & Tricks

Your History is just a stack of diffs:

jj commit -i: Slices a diff off your current work.
jj split -i: Slices an existing diff into two.
jj bookmark forget: Deletes a label that got messy.

The Ghost Refactor

The Scenario: You’re in the middle of a complex Rust feature (Change C), and you realize a function in the base (Change A) needs to be public or renamed for this to work.

jj new A -m "quick fix" → Creates a new “slice” right after A.
Make your change.
jj squash → This “melts” the fix directly into A.

Use jj describe as a Task List

Because jj doesn’t require a “commit” to save work, you can use descriptions to manage your focus.

When you start a session, create a few empty changes:

jj new main -m "Update Cargo.toml"
jj new -m "Add pixel conversion logic"
jj new -m "Fix CLI output formatting"

Now we have a roadmap. Use jj edit to jump into whichever task you feel like doing. jj tracks the progress of each. No need to stash when jumping between tasks because of the working copy commit.

Breaking up your Current set of Changes into Atomic Commits: “The Atomic Shredder” jj split

Often I’ll just keep working on a bug or feature until it works, not particularly concerned about my VCS history. Let’s say I spent 3 hours hacking on a project of mine to get a feature working and I touched 10 files. It works, but the commit is a mess.

With the gitpatch tool, jj split -i makes it simple to break down many changes into logical “atomic commits” using a simple y/ n interface.

You can actually use both jj commit -i & jj split -i to break down changes in @ into smaller changes. jj commit -i is ergonomically tuned for “push some current work down, leave the rest in @”.

If your changes are already in @- (or any earlier commit):

jj commit -i can’t help, because it only ever operates on @.
jj split -i -r @- (or equivalent) can be used to modify an existing commit in history.

As a rule of thumb:

Changes in @ → use jj commit -i to peel off a clean piece, and also jj squash -i to squash a subset of changes from the working copy into the parent commit.
Changes in @- (or earlier) → use jj split -i to rewrite that commit

The Dendritic Pattern with flake-parts

2026-03-07T00:00:00+00:00

The Dendritic Pattern with flake-parts

–dendretic repo

In the early days of Flakes, users often ended up with a massive, monolithic flake.nix or a spaghetti-like web of manual imports. The Dendritic (Tree-like) Pattern solves this by treating your filesystem as the source of truth, using flake-parts as the nervous system that routes code to the correct outputs.

Flake-Parts

IMO the flake-parts docs could do a lot better at explaining how to use it to configure your system. I’ll attempt to explain how to use it and why you might want to.

While flake-parts provides the core structure for standard flake outputs, its real power lies in its modular ecosystem. You can plug in opinionated modules to instantly add specialized features to your system’s nervous system.

When people say “top-level flake attribute”, they mean putting your configuration inside the flake = { ... }; block.

The “Top-Level” (`flake`):

This is for things that are global and don’t change regardless of whether you’re on a Mac, PC or ARM server.

Example: Your nixosConfigurations or homeConfigurations.
A NixOS configuration for a specific laptop is a single, static definition. It doesn’t need to be “multiplied” by system types.

The “Per-System” (`perSystem`)

perSystem is for things that must be built for a specific architecture. (e.g., devShells, packages, formatter)
- You can’t run an x86_64 version of helix on an aarch64 (ARM) MacBook.
Our nixosConfigurations don’t live in a system specific attribute so it goes under flake instead of perSystem.

You can place everything in the same file:

outputs = inputs@{ flake-parts, ... }:
  # https://flake.parts/module-arguments.html
  flake-parts.lib.mkFlake { inherit inputs; } (top@{ config, withSystem, moduleWithSystem, ... }: {
    imports = [
      # Optional: use external flake logic, e.g.
      # inputs.foo.flakeModules.default
    ];
    flake = {
      # Put your original flake attributes here.
    };
    systems = [
      # systems for which you want to build the `perSystem` attributes
      "x86_64-linux"
      # ...
    ];
    perSystem = { config, pkgs, ... }: {
      # Recommended: move all package definitions here.
      # e.g. (assuming you have a nixpkgs input)
      # packages.foo = pkgs.callPackage ./foo/package.nix { };
      # packages.bar = pkgs.callPackage ./bar/package.nix {
      #   foo = config.packages.foo;
      # };
    };
  });

Or you can break it down into modules:

{
  inputs = {
    nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
    flake-parts.url = "github:hercules-ci/flake-parts";
  };

  outputs = inputs @ { flake-parts, ... }:
    flake-parts.lib.mkFlake { inherit inputs; }
    {
      # Supported Systems
      systems = [ "x86_64-linux" "x86_64-darwin"];
      imports = [ ./devShell.nix ./package.nix ./nixos.nix ]
    };

}

devShell.nix:

{
  perSystem = { pkgs, ...}: {
  devShells.default = pkgs.mkShell {
    packages = [ pkgs.ripgrep pkgs.fd ];
  };
};
}

package.nix:

{
  perSystem = { pkgs, ...}: {
    packages.myPackage = pkgs.myPackage;
  };
}

Getting Started

This is the flake that I’m currently using to slowly adopt the dendritic pattern, or not if I choose not to. Maybe making every single thing a flake output isn’t necessary or the best idea, we’ll see. With this, you can use both regular NixOS/home-manager modules and NixOS/home-manager flake-parts modules.

Scalability Toggle:

I have ++ (builtins.attrValues ...) set for both home-manager and NixOS where it automatically adds the inputs for files in the ~/flake/parts directory. This is fine for personal use where you want the custom modules available everywhere instantly.
If the flake gets too big and you want more control just comment out those 2 lines in the nixos.nix and start explicitly adding the inputs to your imports list. Now the parts/ directory will act like a library rather than a Registry, you manually pick what you want for each host.
home-manager flake-parts module

Example: Let’s call this ~/flake/flake.nix

# In this example the top-level configuration is a [`flake-parts`](https://flake.parts) one.
# Therefore, every Nix file (other than this) is a flake-parts module.
# https://github.com/mightyiam/dendritic/blob/master/example/flake.nix
{
  # Declares flake inputs
  inputs = {
    flake-parts = {
      url = "github:hercules-ci/flake-parts";
      inputs.nixpkgs-lib.follows = "nixpkgs";
    };

    import-tree.url = "github:vic/import-tree";

    nixpkgs.url = "github:nixos/nixpkgs/25.11";
  };

  outputs =
    inputs:
    inputs.flake-parts.lib.mkFlake { inherit inputs; } {
      # This tells flake-parts which systems to generate outputs for
      systems = import inputs.systems;

      imports = [
        # Optional: use external flake logic, e.g.
        inputs.treefmt-nix.flakeModule
        # Import home-manager's flake module
        # The flake module defines flake.homeModules and flake.homeConfigurations options,
        # allowing them to be properly merged if they are defined in multiple modules
        inputs.home-manager.flakeModules.default
        ./nixos.nix
      ]
      ++ (inputs.import-tree ./parts).imports;

      hosts = {
        magic = {
          username = "jr";
          system = "x86_64-linux";
        };
        # Adding a second machine is now 4 lines of code:
        # secondary = { username = "jr"; system = "aarch64-linux"; };
      };

      perSystem =
        {
          system,
          ...
        }:
        {

          # Access pkgs with your specific config
          _module.args.pkgs = import inputs.nixpkgs {
            inherit system;
            config.allowUnfree = false;
          };
        };

    };
}

import-tree is essentially a “smarter” version of the scanPaths function that we’ll see later specifically designed for flake-parts. It ensures that every file in ./parts is treated as a module that the mkFlake engine can digest.

Note, this example has more code than for example the dendritic nix repo has because it enables you to automatically import flake-parts modules as well as standard NixOS and home-manager modules as you move to the new system/pattern.

And ~/flake/nixos.nix:

/**
  System Configuration Factory Module

  This module defines a custom schema for describing multiple NixOS hosts
  and automatically generates the corresponding `nixosConfigurations` flakes output.
*/
{
  inputs,
  self,
  lib,
  config,
  ...
}:
let
  # Internal Library & Module Imports

  # Initialize a custom library using the project's internal lib and nixpkgs
  myLib = import "${self}/lib/default.nix" { inherit (inputs.nixpkgs) lib; };

  # Import entry points for global NixOS and Home Manager shared modules
  # `self` points to the root of the flake (requires passing `self` throuth specialArgs)
  nixosModules = import "${self}/nixos";
  homeManagerModules = import "${self}/home";

  # Shared Binary Cache Configuration
  caches = {
    nix.settings = {
      builders-use-substitutes = true;
      substituters = [ "https://cache.nixos.org" ];
      trusted-public-keys = [ "cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDShjY=" ];
    };
  };
in
{
  /**
    SCHEMA DEFINITION
    Defines the 'hosts' option, allowing us to declare system metadata
    (e.g., username, architecture) in a structured attribute set.
  */
  options.hosts = lib.mkOption {
    description = "An attribute set of host definitions to be generated.";
    type = lib.types.attrsOf (
      lib.types.submodule {
        options = {
          username = lib.mkOption {
            type = lib.types.str;
            default = "jr";
            description = "Primary user account name for this host.";
          };
          system = lib.mkOption {
            type = lib.types.str;
            default = "x86_64-linux";
            description = "The target system architecture.";
          };
        };
      }
    );
  };
  /**
    CONFIGURATION GENERATION
    Iterates through the 'config.hosts' defined above and maps them to
    actual 'nixosSystem' instances for the Flake output.
  */
  config.flake.nixosConfigurations = lib.mapAttrs (
    host: cfg:
    inputs.nixpkgs.lib.nixosSystem {
      # Pass global context and metadata into the module system
      specialArgs = {
        inherit
          inputs
          self
          host
          myLib
          ;
        inherit (cfg) username;
      };

      modules = [
        # 1. Project-wide NixOS logic
        nixosModules

        # 2. Host-specific hardware/system configuration file
        "${self}/hosts/${host}/configuration.nix"

        # 3. Home Manager NixOS module (allows configuring HM within NixOS)
        inputs.home-manager.nixosModules.home-manager

        # 4. Standardized cache settings defined in 'let' block
        caches

        # 5. Inline configuration for system-specific and user-specific settings
        {
          nixpkgs.hostPlatform = cfg.system;
          home-manager = {
            # By default, Home Manager uses a private pkgs instance that is configured
            #  via the home-manager.users.<name>.nixpkgs options. To instead use the
            #  global pkgs that is configured via the system level nixpkgs options, set
            useGlobalPkgs = true;
            # Install packages to /etc/profiles rather than $HOME/.nix-profile
            useUserPackages = true;
            # Dynamically import the user's home configuration based on host/username
            users.${cfg.username} = {
              imports = [
                (import "${self}/hosts/${host}/home.nix")
              ]
              # Automatically import `homeModules` in `./parts`
              # Comment out if you want to be explicit and add
              # e.g., inputs.self.homeModules.helix
              ++ (builtins.attrValues config.flake.homeModules);
            };

            extraSpecialArgs = {
              inherit
                inputs
                homeManagerModules
                myLib
                host
                ;
              inherit (cfg) username;
            };
          };
        }
      ]
      # Automatically import `nixosModules` in `./parts`
      ++ (builtins.attrValues config.flake.nixosModules);
    }
  ) config.hosts;
}

Now, any flake-parts module that we place in the ~/flake/parts/ directory will be automatically imported with import-tree. The key here is that it has to be a flake-parts module, i.e. wrapped in flake or perSystem, etc.

You can place both NixOS modules and home-manager modules in the ~/flake/parts directory. Just import it to the correct location and you’re good.

Example NixOS module for amd drivers ~/flake/parts/amd-drivers.nix:

{
  flake.nixosModules.amd-drivers =
    {
      lib,
      pkgs,
      config,
      ...
    }:
    with lib;
    let
      cfg = config.custom.amd-drivers;
    in
    {
      options.custom.amd-drivers.enable = mkEnableOption "AMD GPU/CPU optimized for AM06 Pro";

      config = mkIf cfg.enable {
        # Modern ROCm/HIP support
        systemd.tmpfiles.rules = [ "L+ /opt/rocm/hip - - - - ${pkgs.rocmPackages.clr}" ];
        services.xserver.videoDrivers = [ "amdgpu" ];

        hardware = {
          amdgpu.initrd.enable = true;

          graphics = {
            enable = true;
            enable32Bit = true;
            extraPackages = with pkgs; [
              rocmPackages.clr.icd # For OpenCL/Compute
              # Hardware Acceleration (Video Encoding/Decoding)
              libva
              libva-utils
              libva-vdpau-driver
              libvdpau-va-gl
            ];
          };

          cpu.amd.updateMicrocode = true;
        };

        boot = {
          kernelModules = [
            "kvm-amd"
            "amdgpu"
          ];
          kernelParams = [
            "amd_pstate=active" # Best for Ryzen 5000+ power management
          ];
        };

        boot.kernelPackages = pkgs.linuxPackages_latest;
      };
    };
}

Now, to enable this module, I’ll add this to my configuration.nix or equivalent:

 {...}: {
  imports = [
        # Not necessary because of the `++ (builtins.attrValues config.flake.nixosModules)` in nixos.nix
        # for more control remove those lines and explicitly add:
        # inputs.self.nixosModules.amd-drivers
  ];

  custom = {
    amd-drivers.enable = true;
  };
}
# ---snip---

Example home-manager module ~/flake/parts/fzf.nix:

{
  flake.homeModules.fzf =
    { lib, config, ... }:
    let
      cfg = config.custom.fzf;
    in
    {
      options.custom.fzf.enable = lib.mkEnableOption "Enable fzf module";

      config = lib.mkIf cfg.enable {
        programs.fzf = {
          enable = true;
          # colors = lib.mkForce { };

          defaultOptions = [
            "--height 40%"
            "--reverse"
            "--border"
            "--color=16"
          ];

          defaultCommand = "rg --files --hidden --glob=!.git/";
        };
      };
    };
}

And enable with custom.fzf.enable = true; in your home.nix or equivalent.

And this will be automatically imported, same as above but because of the added ++ (builtins.attrValues config.flake.homeModules); in nixos.nix. Without the automatic import, add inputs.self.homeModules.fzf to your imports list in your home.nix or equivalent.

If you don’t like the auto-import behavior, just delete or comment out that line, after that, the import statements become necessary.

Example of a module thats both NixOS and home-manager zsh.nix

~/flake/parts/shells/zsh.nix:

{
  flake.nixosModules.zsh =
    {
      pkgs,
      lib,
      config,
      username,
      ...
    }:
    let
      cfg = config.custom.zsh;
    in
    {
      options.custom.zsh = {
        enable = lib.mkEnableOption "User zsh configuration";
      };

      config = lib.mkIf cfg.enable {

        # 1. NixOS System-Level (The "Foundation")
        programs.zsh.enable = true;
        users.defaultUserShell = pkgs.zsh;
        environment.pathsToLink = [ "/share/zsh" ]; # Fixes completion for system packages

        # 2. Home Manager (User Configuration)
        home-manager.users.${username} = {
          programs.zsh = {
            enable = true;
            enableCompletion = true;
            completionInit = "autoload -U compinit && compinit";
            autosuggestion.enable = true;
            syntaxHighlighting.enable = true;
            oh-my-zsh = {
              package = pkgs.oh-my-zsh;
              enable = true;
              plugins = [
                "git"
                "sudo"
                "rust"
                "fzf"
              ];
            };
            profileExtra = ''
              if [ -z "$DISPLAY" ] && [ "$XDG_VTNR" = 1 ]; then
               exec mango
              fi
              # ---snip----
}

NOTE: Passing username through specialArgs is what makes this bridge work, you can also just use your username.

This is what ~/flake/parts/shells/default.nix looks like, I had to explicitly add myLib in a let statement to prevent infinite recursion:

{ lib, ... }:
let
  # prevents infinite recursion error
  myLib = import ../../lib { inherit lib; };
in
{
  # Now we can use it safely
  imports = myLib.scanPaths ./.;
}

Enable it in configuration.nix or equivalent:

custom.zsh.enable = true;

lib/default.nix is just a function that automatically imports any .nix file, skipping default.nix:

`lib/default.nix`

{ lib, ... }:
{
  # Returns a list of all .nix files and directories in a path,
  # skipping default.nix. Perfect for the 'imports' list.
  scanPaths =
    path:
    let
      content = builtins.readDir path;
    in
    map (name: path + "/${name}") (
      builtins.attrNames (
        lib.filterAttrs (
          name: type: (type == "directory") || (name != "default.nix" && lib.hasSuffix ".nix" name)
        ) content
      )
    );

  relativeToRoot = lib.path.append ../.;
}

The key here is wrapping the home-manager logic in home-manager.users.${username} = {}, this effectively creates a home-manager sandbox enabling configuration of both in the same file.

NOTE: You can do this without flake-parts also but often wasn’t recommended because the files become a mess that’s hard to understand.

Example using perSystem

In the flake.nix, notice the inputs.treefmt-nix.flakeModule. Since a formatter is something that you would want to run on every system, you use the perSystem attribute.

Adding the inputs.treefmt-nix.flakeModule makes the treefmt options available

~/flake/parts/treefmt.nix:

{
  perSystem = _: {
    treefmt = {
      projectRootFile = "flake.nix";

      programs = {
        deadnix.enable = true;
        statix.enable = true;
        keep-sorted.enable = true;
        nixfmt = {
          enable = true;
          # package = pkgs.nixfmt;
        };
      };

      settings = {
        global.excludes = [
          "LICENSE"
          "README.md"
          ".adr-dir"
          "nu_scripts"
          "*.{gif,png,svg,tape,mts,lock,mod,sum,toml,env,envrc,gitignore,sql,conf,pem,key,pub,py,narHash}"
          "Cargo.lock"
          "flake.lock"
          "justfile"
          ".jj/*"
        ];

        formatter = {
          nixfmt.priority = 1;
          statix.priority = 2;
          deadnix.priority = 3;
        };
      };
    };
  };
}

By using perSystem, your treefmt configuration is automatically available for every architecture you support (x86, ARM, etc.), allowing you to run nix fmt on any machine without rewriting the logic.

import-tree automatically imports this because it’s a flake-parts module & flake output.

flake-parts & numtide devshells

Adding this flake input and flakeModule make the options available, they’re similar to NixOS’s devShell but not the same:

devshell.url = "github:numtide/devshell";

~/flake/parts/dev-shell.nix:

{
  perSystem =
    { pkgs, system, ... }:
    {
      devshells.default = {
        name = "nixos-dev";

        packages = with pkgs; [
          nixfmt
          deadnix
          nixd
          nil
          nh
          nix-diff
          nix-tree
          helix
          git
          ripgrep
          jq
          tree
        ];

        # Message of the Day
        motd = ''
          {2}── NixOS Dev Shell ──────────────────────────────────────────{reset}
          {9}  System: {reset} ${system}
          {2}──────────────────────────────────────────────────────────────{reset}
        '';

        commands = [
          {
            name = "rebuild";
            package = "nh";
            help = "Run nh os switch on the current flake";
            command = "nh os switch .";
          }
          {
            name = "fmt";
            package = "nixfmt";
            help = "Format all nix files in the project";
            command = "nix fmt";
          }
        ];
      };
    };
}

Enter devShell:

cd ~/flake
nix develop

ZFS Bare Metal Impermanence

2026-03-01T00:00:00+00:00

ZFS Imperm Bare-Metal

I couldn’t get disko to bend to my will so I wrote the following bash script. The script automates the steps in Graham Christensen’s Erase your darlings

The Storage Architecture

The script below automates the “Erase Your Darlings” setup. It organizes your data into three distinct “levels” of persistence:

The Volatile (/): A ZFS dataset that is blank at boot. We take a snapshot called @blank immediately after creation. In your NixOS configuration, you will set up a boot-time script to roll back to this @blank snapshot, effectively “formatting” your root in milliseconds.
The Store (/nix): A separate dataset for the Nix store. This doesn’t need to be wiped because Nix already manages its own integrity.
The Safe (/persist and /home): These datasets hold the things you actually care about—your SSH keys, browser profiles, and project files.

What this script automates

This bash script handles the “Stage 0” heavy lifting. It will:

Partition your disk with an EFI boot partition and a LUKS2 encrypted container.
Initialize a ZFS pool (rpool) with performance-optimized settings (like ashift=12 and zstd compression).
Carve out the datasets required for an Impermanence setup.
Mount the hierarchy into /mnt so nixos-generate-config can detect the specialized ZFS layout.

WARNING: This is a destructive operation. Running this script will wipe the target drive completely. Ensure you have backed up any existing data before proceeding.

The Setup Script

Quick Start

Start with the minimal ISO:

NixOS Downloads
NixOS Manual Installation
The script handles the partitioning, formatting, mounting, and lastly, runs nixos-generate-config --root /mnt. After running the script, edit the files in the repo matching your user and device. Finally, after you’re sure you haven’t missed anything, run nixos-install.

export NIX_CONFIG='experimental-features = nix-command flakes'

Clone the starter repo:

git clone https://github.com/saylesss88/my-flake2.git

Inspect & Run the script provided with the repo & follow prompts.:

WARNING: This is a destructive operation. Running this script will wipe the target drive completely. Ensure you have backed up any existing data before proceeding.

sudo chmod +x ./install.sh
sudo bash ./install.sh

I tested the script on an nvme0n1 drive with no issues.

Run the following commands:

# Get your UUID#
sudo blkid /dev/YOUR_DISK > /tmp/blk.txt
# Generate a hashed password
mkpasswd -m yescrypt > /tmp/pass.txt
# Generate a rand # for `networking.hostId`
head -c4 /dev/urandom | xxd -p > /tmp/rand.txt

Edit flake.nix, configuration.nix, and replace the repos hardware-configuration.nix with your own.
Add neededForBoot to the home and persist datasets in the generated hardware-configuration.nix.

Example:

  fileSystems."/home" = {
    device = "rpool/safe/home";
    fsType = "zfs";
    neededForBoot = true;
  };

  fileSystems."/persist" = {
    device = "rpool/safe/persist";
    fsType = "zfs";
    neededForBoot = true;
  };

Move the flake to /mnt/etc/nixos/

sudo mv ~/my-flake2 /mnt/etc/nixos/

Do a final check and install (change host to your host name)

sudo nixos-install --flake /mnt/etc/nixos/myflake2#host

Read the comments, they let you know of requirements.

Reboot. I typically run nixos-install with the minimal requirements, reboot, and then configure my window manager/DE.
After reboot, adjust permissions for your $USER:

sudo mkdir -p /persist/home/$USER
# Set ownership for the persistent home directory
sudo chown -R 1000:100 /persist/home/$USER

# Ensure the home dataset itself is accessible
sudo chmod 755 /home
sudo chmod 755 /persist/home
# Test file, should be gone after reboot
sudo touch /etc/rollback-canary

Uncomment the import of the impermanence module in the configuration.nix.
Reboot, then check:

sudo ls /etc/rollback-canary

You should get an error: "/etc/rollback-canary": No such file or directory (os error 2)

What gets Wiped vs. What Stays

What gets wiped?:

Since we roll back (rpool/local/root):

/etc (including system configs) -> WIPED
/var (logs, databases, containers) -> WIPED
/root (the root users home directory) -> WIPED
/usr (though in NixOS this is mostly empty) -> WIPED

What survives?:

/nix (mounted from rpool/local/nix) -> PERSISTS
/boot (mounted from rpool/local/boot) -> PERSISTS
/home (mounted from rpool/safe/home) -> PERSISTS
/persists (mounted from rpool/safe/persist) -> PERSISTS

NixOS Containers

2026-01-30T00:00:00+00:00

Idiomatic Nix

There are quite a few resources out there that share best practices, but no single unified place to find them all. I’m going to try to build on nix.dev’s Best practices, by doing some research as well as examining the code of some of the leaders in the NixOS world. (Tweag, numtide, etc.)

✔️ mdbook-nix-repl for interactive code blocks

I’ve added a flake.nix to the mdbook-nix-repl repo, you can add it as a flake input:

flake.nix:

# flake.nix
{
  inputs = {
    nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";

    mdbook-nix-repl.url = "github:saylesss88/mdbook-nix-repl?dir=server";
  };

  outputs = { self, nixpkgs, mdbook-nix-repl, ... }: {
    nixosConfigurations.magic = nixpkgs.lib.nixosSystem {
      system = "x86_64-linux";
      modules = [
        ./configuration.nix

        mdbook-nix-repl.nixosModules.default
      ];
    };
  };
}

configuration.nix:

{ pkgs, ... }:
{
  imports = [
  ];

  # This option is now provided by the module you imported from the flake
  custom.nix-repl-server = {
    enable = true;
    port = 8080;
    tokenFile = "/etc/nix-repl-server.env";
  };
}

Copy the value of NIX_REPL_TOKEN in theme/index.hbs, and add create file /etc/nix-repl-server.env:

# Create the file with strict permissions (root read-only)
sudo touch /etc/nix-repl-server.env
sudo chmod 600 /etc/nix-repl-server.env

# Edit it to add: NIX_REPL_TOKEN=your_token_from_index_hbs
sudo vim /etc/nix-repl-server.env

Expected format:

NIX_REPL_TOKEN=9deb7efadb74b9e962e7911bb5caf3b3fef275a1b915b526

Rebuild, and the server will now be running at boot.

All the following examples are interactive, press play to see the result.(The following examples come directly from nix.dev)

rec {
    a = 1;
    b = a + 2;
}

Use this instead:

let
  a = 1;
in {
    a = a;
    b = a + 2;
}

💡 TIP Self-reference can be achieved by explicitly naming the attribute set:

 let
   argset = {
     a = 1;
     b = argset.a + 2;
  };
in
  argset

Updating nested attribute sets

{ a = 1; b = 2; } // { b = 3; c = 4; }

Updates are shallow, names on the right take precidence:

{ a = { b = 1; }; } // { a = { c = 3; }; }

let pkgs = import <nixpkgs> {}; in
pkgs.lib.recursiveUpdate { a = { b = 1; }; } { a = { c = 3;}; }

Secure Boot on Libvirt stack

2026-01-19T00:00:00+00:00

Secure Boot in a Libvirt (KVM) VM with ZFS on LUKS Impermanence

Initial VM Setup

When creating the VM in virt-manager:

Before clicking “Finish”, check the “Customize configuration before install” box
In the Overview section, change Firmware from BIOS to UEFI x86_64: /usr/share/edk2/ovmf/OVMF_CODE_4M.secboot.qcow2
Proceed with the NixOS installation as normal. For lanzaboote to build successfully, I had to pin it to nixpkgs 25.05.

Known Issue: After running nixos-install and rebooting, the SATA CDROM source path may be cleared. If the VM fails to boot, manually reselect the NixOS ISO in the SATA settings and reboot.

Configure Firmware for Custom Secure Boot Keys

The default configuration uses Microsoft’s pre-enrolled keys, which won’t trust your custom-signed kernel. To enable custom key enrollment, you need to modify the VM’s XML configuration.

On your host, find your VM name:

virsh -c qemu:///system list --all

Example Output:

 Id   Name             State
---------------------------------
 -    nixos-unstable   shut off
 -    nixos            shut off

Edit the VM configuration:

virsh edit nixos-unstable

Make the following changes to the <os> section:

Change the enrolled-keys feature from yes to no:

<feature enabled='no' name='enrolled-keys'/>

Delete the explicit <loader> and <nvram> lines. These conflict with libvirt’s firmware autoselection when using enrolled-keys='no':

<!-- DELETE THESE TWO LINES -->
<loader readonly='yes' secure='yes' type='pflash' format='qcow2'>/usr/share/edk2/ovmf/OVMF_CODE_4M.secboot.qcow2</loader>
<nvram template='/usr/share/edk2/ovmf/OVMF_VARS_4M.secboot.qcow2' templateFormat='qcow2' format='qcow2'>/var/lib/libvirt/qemu/nvram/nixos-unstable_VARS.qcow2</nvram>

Your final <os> section should look like this:

<os firmware='efi'>
  <type arch='x86_64' machine='pc-q35-10.1'>hvm</type>
  <firmware>
    <feature enabled='no' name='enrolled-keys'/>
    <feature enabled='yes' name='secure-boot'/>
  </firmware>
  <boot dev='hd'/>
</os>

Add the <serial> tag as a best practice

    <disk type='file' device='disk'>
      <driver name='qemu' type='qcow2' discard='unmap'/>
      <source file='/var/lib/libvirt/images/nixos-unstable-1.qcow2'/>
      <serial>disk01</serial>
      <target dev='vda' bus='virtio'/>
      <address type='pci' domain='0x0000' bus='0x04' slot='0x00' function='0x0'/>
    </disk>

This enables commands like: zpool import -d /dev/disk/by-id rpool

Save and exit the editor. Libvirt will now automatically create a new NVRAM file in Setup Mode (no keys enrolled).

NixOS Installation with ZFS on root with LUKS

ZFS on root with LUKS & Impermanence

Add the impermanence flake input. I also had to pin lanzaboote to nixpkgs 25.05 for lanzaboote to build successfully:

inputs = {
   impermanence.url = "github:nix-community/impermanence";
   nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
   nixpkgs-stable.url = "github:nixos/nixpkgs/nixos-25.05";
};

Add lanzaboote, if you don’t use unstable, you can obviously avoid the overlay:

{ pkgs, lib, inputs, ... }: {
# configuration.nix
nixpkgs.overlays = [
   (final: prev: {
      lanzaboote = (inputs.nixpkgs-stable.legacyPackages.${pkgs.system}.lanzaboote or prev.lanzaboote)
   })
];

environment.systemPackages = [ pkgs.sbctl ];

boot.loader.systemd-boot.enable = lib.mkForce false;

boot.lanzaboote = {
  enable = true;
  pkiBundle = "/var/lib/sbctl";
};
}

And impermanence.nix:

{ inputs, lib, ... }: {
   imports = [
      inputs.impermanence.nixosModules.impermanence
   ];
   boot.initrd.postMountCommands = lib.mkAfter ''
     zfs rollback -r rpool/local/root@blank
   '';
   environment.persistence."/persist" = {
      directories = [ "/var/lib/sbctl" "/var/lib/nixos" ];
   };
   fileSystems."/persist" = {
      device = "rpool/safe/persist";
      fsType = "zfs";
      neededForBoot = true;
   };
}

Lanzaboote Installation

Secure Boot with Lanzaboote

Enroll the Secure Boot Keys

After the XML changes, boot the VM and enter the firmware setup (press ESC during boot).

Navigate to Device Manager → Secure Boot Configuration
Switch to “Custom mode”, uncheck Attempt Secure Boot [ ], select “Reset Secure Boot Keys”, save with F10, and reboot.
Enroll the keys: sudo sbctl enroll-keys -m
Reboot: After enrolling the keys and rebooting, the system will automatically be placed in “Standard mode”, and Attempt Secure Boot [x] selected. You do not need to re-enter firmware setup mode.
Verify Secure Boot Status: bootctl status

ZFS with LUKS and Impermanence

2026-01-17T00:00:00+00:00

ZFS with LUKS and Impermanence

✔️ Table of Contents

I tested this on the libvirt stack with KVM, this should work on bare metal with a few omissions.

✔️ SSH Method

This saves a ton of typing…

Boot the minimal ISO
Set a password for the nixos user: sudo passwd nixos
Find the IP address: ip a (look for etho or wlan0)
SSH in from your host or another machine: ssh nixos@192.168.1.x

Starter Repo containing a flake and the configuration.nix from this chapter

git clone https://github.com/saylesss88/my-flake2.git

I included a personally tested script that handles all of the steps up until you start configuring the configuration.nix.

cd my-flake2
sudo chmod +x install.sh
sudo ./install.sh

You will be prompted to enter your disk, just enter the disk, not anything else, like this:

vda
# OR
nvme0n1

After the first script completes, there is a test.sh script that ensures everything is in order.

sudo chmod +x test.sh
sudo ./test.sh

What is OpenZFS

ZFS is an advanced filesystem, originally developed by Sun Microsystems in 05.

OpenZFS is a fork of the proprietary Oracle ZFS, it was forked over a decade ago. Most of the code remains the same so you can check the Oracle website for docs and administration guides.

ZFS is licensed under the Common Development and Distribution License (CDDL). Because the CDDL is incompatible with the GPL, it is not possible for ZFS to be included in the Linux Kernel. This requirement, however, does not prevent a native Linux kernel module from being developed and distributed by a third party, as is the case with OpenZFS (previously named ZFS on Linux). –arch wiki

Comparison: OpenZFS Native Encryption vs. LUKS

✔️ OpenZFS Native Encryption vs. LUKS

NOTE: This isn’t an attack on ZFS Native Encryption, I’m just presenting the information, the choice is yours. Unless you have a high threat model, ZFS native encryption has many benefits such improved flexibility and authentication.

LUKS (Device Layer): LUKS operates on the block device (like /dev/nvme0n1). It knows nothing about files, folders, or datasets. It just sees a stream of bytes and scrambles them.
- Everything on the partition is encrypted. The filesystem sits inside the encrypted container.
- With standard LUKS, an adversary can see you are using encryption (the LUKS header is visible), but they cannot determine what filesystem (ZFS, ext4, etc.) is inside. If you go a step further and use a detached header, the entire drive looks like random noise, providing plausible deniability that any data exists at all.
ZFS Native (Filesystem Layer): ZFS encryption operates at the Dataset (Filesystem) level. It is aware of the structure of your data.
- Only the file blocks (the actual content of your files) and the file attributes (ACLs, permissions) within a specific dataset are encrypted.

No matter how careful you are with ZFS Native encryption, these cannot be hidden:

The Structure: The fact that dataset A is a child of dataset B
The Volume: The exact amount of disk space used by each dataset (in bytes)
The Activity: The fact that something changed at a specific time (via snapshot creation or used property changing)

By using generic dataset names (e.g., data/vol1 instead of data/mistress_photos) and automated snapshot schedules, you can strip the semantic value from the exposed metadata. An attacker will see that you have data and how much you have, but they won’t know what it is or which dataset is the valuable one.

Sanitizing your ZFS usage (Mitigating risk):

By following a few simple best practices you can mitigate most, if not all of the risk depending on the situation.

Use generic IDs for dataset names, instead of tank/mistress_photos use tank/vol-A
Automate your snapshots to prevent traffic analysis
Use padding to mitigate size analysis, add dummy files to obfuscate the size (Can be tedious in ZFS). This is the hardest to mitigate, if this is a real threat, use LUKS instead.

OpenZFS native encryption allows you to transparently encrypt data at rest within ZFS itself. It was initially released in May 2019, giving it much less time to be scrutinized compared to LUKS (initial release in 2004).

OpenZFS Encryption operates at the dataset layer, not the disk layer, which creates several critical security gaps that full-disk encryption (FDE) solutions like LUKS completely avoid.

Unlike LUKS, which presents a “black box” of random noise to anyone without the key, ZFS Native Encryption must leave certain structural elements visible to the operating system. This is a deliberate design choice that allows ZFS to perform maintenance tasks (like scrubbing) on locked datasets without requiring the user to type in a password. (Depending on your threat model, this can be a deal breaker).

Threat Example

Example: Threat Model where ZFS Native Encryption falls short compared to LUKS

The “Pattern of Life” Attack (Timestamp Leaks)

The Leak: ZFS snapshot names and creation times are visible in plaintext (zfs list -t snapshot)

The Threat Model: An adversary monitoring your backups or seizing your drive can build a profile of your behavior without decrypting a single byte.

If you claim to be asleep at 3AM, but zfs list shows snapshots being created or data changing size at 3:15 AM, your alibi is broken.
Or, say a whistleblower contacts a journalist. An adversary seizes the journalist’s laptop. They can’t read the files, but they see a new dataset grew by exactly 5GB at the exact time the leak occured. Correlation = Guilt.

Compress & Encrypt:

It’s actually a common misconception that LUKS prevents compression before encryption, both methods are able to do this.

ZFS Native: Data -> Compress -> Encrypt -> Checksum -> Write to Disk
ZFS on LUKS: Data -> Compress -> ZFS Write -> LUKS Encrypt -> Write to Disk

Both methods save disk space.

Integrety and Authentication:

This is the strongest architectural argument for ZFS Native.

ZFS Native: Uses AES-GCM (default) which is an Authenticated Encryption with Associated Data (AEAD) mode. If a single bit is flipped on disk (maliciously or accidentally), ZFS refuses to return the bad data and reports a checksum error.
- NOTE: You can get integrity with LUKS2 with dm-integrity, but it incurs a massive performance penalty and is considered experimental for production use.

ZFS Native Encryption OR LUKS

Use LUKS if:

You can’t afford to leak metadata like dataset names or snapshot timestamps. LUKS makes the drive look like random noise.
You require rock-solid stability. The ZFS-on-LUKS stack is very “battle-tested”.

Use ZFS Native Encryption if:

You have “Untrusted” Offsite Backups: This is a really nice feature! You can zfs send -w your data to a friend’s server or a cloud VM. The remote host cannot mount or read your data because they never have the key, but they can still scrub the pool and verify the data integrity.
You need granular control: ZFS Native Encryption allows you to for example, keep your OS root unencrypted for fast booting/repair, but your /home directory encrypted.
You run many VMs/Containers: You can create a new encrypted dataset for a specific project/client without repartitioning or creating loopback files.
You want to verify data authenticity.
arsTechnica quick start to openzfs-native-encryption
Practical ZFS is native encryption ready for production use?

Getting Started

When creating the VM, before clicking “Finish”, check the “Customize configuration before install” box and choose EFI Firmware > BIOS. You will waste a bunch of time if you forget to do this!

I used OVMF_CODE.fd in my testing.

Format your disk

Partition & Format

sudo cfdisk /dev/vda
sudo mkfs.fat -F32 /dev/vda1

Setup LUKS

sudo cryptsetup luksFormat /dev/vda2
sudo cryptsetup open /dev/vda2 cryptroot

Create zpool (Edited 2026-01-18 normalization=none)

sudo zpool create \
  -o ashift=12 \
  -o autotrim=on \
  -O acltype=posixacl \
  -O canmount=off \
  -O compression=zstd \
  -O normalization=none \
  -O relatime=on \
  -O xattr=sa \
  -O dnodesize=auto \
  -O mountpoint=none \
  rpool /dev/mapper/cryptroot

Dataset Creation

# root (ephemeral)
sudo zfs create -p -o canmount=noauto -o mountpoint=legacy rpool/local/root
sudo zfs snapshot rpool/local/root@blank

# nix store
sudo zfs create -p -o mountpoint=legacy rpool/local/nix

# persistent data
sudo zfs create -p -o mountpoint=legacy rpool/safe/home
sudo zfs create -p -o mountpoint=legacy rpool/safe/persist

mountpoint=legacy means that systemd will take care of the mounting

Mounting

# 1. Mount root first
sudo mount -t zfs rpool/local/root /mnt

# 2. Create directories
sudo mkdir -p /mnt/{nix,home,persist,boot}

# 3. Mount ESP directly to /boot (simpler and safer for systemd-boot)
sudo mount -t vfat -o umask=0077 /dev/vda1 /mnt/boot

# 4. Mount other ZFS datasets
sudo mount -t zfs rpool/local/nix /mnt/nix
sudo mount -t zfs rpool/safe/home /mnt/home
sudo mount -t zfs rpool/safe/persist /mnt/persist

Configuration Prep

sudo nixos-generate-config --root /mnt

export NIX_CONFIG='experimental-features = nix-command flakes'
nix-shell -p helix

sudo blkid /dev/vda2
# Copy the uuid

# configuration.nix
 boot.initrd.luks.devices = {
     cryptroot = {
       device = "/dev/disk/by-uuid/uuid#";
       allowDiscards = true;
       preLVM = true;
     };
   };

boot.initrd.luks.devices."cryptroot".device = "/dev/disk/by-uuid/<UUID-OF-PARTITION-2>";

Prep `configuration.nix`

head -c4 /dev/urandom | xxd -p > /tmp/rand.txt

Create password file in a persistent location:

sudo mkdir -p /mnt/persist/etc/nixos-secrets/passwords

 #1) This is for `initialHashedPassword`
 #   Read this in with `:r /tmp/pass.txt`
mkpasswd --method=yescrypt > /tmp/pass.txt

After first reboot, the above files will be placed directly under /persist/

(Edited 2026-01-18 use postMountCommands > postResumeCommands)

{ config, lib, pkgs, ... }:

{
  # ------------------------------------------------------------------
  # 1. Boot loader – systemd-boot (UEFI only)
  # ------------------------------------------------------------------
  boot.loader = {
    systemd-boot = {
      enable = true;
      consoleMode = "max";
      editor = false;
    };
    efi = {
      canTouchEfiVariables = true;
      efiSysMountPoint = "/boot";
    };
  };

  # ------------------------------------------------------------------
  # 2. ZFS support see: https://openzfs.github.io/openzfs-docs/Getting%20Started/NixOS/index.html
  # ------------------------------------------------------------------
  boot.supportedFilesystems = [ "zfs" ];
  boot.zfs.devNodes = "/dev/";       # Critical for VMs
  # Not needed with LUKS
  boot.zfs.requestEncryptionCredentials = false;
  # systemd handles mounting
  systemd.services.zfs-mount.enable = false;

  services.zfs = {
    autoScrub.enable = true;
    # periodically runs `zpool trim`
    trim.enable = true;
    # autoSnapshot = true;
  };

  # ------------------------------------------------------------------
  # 3. LUKS
  # ------------------------------------------------------------------
   boot.initrd.luks.devices = {
     cryptroot = {
    # replace uuid# with output of UUID # from `sudo blkid /dev/vda2`
       device = "/dev/disk/by-uuid/uuid#";
       allowDiscards = true;
       preLVM = true;
     };
   };

  # ------------------------------------------------------------------
  # 4. Roll-back root to blank snapshot on **every** boot
  # ------------------------------------------------------------------
 # Uncomment after first reboot
 # boot.initrd.postMountCommands = lib.mkAfter ''
 #   zfs rollback -r rpool/local/root@blank
 # '';

  # ------------------------------------------------------------------
  # 5. Basic system (root password, serial console for VM)
  # ------------------------------------------------------------------
  # Unique 8-hex hostId (run once in live ISO: head -c4 /dev/urandom | xxd -p)
  networking.hostId = "a1b2c3d4";    # <<<--- replace with your own value

  users.users.root.initialPassword = "changeme";   # change after first login

  boot.kernelParams = [ "console=tty1" ];

  # ------------------------------------------------------------------
  #  Users
  # ------------------------------------------------------------------

  users.mutableUsers = false;

  # Change `your-user`
  users.users.your-user = {
    isNormalUser = true;
    extraGroups = [ "wheel" ];
    group = "your-user";
    # :r /tmp/pass.txt:
    initialHashedPassword = "";
  };

  # This enables `chown -R your-user:your-user`
  users.groups.your-user = { };

  # ------------------------------------------------------------------
  #  (Optional) Helpful for recovery situations
  # ------------------------------------------------------------------
  # users.users.admin = {
  #  isNormalUser = true;
  #  description = "admin account";
  #  extraGroups = [ "wheel" ];
  #  group = "admin";
    # initialHashedPassword = "Output of `:r /tmp/pass.txt`";
 # };

 # users.groups.admin = { };
  # ------------------------------------------------------------------

  # ------------------------------------------------------------------
  # 6. (Optional) Enable SSH for post-install configuration
  # ------------------------------------------------------------------
  # services.openssh = {
  #  enable = true;
  #  settings.PermitRootLogin = "yes";
  #};

  # ------------------------------------------------------------------
  # 7. Mark /persist as needed for boot
  # ------------------------------------------------------------------
  fileSystems."/persist".neededForBoot = true;
}

After reboot, you can uncomment:

  boot.initrd.postMountCommands = lib.mkAfter ''
    zfs rollback -r rpool/local/root@blank
  '';

Uncomment the above script and test: (Don’t forget that the /etc directory will be wiped, including your configuration.nix and hardware-configuration.nix!)

Configuration backup

sudo mkdir -p /persist/etc
sudo cp /etc/nixos/hardware-configuration.nix /etc/nixos/configuration.nix /persist/etc/

Rollback Test

sudo touch /etc/rollback-canary
sudo reboot

If the rollback is working, /etc/rollback-canary should be gone after reboot (while things in /persist remain).

Adding a disk serial (libvirt XML)

NixOS ZFS boot support is broken for virtio drives without serial numbers. Virtio disks without serials don’t appear in /dev/disk/by-id, but ZFS boot logic only tries to import pools from /dev/disk/by-id. The official OpenZFS NixOS documentation explicitly states: “If virtio is used as disk bus, power off the VM and set serial numbers for disk”

In the <disk ...> block of your root disk add:

Add to .zshrc:

export LIBVIRT_DEFAULT_URI="qemu:///system"

virsh list --all
virsh edit nixos-unstable

In the first <disk ... device='disk'> section (the one with target dev='vda' bus='virtio'), add a <serial> line, e.g.:

<disk type='file' device='disk'>
  <driver name='qemu' type='qcow2' discard='unmap'/>
  <source file='/var/lib/libvirt/images/nixos-unstable-1.qcow2' index='2'/>
  <backingStore/>
  <target dev='vda' bus='virtio'/>
  <serial>disk01</serial>
  <alias name='virtio-disk0'/>
  ...
</disk>

Issues I’ve Come Across

sops-nix README: Explicitly warns: “If you are using Impermanence, the key used for secret decryption … must be in a persisted directory, loaded early enough during boot.” It specifically cites activation timing as the reason this fails.

Typically the solution was to add neededForUsers = true; in your “password_hash” block but that isn’t working for this setup. (ZFS/LUKS/Imperm)

I’ve been using initialHashedPassword, which bypasses the race entirely by baking the salted hash into the store. This is all that I’ve found that works so far…

Without adding the <serial>disk01</serial> to the XML when you reboot, your system will hang before asking for your LUKS password.
Without clicking “Customize configuration before install” box and choosing EFI Firmware instead of the default BIOS, you will not be able to boot at all. This seems to be the case for all custom disk layouts with NixOS on the libvirt stack.

Resources

✔️ Resources

ZFS Impermanence in a VM

2026-01-16T00:00:00+00:00

ZFS Impermanence in a VM

✔️ Table of Contents

Yet another blog post inspired by erase your darlings

I only tested this within a VM although with a few small tweaks it should work on bare metal. I used the libvirtd stack with KVM for this.

NOTE: This example doesn’t use encryption, it would be easy to add ZFS Native Encryption by changing the first zpool command. It’s good enough for most people but does leak some metadata. I’ll add a LUKS example eventually which is more involved.

Starter Repo containing a flake and the configuration.nix from this chapter

git clone https://github.com/saylesss88/my-flake2.git

✔️ SSH Method to enable copy-paste

Boot the minimal ISO
Set a password for the nixos user: sudo passwd nixos
Find the IP address: ip a (look for eth0 or wlan0)
SSH in from another machine: ssh nixos@192.168.1.x
Clone the repo and copy-paste commands from your browser to the terminal.

✔️ Multi-TTY Method (No extra Devices)

Log in on the default TTY (usually Alt+F1).
Switch to a second TTY by pressing Alt+F2.
Log in again (user nixos, no password default).
Clone your repo in TTY2: git clone https://github.com/your/repo.
Open the README with a pager: less repo/README.md.
Switch back to TTY1 (Alt+F1) to execute commands.
Toggle back and forth (Alt+F2 / Alt+F1) to read and type.

✔️ tmux Method (Split Screen)

The minimal ISO includes tmux in the package set, but it’s not installed in the environment by default.

Run: nix run nixpkgs#tmux
Once inside tmux, split the screen vertically: Press Ctrl+b then %
In the right pane, open the README: less repo/README.md
In the left pane, type the commands
Switch panes with Ctrl+b then Left/Right Arrow

Start with a minimal ISO.

Download Minimal (64-bit Intel-AMD)

Choose the LTS image, it comes with the zfs module enabled.

I’ve also found that for my system it works best to switch the Video Model to Virtio, with 3D accelleration disabled (causes mouse inversion).

I used OVMF_CODE.fd in my testing.

Check out your layout:

sudo fdisk -l

Format your disk:

sudo cfdisk /dev/vda

Create a 1G EFI System first, then a Linux Filesystem with the remaining space. I used (100G)

For the following guide, you want /dev/vda1 to be your EFI System partition, and /dev/vda2 to be the Linux Filesystem partition.

sudo fdisk -l

sudo mkfs.vfat -n EFI /dev/vda1

Create Your ZFS Partitions

Create a zpool: (Edited 2026-01-18 normalization=none)

zpool create \
  -o ashift=12 \
  -o autotrim=on \
  -O acltype=posixacl \
  -O canmount=off \
  -O dnodesize=auto \
  -O normalization=none \
  -O relatime=on \
  -O xattr=sa \
  -O mountpoint=none \
  rpool /dev/vda2

ZFS Native Encryption (Work in Progress)

zpool create -f \
  -o ashift=12 \
  -O encryption=aes-256-gcm \
  -O keyformat=passphrase \
  -O keylocation=prompt \
  -O mountpoint=none \
  -O acltype=posixacl \
  -O compression=lz4 \
  -O xattr=sa \
  rpool /dev/vda2

I just got impermanence working without encryption, I haven’t been able to test and iron out any quirks of this encryption method..

Create all datasets with parents (-p):

# root (ephemeral – will be rolled back)
zfs create -p -o canmount=noauto -o mountpoint=legacy rpool/local/root

# blank snapshot (the “erase” target)
zfs snapshot rpool/local/root@blank

zfs create -p -o mountpoint=legacy rpool/local/boot
# /nix – read-only store, must survive rollbacks
zfs create -p -o mountpoint=legacy rpool/local/nix

# persisted areas
zfs create -p -o mountpoint=legacy rpool/safe/home
zfs create -p -o mountpoint=legacy rpool/safe/persist

Mount everything under /mnt:

mount -t zfs rpool/local/root /mnt

mkdir -p /mnt/{boot,boot/efi,nix,home,persist}
mount -t vfat -o umask=0077 /dev/vda1 /mnt/boot/efi
mount -t zfs rpool/local/nix   /mnt/nix
mount -t zfs rpool/safe/home  /mnt/home
mount -t zfs rpool/safe/persist /mnt/persist

Note: By placing your Nix flake in /home/user/nixos-config (which lives on rpool/safe/home), it persists naturally. You don’t need to add your configuration files to the environment.persistence module lists because the underlying storage isn’t being wiped.

Continue with the rest of the install

nixos-generate-config --root /mnt
# edit /mnt/etc/nixos/configuration.nix  (add ZFS + rollback + impermanence)

✔️ Quick checklist:

Quick checklist to confirm that you’ve taken all of the necessary steps.

# 1. pool
zpool create -o ashift=12 -o autotrim=on -O acltype=posixacl -O canmount=off \
  -O dnodesize=auto -O normalization=formD -O relatime=on -O xattr=sa \
  -O mountpoint=none rpool /dev/vda2

# 2. datasets + snapshot
zfs create -p -o canmount=noauto -o mountpoint=legacy rpool/local/root
zfs snapshot rpool/local/root@blank
zfs create -p -o mountpoint=legacy rpool/local/nix
zfs create -p -o mountpoint=legacy rpool/safe/home
zfs create -p -o mountpoint=legacy rpool/safe/persist
# add a /boot dataset
zfs create -p -o mountpoint=legacy rpool/local/boot

# 3. mounts
mount -t zfs rpool/local/root /mnt
mkdir -p /mnt/{boot,boot/efi,nix,home,persist}

# /boot on ZFS
mount -t zfs rpool/local/boot /mnt/boot

# ESP on /boot/efi
mount -t vfat -o umask=0077 /dev/vda1 /mnt/boot/efi

mount -t zfs rpool/local/nix /mnt/nix
mount -t zfs rpool/safe/home /mnt/home
mount -t zfs rpool/safe/persist /mnt/persist

Prep `configuration.nix`

head -c4 /dev/urandom | xxd -p > /tmp/rand.txt

Create password file in a persistent location:

sudo mkdir -p /mnt/persist/etc/nixos-secrets/passwords

# 2) Create the password hash and write it to the persistent file
# Replace "your-password" and "your-user"
sudo sh -c 'mkpasswd -m yescrypt "your-password" > /mnt/persist/etc/nixos-secrets/passwords/your-user'

# 3) Lock down permissions
sudo chown root:root /mnt/persist/etc/nixos-secrets/passwords/your-user
sudo chmod 600 /mnt/persist/etc/nixos-secrets/passwords/your-user

After first reboot, the above files will be placed directly under /persist/

You will read rand.txt into the configuration.nix with :r /tmp/rand.txt.

Edit the /mnt/etc/nixos/configuration.nix (Edited 2026-01-18 use postMountCommands instead of postResumeCommands) :

{ config, lib, pkgs, ... }:

{
  # ------------------------------------------------------------------
  # 1. Boot loader – systemd-boot (UEFI only)
  # ------------------------------------------------------------------
  boot.loader = {
    systemd-boot = {
      enable = true;
      consoleMode = "max";           # Full 80×25 console in VM
      editor = false;                # Security – no edit at boot
    };
    efi = {
      canTouchEfiVariables = true;   # libvirt provides /sys/firmware/efi
      efiSysMountPoint = "/boot/efi";    # Our 1 GiB FAT32 partition
    };
  };

  # ------------------------------------------------------------------
  # 2. ZFS support
  # ------------------------------------------------------------------
  boot.supportedFilesystems = [ "zfs" ];
  boot.zfs.devNodes = "/dev/";       # Critical for VMs

  # Unique 8-hex hostId (run once in live ISO: head -c4 /dev/urandom | xxd -p)
  networking.hostId = "a1b2c3d4";    # <<<--- replace with your own value

  # ------------------------------------------------------------------
  # 3. Roll-back root to blank snapshot on **every** boot
  # ------------------------------------------------------------------
# Uncomment after first reboot
#  boot.initrd.postMountCommands = lib.mkAfter ''
#    zfs rollback -r rpool/local/root@blank
#  '';

  # ------------------------------------------------------------------
  # 4. Basic system (root password, serial console for VM)
  # ------------------------------------------------------------------
  users.users.root.initialPassword = "changeme";   # change after first login
  boot.kernelParams = [ "console=ttyS0,115200n8" ];

  users.mutableUsers = false;

  users.users.your-user = {
    isNormalUser = true;
    extraGroups = [ "wheel" ];
    group = "your-user";
    # The location of `hashedPasswordFile` after first reboot
    hashedPasswordFile = "/persist/etc/nixos-secrets/passwords/your-user";
  };

  # This enables `chown -R your-user:your-user`
  users.groups.your-user = { };

  # ------------------------------------------------------------------
  # 5. (Optional) Enable SSH for post-install configuration
  # ------------------------------------------------------------------
  # services.openssh = {
  #  enable = true;
  #  settings.PermitRootLogin = "yes";
  #};

  # ------------------------------------------------------------------
  # 6. Mark /persist as needed for boot
  # ------------------------------------------------------------------
  fileSystems."/persist".neededForBoot = true;
}

sudo nixos-install --root /mnt

reboot

Copy your system files to a persistent location before uncommenting the impermanence script.

sudo mkdir -p /persist/etc
sudo cp /etc/nixos/configuration.nix /etc/nixos/hardware-configuration.nix /persist/etc/

Now, you can uncomment this block:

  boot.initrd.postMountCommands = lib.mkAfter ''
    zfs rollback -r rpool/local/root@blank
  '';

sudo touch /etc/rollback-canary
sudo reboot

If the rollback is working, /etc/rollback-canary should be gone after reboot (while things in /persist remain).

What gets Wiped vs. What Stays

What gets wiped?:

Since we roll back /(rpool/local/root):

/etc (including system configs) -> WIPED
/var (logs, databases, containers) -> WIPED
/root (the root users home directory) -> WIPED
/usr (though in NixOS this is mostly empty) -> WIPED

What survives?:

/nix (mounted from rpool/local/nix) -> PERSISTS
/boot (mounted from rpool/local/boot) -> PERSISTS
/home (mounted from rpool/safe/home) -> PERSISTS
/persists (mounted from rpool/safe/persist) -> PERSISTS

Why this matters for secrets?

SSH Host keys typically live in /etc/ssh. Since /etc is wiped, they disappear. Store them in /persist/etc/ssh and tell NixOS to look there. (or symlink them)

User Secrets (~/.config/sops): They live in /home so they’re safe.

Integrating into a Flake

After first reboot, I recommend setting up a flake in a persistent location such as /home/your-user/flake. Because subsequent reboots will wipe the /etc directory.

Example Flake, this is a WIP adaptation from another flake I had.

sudo mkdir /imperm_test
echo "This should be Gone after Reboot" | sudo tee /imperm_test/testfile
sudo ls -l /imperm_test/testfile # Verify the file exists
sudo cat /imperm_test/testfile # Verify content

Reboot and check again:

sudo ls -l /imperm_test/testfile # Verify the file no longer exists
sudo cat /imperm_test/testfile # Verify content is missing

Persisting SSH Keys

sudo mkdir -p /persist/etc/ssh
sudo ssh-keygen -t ed25519 -f /persist/etc/ssh/ssh_host_ed25519_key -N ""

OR if you still have keys in /etc/ssh you want to keep just copy them to the persistent location:

sudo cp /etc/ssh/ssh_host_ed25519_key* /persist/etc/ssh/

Tell NixOS where to find them

services.openssh = {
  hostKeys = [
    {
      path = "/persist/etc/ssh/ssh_host_ed25519_key";
      type = ed25519;
    }
  ];
}

After I initially get things working, I switch to sops-nix, the following guide works for this setup: sops-nix Guide

Resources

GnuPG gpg-agent

2026-01-15T00:00:00+00:00

GnuPG & `gpg-agent` on NixOS

✔️ Table of Contents

⚠️ SECURITY WARNING: This guide involves sensitive cryptographic material. Never share your private key or passphrase. Backup your keys and handle them with extreme care.

⚠️ gpg.fail (practical OpenPGP vulnerabilities) (Added on 2026-01-15)

The gpg.fail is a write-up of real-world weaknesses in GPG/OpenPGP implementations and edge cases in the OpenPGP ecosystem—not the underlying math of modern cryptography. The core idea is that signature verification needs two things: correct cryptography and confidence that the data you think was verified is actually the same data the verifier processed, which can break down when formats are complex and tooling is permissive or ambiguous.

Why this matters even with good key hygiene

Most of the hardening in this guide (offline primary key, subkeys, strict permissions, agent separation) is still worth doing because it protects your private key material and reduces the blast radius if a workstation is compromised.

But that kind of key hygiene doesn’t automatically protect you from OpenPGP “sharp edges” like ambiguous parsing rules, weird message constructions, or implementation bugs because those problems happen at the message/format/tooling layer, not the key-storage layer.

How to avoid the sharp edges (actionable)

Don’t treat “Good signature” as the end of the story. Treat verification as “verify + inspect what was verified,” especially if the output will be consumed by other tools or humans who may misinterpret it.
Prefer OpenPGP for narrow, well-understood tasks (verifying release artifacts, encrypting files) and be extra cautious when dealing with untrusted, attacker-controlled OpenPGP inputs that flow through multiple tools (mail clients, import pipelines, automation).
Keep GnuPG and related tooling updated; gpg.fail covers vulnerabilities that include classic implementation issues and not just “protocol design” pitfalls.

If you automate verification (important)

If you’re writing automation around signature verification, ensure your pipeline clearly distinguishes:

“signature cryptographically valid” from
“the extracted/displayed message is exactly what was verified”. Some gpg.fail items specifically call out cases where output does not make this distinction obvious enough to prevent misuse.

NixOS/Home-Manager hardening can break GPG (common failure mode)

Some “hardening” choices can cause GPG to fail in ways that look mysterious but are just UI/agent integration problems (for example, No pinentry / “gpg failed to sign the data” when the agent can’t prompt). If GPG signing/encryption suddenly stops working, first confirm pinentry is configured correctly (via your services.gpg-agent.pinentryPackage or gpg-agent.conf) and restart the agent with gpgconf --kill gpg-agent then gpgconf --launch gpg-agent.

🔑 Key Concepts

GnuPG is a complete and free implementation of the OpenPGP standard. It allows you to encrypt and sign your data and communications, has a versatile key management system, and access modules for many kinds of public key directories. GnuPG (GPG), is a command line tool for secure communication.

PGP (Pretty Good Privacy) and GPG (GNU Privacy Guard). While distinct, they are deeply interconnected and, for the rest of this section, I’ll use the terms interchangeably.

PGP was the original, groundbreaking software that brought robust public-key cryptography to the masses. It set the standard for secure email communication. However, PGP later became a commercial product.

To provide a free and open-source alternative that anyone could use and inspect, GPG was created. Crucially, GPG is a complete implementation of the OpenPGP standard. This open standard acts as a universal language for encryption and digital signatures.

GnuPG uses a more complex scheme in which a user has a primary keypair and then zero or more additional subordinate keypairs.

Signing public keys with the corresponding private key is called self-signing, and a public key that has self-signed user IDs bound to it is called a certificate.

Web of Trust: Rather than validate every single key individually, you can rely on other factors such as if it has been signed by a key that you fully trust or if it has been signed by three marginally trusted keys to validate keys.

gpg-agent is a daemon to manage secret (private) keys independently from any protocol. It is used as a backed for gpg and gpgsm as well as for a couple of other utilities. –man gpg-agent

There are numerous front-ends for gpg as well, i.e., GUI apps that simplify many of the commands and processes. Two that I touch on in this overview are seahorse and kleopatra.

Asymmetric Encryption (Public-Key cryptography)

E2ee requires that every sender and recipient does a one time preparation, which involves the generation of personal random numbers. Two such random numbers are necessary, one will be called your secret key and another one will be called your public key (together your personal key). These numbers are very big, they consist of hundreds or thousands of digits.

A message can be encrypted using the recipients public key and can only be decrypted with the matching private key. In other words, if you exchange public keys with someone you both can encrypt messages that only the other can decrypt with their own private key. You must never share the private key or the private keys passphrase with anyone else.

What’s safe to share?

Your public key (used to encrypt files and verify signatures)
Your key ID (identifies your key, useful for sharing public keys or configs)
Your keys fingerprint gpg --fingerprint

What must never be shared?

Your private (secret) key, usually in your ~/.gnupg/private-keys-v1.d/ directory. Usually called your private keyring. Your main goal should be the protection of your private key.
Your passphrase for your private key. Even if someone is able to somehow get your private key, they need to break the passphrase to access it unencrypted. Protect this passphrase!

Best Practices

Don’t rely on the short KeyID, at least use long OpenPGP Key IDs (for example 0xA1E6148633874A3D), they are 64 bits long and harder to spoof. Even better, use the fingerprint.This is accomplished in the configuration with keyid-format = "0xlong";, and with-fingerprint.

Always sign your public keys before you publish them to prevent man in the middle attacks and other modifications. When a subkey or userID is generated it is self-signed automatically, which is why you need to enter your password.

Don’t blindly trust keys from keyservers. You should verify the full key fingerprint with the owner over the phone if possible.

Verifying software signatures

Use a strong primary key, don’t use 1024-bit DSA, 1024-bit RSA, or SHA-1 for signing they are no longer recommended.

Choose an expiration date less than 2 years, you can add time if needed. Remember this date.

Rotate your subkeys.

Keep your primary key offline, this ensures that it can’t be stolen by an attacker allowing him to create new identities. We accomplish this by creating subkeys and only adding the subkeys keygrip and the subkeys default-key to our configuration keeping the primary key out of it.

Since we will be removing our primary key, even we won’t be able to create additional keys so it’s important to think ahead and make all the keys you’ll need. However, it is as easy as reimporting it to give yourself access again.

Many of these best practices come from the following guide:

RiseUp gpg-best-practices

Home Manager module with gpg-agent, gnupg, and pinentry-gnome3:

# gpg-agent.nix
{
  config,
  lib,
  pkgs,
  ...
}: {
  options = {
    custom.pgp = {
      enable = lib.mkEnableOption {
        description = "Enable PGP Gnupgp";
        default = false;
      };
    };
  };

  config = lib.mkIf config.custom.pgp.enable {
    services = {
      ## Enable gpg-agent with ssh support
      gpg-agent = {
        enable = true;
        enableSshSupport = true;
        enableZshIntegration = true;
        # pinentry is a collection of simple PIN or passphrase dialogs used for
        # password entry
        pinentryPackage = pkgs.pinentry-qt;
      };

      ## We will put our keygrip here
      gpg-agent.sshKeys = [];
    };
    home.packages = [pkgs.gnupg];
    programs = {
      gpg = {
        ## Enable GnuPG
        enable = true;

        # homedir = "/home/userName/.config/gnupg";
        settings = {
          # Default/trusted key ID (helpful with throw-keyids)
          # Example, you will put your own keyid here
          # Use `gpg --list-keys`
          # default-key = "0x37ACBCDA569C5C44788";
          # trusted-key = "0x37ACBCDA569C5C44788";
          # https://github.com/drduh/config/blob/master/gpg.conf
          # https://www.gnupg.org/documentation/manuals/gnupg/GPG-Configuration-Options.html
          # https://www.gnupg.org/documentation/manuals/gnupg/GPG-Esoteric-Options.html
          # Some Best Practices, stronger algos etc
          # Use AES256, 192, or 128 as cipher
          personal-cipher-preferences = "AES256 AES192 AES";
          # Use SHA512, 384, or 256 as digest
          personal-digest-preferences = "SHA512 SHA384 SHA256";
          # Use ZLIB, BZIP2, ZIP, or no compression
          personal-compress-preferences = "ZLIB BZIP2 ZIP Uncompressed";
          # Default preferences for new keys
          default-preference-list = "SHA512 SHA384 SHA256 AES256 AES192 AES ZLIB BZIP2 ZIP Uncompressed";
          # SHA512 as digest to sign keys
          cert-digest-algo = "SHA512";
          # SHA512 as digest for symmetric ops
          s2k-digest-algo = "SHA512";
          # AES256 as cipher for symmetric ops
          s2k-cipher-algo = "AES256";
          # UTF-8 support for compatibility
          charset = "utf-8";
          # Show Unix timestamps
          fixed-list-mode = "";
          # No comments in signature
          no-comments = "";
          # No version in signature
          no-emit-version = "";
          # Disable banner
          no-greeting = "";
          # Long hexidecimal key format
          keyid-format = "0xlong";
          # Display UID validity
          list-options = "show-uid-validity";
          verify-options = "show-uid-validity";
          # Display all keys and their fingerprints
          with-fingerprint = "";
          # Cross-certify subkeys are present and valid
          require-cross-certification = "";
          # Disable caching of passphrase for symmetrical ops
          no-symkey-cache = "";
          # Enable smartcard
          # use-agent = "";
        };
      };
    };
  };
}

🤔 Fun Fact: Elliot Alderson mentions encrypting Evil Corps files with 256 bit AES encryption ensuring that it’s impossible to break in eps1.9_zer0.daY.avi of Mr. Robot.

The default path is ~/.gnupg, if you prefer placing it in the ~/.config directory or elsewhere, uncomment the homedir line and change userName to your username.
I use sway so pinentry-qt works for me, there is also the following options for this attribute:
pinentry-tty
pinentry-gnome3
pinentry-gtk2

And more, research what you need and use the correct one.

search.nixos.org pinentry

Enable in your home.nix or equivalent:

# home.nix
# ... snip ...
imports = [
    ./gpg-agent.nix
];
custom.pgp.enable = true;
# ... snip ...

gpg --full-generate-key can be used to generate a basic keypair.

gpg --expert --full-generate-key can be used for keys that require more capabilities.

❗ NOTE: We will first generate our GPG primary key that is required to atleast have sign capabilities, we will then derive subkeys from said primary key and use them for signing and encrypting. It is recommended to generate a revoke certificate right after creating your primary key.

To generate your gpg primary key you can do the following:

gpg --full-generate-key

Choose (10) (sign only)
Give it a name and description
Give it an expiration date, 1y is common
Use a strong passphrase or password
Give it a comment, I typically add the date

If you see a warning about incorrect permissions, you can run the following:

chmod 700 ~/.gnupg
chmod 600 ~/.gnupg/*

Verify:

ls -ld ~/.gnupg
# Should show: drwx------

ls -l ~/.gnupg
# Files should show: -rw-------

Generate a Revocation Certificate

mykey must be a key specifier, either the keyID of the primary keypair or any part of the user ID that identifies the keypair:

Replace mykeyID with the keyID of your primary key and store the cert in a safe place:

gpg --output revoke.asc --gen-revoke mykeyID
Create a revocation certificate for this key? (y/N)
Please select the reason for the revocation:
  0 = No reason specified
  1 = Key has been compromised
  2 = Key is superseded
  3 = Key is no longer used
  Q = Cancel
(Probably you want to select 1 here)
Your decision?

The certificate will be output to a file revoke.asc. If the --output is ommitted, the result will be placed on stdout.

Since it’s a short certificate, you can print a hardcopy and store it somewhere safe. The cert shouldn’t be somewhere that others can access it since anyone could publish the revoke cert and render the corresponding public key useless.

To apply the revoke cert, import it:

NOTE: Only import the revoce.asc if you want to revoke (i.e., make it not work anymore)

gpg --import revoke.asc
# And optionally push the revoked key to public keyservers to notify others:
gpg --keyserver keyserver.ubuntu.com --send-keys YOUR_KEYID

After fixing, run gpg --list-keys --with-fingerprint, which lists your public keys:

# Take note of your public key
gpg --list-keys --with-fingerprint
/home/jr/.gnupg/pubring.kbx
---------------------------
pub   ed25519/0x095782A1B124AF15 2025-08-23 [SCA] [expires: 2026-08-23]
Key fingerprint = 5908 9C5B FEC8 0D75 FCB0  E206 0958 82C1 A124 CF15
uid                   [ultimate] Jr (08-23-25) <sayls8@proton.me>

Copy the KeyID, in this example it would be 0x095722B2A123CF15. We will use it for the command below.

The warning should be gone.

Now we will generate 2 subkeys, 1 for encryption and 1 for authentication.

gpg --expert --edit-key 0x095722B2A123CF15

When the screen opens, type addkey

Choose 11 (set your own capabilities) and add A (Authenticate) and type save to save and exit. Repeat this again and choose 12 ECC (encrypt only).

❗ gpg --edit-key has many more capabilities, after launching type help.

Add Keygrip of Authenticate Subkey to sshcontrol for gpg-agent

gpg --list-secret-keys --with-keygrip --keyid-format LONG

Copy the keygrip of the subkey with Authenticate capabilities

Add the keygrip number to your gpg-agent.sshKeys and rebuild, this adds an SSH key to gpg-agent. This is for the SSH key functionality of gpg-agent, while the key ID (default-key) is for GPG-specific operations like signing commits:

# gpg-agent.nix
gpg-agent.sshKeys = ["6BD11826F3845BC222127FE3D22C92C91BB3FB32"];

By itself, a keygrip cannot be used to reconstruct your private key. It’s derived from the public key material, not from the secret key itself so it’s safe to version control. Don’t put your keygrip in a public repo if you don’t want people to know you use that key for signing/authentication. It’s not a security risk, but it leaks a tiny bit of metadata.

The following article mentions the keygrip being computed from public elements of the key:

gnupg-users what-is-a-keygrip

Add the KeyId to your gpg-agent.nix, this declares your default-key to persist through rebuilds:

Copy the public key of the same subkey with Authenticate capabilities you will see something like [SA] next to it for Sign and Authenticate:

# gpg-agent.nix
gpg.settings = {
    # Replace with your own Subkeys KeyID `gpg --list-keys --keyid-format LONG`
    default-key = "Ox37ACA569C5C44787";
    trusted-key = "Ox37ACA569C5C44787";
};

This key should be signed automatically, ensure that it is:

gpg --sign-key Ox37ACA569C5C44787

Rebuild, and check that everything is correct with:

ssh-add -L
# you should see something like:
ssh-ed25519 AABCC3NzaC1lZDI1NTE5ABBAIHyujgyCjjBTqIuFM3EMUSo6RGklmOXQW3uWRhWdJ1Mm (none)

Never version-control your private key files or .gnupg contents.

Add the following to your shell config:

# zsh.nix
# ... snip ...
initContent = ''
    export GPG_TTY=$(tty)
    export SSH_AUTH_SOCK=$(gpgconf --list-dirs agent-ssh-socket)
    gpgconf --launch gpg-agent
'';
# ... snip ...

Rebuild and then restart gpg-agent if necessary:

gpgconf --kill gpg-agent
gpgconf --launch gpg-agent

Test, these should match:

echo "$SSH_AUTH_SOCK"
# output
/run/user/1000/gnupg/d.wft5hcsny4qqq3g31c76534j/S.gpg-agent.ssh

gpgconf --list-dirs agent-ssh-socket
# output
/run/user/1000/gnupg/d.wft5hcsny4qqq3g31c76834j/S.gpg-agent.ssh

ssh-add -L
# Copy the entire following line:
ssh-ed25519 AABBC3NzaC1lZDI1NTE5AAAAIGXwhVokJ6cKgodYT+0+0ZrU0sBqMPPRDPJqFxqRtM+I (none)

Mine shows (none) because I left the comment field blank when creating the key and doesn’t affect functionality.

Then, in your server’s NixOS configuration (e.g., configuration.nix): Change yourUser to your username. This is how you grant access to a remote machine, and the public key from the GPG subkey is what’s added here, the output of ssh-add -L:

users.users.yourUser = {
openssh = {
  authorizedKeys.keys = [
    # Replace with the output of `ssh-add -L`
    "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIGXwhVokJ6cKgodYT+0+0ZrU0sBqMPPRDPJqFxqRtM+I (none)"
  ];
};
};

❗ NOTE: Only the public key goes here, it’s safe to commit to version control. If you prefer not to hardcode it in the config, you can reference it from a .pub file in your repo and read it with builtins.readFile ./mykey.pub

Rebuild your system and test an SSH connection into the server:

ssh -p <your-port> user@hostname

<your-port> is often 22 so it would be something like:

ssh -p 22 bill@xps

Once you successfully sign in to SSH, it will ask you if you’re sure you trust the remote server’s SSH host key. Once you type yes, it will automatically be used for tasks such as file decryption.

Remove and Store your Primary Key offline

❗ NOTE: After you remove your primary key, you will no longer be able to derive subkeys from it or sign keys unless you re-import it.

# extract the primary key
gpg -a --export-secret-key sayls8@proton.me > secret_key
# extract the subkeys, which we will reimport later
gpg -a --export-secret-subkeys sayls8@proton.me > secret_subkeys.gpg
# delete the secret keys from the keyring, so only subkeys are left
gpg --delete-secret-keys sayls8@proton.me
Delete this key from the keyring? (y/N) y
This is a secret key! - really delete? (y/N) y
# reimport the subkeys
gpg --import secret_subkeys.gpg
# verify everything is in order
gpg --list-secret-keys
# remove the subkeys from disk
rm secret_subkeys.gpg

I recommend also keeping a .gpg version to make it easy to re-import your primary key: gpg --export-secret-keys --armor --output private-key-bak.gpg

Then store secret_key on an encrypted USB drive or somewhere offline. If you want to protect it for now, you can just use the encryption subkey that we created to encrypt secret_key with a passphrase:

gpg --list-keys --keyid-format LONG

Copy the KeyID of the subkey with encrypt capabilities for the following command:

# Encrypting your secret key for yourself
gpg --encrypt --recipient Ox37ACA569C5C44787 secret_key

You can check that the secret key material is missing with gpg --list-secret-keys, you should see sec# instead of sec.

gpg --list-secret-keys
# Output:
sec#  ed25519/0x
# ...snip...

The above set of commands are from the RiseUp Keep your primary key offline

Add your GPG Key to GitHub

Plug your own public key from gpg --list-keys in the following command:

gpg --armor --export <Public-Key>

Copy the entire block from -----BEGIN PGP PUBLIC KEY BLOCK----- to -----END PGP PUBLIC KEY BLOCK-----

❗ You can also paste the above block into a public keyserver such as keys.openpgp.org. This allows others to find and use your key to encrypt messages or verify your signatures. Many tools and users rely on public key servers to fetch keys automatically. You can also publish your revocation certificates, which help others know if your key is compromised or revoked. This can be a privacy concern as key servers publish (and keep) associated user IDs and metadata linked to your key, such as your email.

It’s the same process as adding an SSH key, Go to Settings, SSH and GPG keys, New GPG key and your all set.

Sign your Commits for Git

# git.nix
{...}: {
    programs.git = {
        enable = true;
      extraConfig = {
          commit.gpgsign = true;
          user.signingkey = "0x0666C1A265F156"
      };
    };
}

After this, you will be prompted for your Private Keys password on every commit.

If you look at your commits on GitHub, after adding the GPG key and the above settings to your git setup it will show your commits are Verified.

Backing up Your Keys

gpg --export-secret-keys --armor --output my-private-key-backup.gpg

Your private keys will be encrypted with a passphrase into a .gpg file. Store this backup in a secure location line an encrypted USB drive. This can prevent you from losing access to your keys in the case of disk failure or accidents.

You can export your public keys and publish them publicly if you choose:

gpg --export --armor --output my-public-keys.gpg

Now if your keys ever get lost or corrupted, you can import these backups.

Encrypt a File with PGP

The easy way to do this is with an app like Kleopatra, available as pkgs.kdePackages.kleopatra. Kleopatra will automatically recognize your gpg keys and enable you to easily encrypt messages by clicking the Notepad, typing your message and clicking Sign/Encrypt Notepad. You can also choose to encrypt the message with a password, where anyone that has the password can read the message.

Using the above and below methods enable you to encrypt any message for basically any service and just copy past the encrypted text into the service for added privacy.

Encrypting a whole directory is a bit more involved and requires using compression.

List your keys and get the key ID

gpg --list-keys --keyid-format LONG

Example output, don’t use RSA keys:

pub   rsa4096/ABCDEF1234567890 2024-01-01 [SC]
uid           [ultimate] Your Name <you@example.com>
sub   rsa4096/1234567890ABCDEF 2024-01-01 [E]

Notice the sub and the [E] for the subkey with encrypt capabilities.
The part after the slash on the pub line is your key ID (ABCDEF1234567890 in the example)
You can also use your email or name to refer to the key in most commands.

Encrypt a file

In order to encrypt a document you must have the public keys of the intended recipients.

echo "This file will be encrypted" > file.txt

Encrypting for yourself (using a key ID as recipient):

gpg --encrypt --recipient ABCDEF1234567890 file.txt

ls
│  7 │ file.txt            │ file │     28 B │ now           │
│  8 │ file.txt.gpg        │ file │    191 B │ now           │

Encrypting for someone else with their email (public key identifier):

gpg --output file.gpg --encrypt --recipient jake@proton.me file.txt

ls
file.txt
file.gpg

gpg --encrypt doesn’t modify the original file. It creates a new encrypted file by default with gpg amended to the filename.

gpg --decrypt file.txt.gpg
gpg: encrypted with cv25519 key, ID 0x4AC131B80CEC833E, created 2025-07-31
      "GPG Key <sayls8@proton.me>"
This file will be encrypted

Or, to save the decrypted text to a file:

gpg --output decrypted_file.txt --decrypt file.txt.gpg
cat decrypted_file.txt
# Output
File: decrypted.txt
This file will be encrypted

You will be asked for the passphrase you used when creating the key in order to decrypt the file.

Sign and Verify Signatures

When you sign a document it is certified and timestamped. If after the doc is signed, if the doc is further modified in any way the verification of the signature will fail.

A signature is created using the private key of the signer, and verified with the corresponding public key. For example, to verify Jakes signature you would use Jake’s public key to see that the work indeed came from him and hasn’t been modified since.

To sign the above file.txt:

gpg output doc.sig --sign file.txt
# To clearsign use:
gpg --clearsign file.txt
# For a detached signature use:
gpg --output doc.sig --detach-sig file.txt

You will be prompted for your passphrase.

You can either check the signature or check the signature and recover the original document.

# To only check:
gpg --output doc --verify doc.sig
# To verify and extract the document
gpg --output doc --decrypt doc.sig

Email Encryption

Email is inherently insecure, and email-based attacks remain one of the top vectors for data breaches. Encrypting your email protects your privacy by ensuring that only the intended recipient can read it. Encrypting your emails with PGP provides valuable security benefits but also has inherent limitations that prevent it from being considered truly “secure communication” by modern standards.

Email Self-Defense

What its Good for:

Confidentiality, it prevents unauthorized third parties (like email providers or network eavesdroppers) from reading your email content.
Integrity and authenticity: Digital signatures verify that the email genuinely came from the claimed sender and hasn’t been altered in transit.
Long-term confidentiality: Encrypted emails stored on servers or devices remain protected even if the storage is later compromised. With companies like Gmail giving you a “free” account, that usually means that you are the product and you should tread lightly.

To securely communicate with someone never use email, use a dedicated service such as Threema, Signal or Brair. It’s hard to recommend any messaging service at the moment, always do your own research and stay informed on the companies policies. Signal has taken some heat for the way it has implemented it’s MobileCoin. The biggest issue I’ve faced is getting other people to care or use the same e2ee app.

With Thunderbird you can go to settings, Privacy and Security, and scroll to the bottom where it says “End to End Encryption”, Click the Settings tab there, finally click End-To-End Encryption on the left.

From there, you can click + Add Key next to your email address and either generate a new key through Thunderbird. If you use this, choose the Curve protocol or whatever isn’t RSA.

Or import your own key which is definitely more secure since you’re not trusting someone else with your private key:

gpg --export --armor sayls8@gmail.com > publickey.asc

Then select + Add Key and choose import your own, this didn’t work for me. What did work was to start composing an email and click on the OpenPGP button, Go to Key Manager, File, Import Public Key from a File and choose your publickey.asc. This way, only you have access to your private key.

How e2ee with OpenPGP works in general

Import your recipient’s public key

When you start composing an email, you’ll see that you need to resolve key issues if you don’t already have the recipients public key. Click Resolve, and either Discover Public Keys Online… or Import Public Keys From File…

Thunderbird has the option to use the OpenPGP Key Manager to view or manage public keys of your correspondents.

If you’re sending encrypted emails to someone you’ll need their public key, there are a few methods of doing this just ensure you verify the Fingerprint with the person your talking to.

Exporting your public key means creating a copy of the public part of your cryptographic key pair that you can share with others.

For example, say that Jake wants to send you his public key. First he has to export his key:

gpg --output jake.gpg --export jake@proton.me

The key is exported in binary format, to export in ASCII-armored format use:

gpg --armor --export jake@proton.me

Now, once he sends this to you, you’ll need to import and validate it:

gpg --import jake.gpg

Once the key is imported it should be validated. If you need to validate a key manually, it is done by verifying the key’s fingerprint and then signing the key to certify it as a valid key.

Check that it exists in your keychain:

gpg --list-keys

You should see Jakes key in the above list.

To certify the key you need to edit it:

gpg --edit-key jake@proton.me
# List the fingerprint
gpg> fpr
# once the fingerprint is verified with the owner, sign it
gpg> sign
# once signed, you can check the key to list signatures on it
gpg> check

❗ NOTE: You can use PGP to encrypt any message and paste it into any software and send it. As long as only you and your recipient are the only people to have the private keys, you will be the only people able to decrypt the messages. Implementing this correctly is a good way to stop government mass surveillance.

Make your Public Key Highly Available

You should always make sure that you sign your public key before you publish it. When you distribute your public key, you’re distributing the public components of your master and subkeys as well as the user IDs. If unsigned, this is a security risk because it’s possible for an attacker to tamper with it. The public key can be modified by adding or substituting keys, or changing user IDs.

Signing the keys provides a web of trust, only the corresponding public key can be used to verify the signature and ensure it hasn’t been modified. Since we are already only using subkeys for public keys, they are automatically self-signed.

gpg --output ~/mygpg.key --armor --export your_email@address.com

You can then send this file to the other party.

You can also use the GPG interface to upload your key to a key server:

gpg --list-keys your_email@address.com

Copy the key ID for the following command, remember its on the pub line after the /.

gpg --send-keys --keyserver pgp.mit.edu key_id

The key will be uploaded to the server and likely be distributed to other key servers around the world. This is why expiration dates are important, if your key is lost or stolen, the damage window is limited to the expiration period. Also remember, you can add more time even after the key has expired.

Example: Verifying Arch Linux Download

✔️ Click to Expand Example of verifying and signing the archlinux public key

First, download both the arch .iso and .sig files.

I tried a few different methods from https://archlinux.org/download/#checksums and the easiest by far was using Sequoia available in Nixpkgs as pkgs.sequoia-sq:

Download the archlinux public key:

sq network wkd search pierre@archlinux.org --output release-key.pgp

Found 2 certificates related to the query:

 - 3E80CA1A8B89F69CBA57D98A76A5EF9054449A5C
   - Pierre Schmitz <pierre@archlinux.org> (UNAUTHENTICATED)
   - created 2022-10-31 09:11:51 UTC
   - found via: WKD

 - 4AA4767BBC9C4B1D18AE28B77F2D434B9741E8AC
   - Pierre Schmitz <pierre@archlinux.de> (UNAUTHENTICATED)
   - created 2011-04-10 09:35:33 UTC
   - found via: WKD

Hint: To extract a particular certificate from release-key.pgp, use any of:

  $ sq cert export --keyring=release-key.pgp --cert=3E80CA1A8B89F69CBA57D98A76A5EF9054449A5C

  $ sq cert export --keyring=release-key.pgp --cert=4AA4767BBC9C4B1D18AE28B77F2D434B9741E8AC

Export the chosen key to a .pgp file:

sq cert export --keyring=release-key.pgp --cert=3E80CA1A8B89F69CBA57D98A76A5EF9054449A5C > pierre-archlinux.pgp

Import into your keychain:

 gpg --import pierre-archlinux.pgp
gpg: key 0x76A5EF9054449A5C: 9 signatures not checked due to missing keys
gpg: key 0x76A5EF9054449A5C: public key "Pierre Schmitz <pierre@archlinux.org>" imported
gpg: Total number processed: 1
gpg:               imported: 1
gpg: marginals needed: 3  completes needed: 1  trust model: pgp
gpg: depth: 0  valid:   3  signed:   0  trust: 0-, 0q, 0n, 0m, 0f, 3u
gpg: next trustdb check due at 2026-08-23

Now, you should see <pierre@archlinux.org> and his keys when you run gpg --list-keys

Finally, verify the signature:

sq verify --signer-file release-key.pgp --signature-file archlinux-2025.08.01-x86_64.iso.sig archlinux-2025.08.01-x86_64.iso
Authenticated signature made by 3E80CA1A8B89F69CBA57D98A76A5EF9054449A5C (Pierre Schmitz <pierre@archlinux.org>)

1 authenticated signature.

This shows that the signature was made by the key with the ID 3E80CA1A8B89F69CBA57D98A76A5EF9054449A5C (Pierre Schmitz).

GPG authenticated that the signature is valid and that the key used to sign is trusted in our keyring.

1 authenticated signature confirms the files integrity and authenticity.

We have successfully verified that the file was signed by Pierr’s official Arch Linux key and has not been tampered with.

Since the key has been verified we can now sign it. We will have to import our primary key to do so since we are keeping it offline for safety.

gpg --import backup.gpg

List your keys to get the arch keyID:

gpg --list-keys
# ... snip ...
pub   ed25519/0x76A5EF9054449A5C 2022-10-31 [SC] [expires: 2037-10-27]
      Key fingerprint = 3E80 CA1A 8B89 F69C BA57  D98A 76A5 EF90 5444 9A5C
uid                   [  full  ] Pierre Schmitz <pierre@archlinux.org>
uid                   [  full  ] Pierre Schmitz <pierre@archlinux.de>
sub   ed25519/0xD6D13C45BFCFBAFD 2022-10-31 [A] [expires: 2037-10-27]
sub   cv25519/0x7F56ADE50CA3D899 2022-10-31 [E] [expires: 2037-10-27]

Sign the key:

gpg --sign-key 0x76A5EF9054449A5C

Now you can Export and publish the new public key and send it to a keyserver:

gpg --export --armor 0x76A5EF9054449A5C > archlinux-signed.asc
gpg --send-keys 0x76A5EF9054449A5C

The more people that verify, sign, and re-export and publish their keys the better for the web of trust that gpg uses making the network more secure for everyone.

Edit your trust level of the key

gpg --edit-key pierre@archlinux.org
gpg> trust
Please decide how far you trust this user to correctly verify other users' keys
(by looking at passports, checking fingerprints from different sources, etc.)

  1 = I don't know or won't say
  2 = I do NOT trust
  3 = I trust marginally
  4 = I trust fully
  5 = I trust ultimately
  m = back to the main menu

Your decision? 3
# Output:
pub  ed25519/0x76A5EF9054449A5C
     created: 2022-10-31  expires: 2037-10-27  usage: SC
     trust: marginal      validity: full

You can see that the trust is marginal and validity is full.

NixOS Containers

2026-01-11T00:00:00+00:00

NixOS Containers

✔️ Click to Expand Table of Contents

NixOS containers are lightweight systemd-nspawn containers managed declaratively through your NixOS configuration. They allow you to run separate, minimal NixOS instances on the same machine, each with its own services, packages, and (optionally) network stack.

freedesktop systemd-nspawn

❗ NixOS’ containers do not provide full security out of the box (just like docker). They do give you a separate chroot, but a privileged user (root) in a container can escape the container and become root on the host system. –beardhatcode Declarative-Nixos-Containers

Common Use Cases

Isolating services: Run a web server, database, or any service in its own container, so it can’t interfere with the main system or other services
Testing and development: Try out new configurations, packages, or services in a sandboxed environment.
Reproducible deployments: Because containers are defined declaratively, you can reproduce the exact same environment anywhere.
Running multiple versions of a service: For example, testing different versions of Git or HTTP servers side by side.

Hosting mdBook

Let’s say you want to host your mdBook. You can define a NixOS container that runs only the necessary service, isolated from your main system:

{
  config,
  lib,
  ...
}: {
  containers.mdbook-host = {
    autoStart = true;
    ephemeral = true;
    privateNetwork = false;  # Use the hosts network

    bindMounts."/var/www/mdbook" = {
      hostPath = "/home/jr/nix-book/book";
      isReadOnly = true;
    };

    config = {containerPkgs, ...}: {
      networking.useDHCP = lib.mkDefault true;

      services.httpd = {
        enable = true;
        adminAddr = "yourEmail.com";
        virtualHosts."localhost" = {
          documentRoot = "/var/www/mdbook";
          serverAliases = [];
        };
      };

      networking.firewall.allowedTCPPorts = [80];
      environment.systemPackages = with containerPkgs; [];
      system.stateVersion = "25.05";
    };
  };
}

ephemeral: if true, the container resets on each restart.
autoStart: Ensures the container starts automatically at boot.
config: Defines the containers NixOS configuration, just like a regular NixOS system.

Mounts

    bindMounts."/var/www/mdbook" = {
      hostPath = "/home/jr/nix-book/book";
      isReadOnly = true;
    };

The bindMount settings above specify that /var/www/mdbook in the container should be linked to /home/jr/nix-book/book on the host.

hostPath must exist, and /var/www/mdbook must not exist for this to work.

The above container is fairly simple because its ReadOnly, things get more complicated when you need HTTPD to have write privileges.

When you create and run a NixOS container like mdbook-host. NixOS stores the container’s root filesystem and related container state data under:

ls /var/lib/nixos-containers/
╭────────────╮
│ empty list │  # It's empty because we set ephemeral to true
╰────────────╯

This directory holds the container’s own filesystem image, including system files, installed packages, configuration, and any data internal to the container.

Check Container Status

nixos-container list
mdbook-host

sudo systemctl status container@mdbook-host
 Main PID: 32938 (systemd-nspawn)
     Status: "Container running: Ready."

Test HTTP server inside the container

We configured Apache (httpd) to serve /var/www/mdbook at localhost

Let’s check if Apache is running:

sudo nixos-container run mdbook-host -- systemctl status httpd
● httpd.service - Apache HTTPD
     Loaded: loaded (/etc/systemd/system/httpd.service; enabled; preset: ignored)
     Active: active (running) since Fri 2025-08-15 10:14:39 EDT; 2min 18s ago

Check the Bind Mount:

sudo nixos-container run mdbook-host -- ls -l /var/www/mdbook

You should see an index.html and any other files from ~/nix-book/book

Test the Web Server:

curl http://localhost

You should see your book in HTTP format as raw HTML.

Test on the web, in your browser visit:

http://localhost/

You should see your book fully served

Troubleshooting

Make sure your book has the correct permissions to allow hostPath to read it:

sudo chmod -R o+rX ~/nix-book/book

If needed restart the container:

sudo nixos-container stop mdbook-host
sudo nixos-container start mdbook-host

Ensure that /var/www/mdbook is being populated:

sudo nixos-container run mdbook-host -- ls -l /var/www/mdbook

You should see an index.html and more

sudo nixos-container run mdbook-host -- systemctl status httpd

You should see enabled & active (running)

Check the containers status:

sudo nixos-container status mdbook-host
up

Why Bother Serving your book to localhost?

Real-time updates without rebuilding the container

Files added, changed, or removed from ~/nix-book/book on the host are immediately reflected inside the container. This allows for:
- Rapid iteration and testing of your books content without rebuilding
- Easier debugging and fixing content or config issues on the fly.

Keeps container images small and immutable

Instead of baking book files into the container image (which requires rebuilding every change), the container image remains clean and generic.

Separation of concerns

The container focuses on running the service, while the content is managed independently on the host. This separation improves maintainability and more.

Data persistence

Since the files live on the host, they persist independently of the containers lifecycle: restarting, recreating, or destroying the container won’t lose your content.

Security Control

You can carefully set permissions on the host directory, control read/write access, and isolate the container runtime from sensitive data.

Removing the State

To remove /var/lib/nixos-containers/mdbook-host, you need to remove the container configuration, rebuild, and then run the following commands to remove the immutable sticky bits that prevent deletion.

# Forcibly remove all attributes
sudo chattr -R -i mdbook-host/
sudo rm -rf mdbook-host/

OCI deployment pipeline building a Rust App

If you want to use mdbook-nix-repl check out the README, the following shows how I tested locally before eventually adding a flake.nix to the repo streamlining this for users of the project.

mdbook-nix-repl README

This documents how to work with a local Rust crate repository without a flake.nix for testing. The README above explains how to generate a token and use the project, this is just for educational purposes if you wanted to implement something similar:

nix-repl-server.nix, place this in the same dir as your configuration.nix:

{
  config,
  lib,
  pkgs,
  inputs,
  ...
}:

let
  cfg = config.custom.nix-repl-server;

  serverSource = inputs.mdbook-nix-repl + "/server";

  # 1. Build the binary using your package definition
  # serverPkg = pkgs.callPackage ./server-pkg.nix { };
  serverPkg = pkgs.callPackage ./server-pkg.nix {
    src = serverSource;
  };

  # 2. Build a minimal container image containing just the server + nix + deps
  nixReplImage = pkgs.dockerTools.buildLayeredImage {
    name = "nix-repl-server";
    tag = "latest";

    # dependencies needed at runtime inside the container
    contents = [
      serverPkg
      pkgs.nix
      pkgs.bashInteractive
      pkgs.cacert
      pkgs.tini
      pkgs.coreutils
    ];

    config = {
      Entrypoint = [
        "${pkgs.tini}/bin/tini"
        "--"
      ];
      Cmd = [ "${serverPkg}/bin/nix-repl-server" ];
      ExposedPorts = {
        "8080/tcp" = { };
      };
      # Important: Container must see 0.0.0.0 to receive traffic from host port mapping
      Env = [
        "NIX_REPL_BIND=0.0.0.0"
        "NIX_CONFIG=experimental-features = nix-command flakes"
        "SSL_CERT_FILE=${pkgs.cacert}/etc/ssl/certs/ca-bundle.crt"
      ];
    };
  };
in
{
  options.custom.nix-repl-server = {
    enable = lib.mkEnableOption "nix-repl-server container";
    port = lib.mkOption {
      type = lib.types.port;
      default = 8080;
      description = "Host port to map to the container";
    };
    tokenFile = lib.mkOption {
      type = lib.types.path;
      default = "/etc/nix-repl-server.env";
      description = "Path to file containing NIX_REPL_TOKEN=...";
    };
  };

  config = lib.mkIf cfg.enable {
    # Enable Podman backend
    virtualisation.podman.enable = true;
    virtualisation.oci-containers.backend = "podman";

    # The OCI container definition
    virtualisation.oci-containers.containers.nix-repl-server = {
      image = "nix-repl-server:latest";

      # This effectively "loads" the image into Podman on boot
      imageFile = nixReplImage;

      ports = [ "127.0.0.1:${toString cfg.port}:8080" ];

      # Inject the token safely at runtime (not in Nix store)
      environmentFiles = [ cfg.tokenFile ];

      extraOptions = [
        "--cap-drop=ALL"
        "--security-opt=no-new-privileges"
        "--pull=never" # Use the local loaded image
      ];
    };
  };
}

server-pkg.nix, place this in the same dir as nix-repl-server.nix:

{
  lib,
  rustPlatform,
  nix,
  pkg-config,
  openssl,
  makeWrapper,
  inputs,
  src,
}:

rustPlatform.buildRustPackage {
  pname = "nix-repl-server";
  version = "0.1.0";

  # Point this to your actual source root (where Cargo.toml is)
  # src = ./.;
  inherit src;

  # You must commit Cargo.lock for this to work
  # cargoLock.lockFile = ../../../mdbook-nix-repl/server/Cargo.lock;
  cargoLock.lockFile = "${src}/Cargo.lock";

  postPatch = ''
    cp Cargo.toml.inc Cargo.toml
  '';

  # Runtime dependencies (nix for evaluation)
  nativeBuildInputs = [
    pkg-config
    makeWrapper
  ];
  buildInputs = [ openssl ];

  doCheck = false;

  # Ensure 'nix' is available in the path if your binary calls Command::new("nix")
  postInstall = ''
    wrapProgram $out/bin/nix-repl-server --prefix PATH : ${lib.makeBinPath [ nix ]}
  '';

  meta = with lib; {
    description = "Secure Nix REPL server for mdbook-nix-repl";
    platforms = platforms.linux;
  };
}

flake.nix, this URL leads to a Rust crate repo:

inputs = {
  mdbook-nix-repl = {
    url = "path:/home/jr/mdbook-nix-repl";
    flake = false;
  };
}

configuration.nix:

{ pkgs, inputs, ... }:
{
  imports = [
    # Include the results of the hardware scan.
    ./hardware-configuration.nix
    ./users.nix
    ./nix-repl-server.nix
  ];

  custom.nix-repl-server = {
    enable = true;
    port = 8080; # Optional, defaults to 8080
    tokenFile = "/etc/nix-repl-server.env";
  };
# --snip--

Resources

RedHat A Practical Intro to Container Technology

Packaging a Rust crate for Nixpkgs

2025-12-31T00:00:00+00:00

✔️ Table of Contents

Packaging a Rust crate for Nixpkgs

NOTE: This example assumes you’re packaging a crate that’s already on crates.io, or you’re packaging an existing Rust project for nixpkgs.

Nixpkgs is a big repository, so it helps to start with a focused workflow: create a branch, add a package under pkgs/by-name/, build it, then open a PR.

Clone nixpkgs

Fork and clone NixOS/nixpkgs:

git clone git@github.com:your-user/nixpkgs.git
cd nixpkgs
git remote add upstream git@github.com:NixOS/nixpkgs.git

(SSH avoids HTTPS helper issues)

If your clone is shallow, convert it to full history (doesn’t lose work):

git fetch --unshallow --tags

Create a branch and add package:

Create a branch before changes preferably:

git switch -c mdbook-rss-feed

Add the package under pkgs/by-name

New top-level packages should generally go under pkgs/by-name/<2 letters>/<name>/package.nix (e.g. pkgs/by-name/md/mdbook-rss-feed/package.nix). Packages in pkgs/by-name are picked up automatically and usually don’t require edits to all-packages.nix.

Write package.nix (Rust crate example)

Start with rustPlatform.buildRustPackage and fetchCrate:

{
  lib,
  rustPlatform,
  fetchCrate,
  versionCheckHook,
}:
rustPlatform.buildRustPackage rec {
  pname = "mdbook-rss-feed";
  version = "1.3.0";

  src = fetchCrate {
    inherit pname version;
    hash = "output of `nix hash convert` shown below";
  };

  cargoHash = lib.fakeHash;

  nativeInstallCheckInuts = [
    versionCheckHook
  ];
  doInstallCheck = true;

  meta = {
    description = "mdBook preprocessor that generates RSS, Atom, and JSON feeds";
    mainProgram = "mdbook-rss-feed";
    homePage = "https://crates.io/crates/mdbook-rss-feed";
    license = lib.licenses.asl20;
    maintainers = [ lib.maintainers.sayls88 ];
  };
}

Prefetch the crate hash:

Use fetchCrate / crate2nix style workflow, or just prefetch the crates.io tarball:

nix-prefetch-url \
  --unpack \
  https://crates.io/api/v1/crates/mdbook-rss-feed/1.3.0/download

That prints a base32 hash: 0932843lknasdlfkm2lkdnflaknldvdsvser

Convert it to sri format:

nix hash convert --hash-algo sha256 --from nix32 --to sri 0932843lknasdlfkm2lkdnflaknldvdsvser

The above commands output looks like: sha256-...=

Put the resulting sha256-... into src.hash:

  src = fetchCrate {
    inherit pname version;
    hash = "sha256-...";
  };

Get cargoHash via a failing build

In the nixpkgs root (i.e., the nixpkgs directory), run:

nix-build -A mdbook-rss-feed
# OR nix3 format
nix build .#mdbook-rss-feed

Nix will fail with a message like:

hash mismatch
specified: sha256-....
got: sha256-1...

Copy the got value into cargoHash, rebuild, and it should succeed.

Sanity check: from nixpkgs root :

./result/bin/mdbook-rss-feed --version

Adding yourself as maintainer

Edit nixpkgs/maintainers/maintainer-list.nix add your user in alphabetical order:

your-handle = {
  email = "you@example.com";
  name = "Your Name";
  github = "your-gh-handle";
  githubId = 12345678;
};

If you specify github, nixpkgs expects githubId too. You can get it from: https://api.github.com/users/<user>.

The nixpkgs maintainers prefer if you add the maintainer-list.nix as a separate commit.

git commit -m "maintainers: add <user>"

Treefmt

Run treefmt the nixpkgs way, from the repo root. Run this right before you push, my editors formatter does something different with single entry lists than what Nixpkgs wants:

nix develop --command treefmt
nix fmt

Rebase and push safely

From the mdbook-rss-feed branch:

git fetch upstream --tags
git rebase upstream/master

Commit and push your PR branch:

Then commit and push

git commit -m "mdbook-rss-feed: init at 1.3.0"
# First push
git push origin mdbook-rss-feed
# Use `--force-with-lease` only if you rebased/amended and need to rewrite the PR branch.
# git push --force-with-lease origin mdbook-rss-feed

--force-with-lease is the recommended safe force-push for PR branches.

If --force-with-lease says “stale info”, fetch the remote branch ref first, then retry.

Then commit and push

git commit -m "mdbook-rss-feed: init at 1.3.0"
git push -u origin mdbook-rss-feed

Then:

Go to GitHub -> your fork
Click “Compare & pull request” on the mdbook-rss-feed branch
Fill out the PR template (why useful, tested on x86_64-linux, etc.)
Submit!

The package will go through CI checks, and once green + approved by a maintainer, it’ll land in nixpkgs.

Recovering from Mistakes

You’re bound to make mistakes, if you learn some Git basics it will help you quite a bit.

You should avoid adding new commits for small fixes like typos, formatting, or minor adjustments requested in review. For substantial changes that add functionality, a new commit may be more appropriate.

Say that we pushed our PR and one of the maintainers gave us a suggested change, (they want us to follow conventions and remove a trailing period from our packages description for this example).

Make the edit locally (remove the trailing period in the file)
Stage the change: git add pkgs/by-name/xx/your-package/package.nix (avoid git add -A as it stages everything, which can accidentally include unrelated files)
Amend the commit: git commit --amend --no-edit(this preserves your original commit message, if you want to change the commit message use git commit --amend)
Force push: git push --force-with-lease (This is safer than just using --force because it will fail if someone else has pushed commits to your branch that you don’t have locally)

Alternative for Multiple Commits

Interactive rebase is useful when your PR has several “WIP” commits (or you added a small review fix as a separate commit) and you want to present a cleaner history before merge.

You can use interactive rebase to squash all your would be small fix commits into a single commit they belong to.

Avoid squashing if the commits represent distinct, reviewable changes that stand on their own.

Basic Workflow (squash/fixup)

Decide how many commits back you want to edit (example: last 3 commits):

git rebase -i HEAD~3

Your editor opens with a “todo” list (oldest at top). Change later commits from pick to fixup or squash:

fixup = combine into the previous commit, discard this commit message.
squash = combine, but keep/edit commit messages.

Example todo:

pick 1111111 mdbook-rss-feed: init at 0.1.0
pick 2222222 mdbook-rss-feed: fix trailing period
pick 3333333 mdbook-rss-feed: formatting

Change to:

pick 1111111 mdbook-rss-feed: init at 0.1.0
fixup 2222222 mdbook-rss-feed: fix trailing period
fixup 3333333 mdbook-rss-feed: formatting

Save/close: if you squashed, Git will prompt you to edit the final combined message.

Push updated history

You have to force-push because rebase rewrites commit SHAs:

git push --force-with-lease
# If something goes wrong
# git rebase --abort
# If you hit conflicts, fix the files, then:
# git add <files>
# git rebase --continue

If you have an unrelated change accidentally included (for example: you staged an extra file), it’s usually better to fix it via rebase/splitting before reviewers spend time re-reviewing noise.

As of 01-13-26 I have been waiting for 2 weeks for the darwin checks to complete, I guess this bottleneck has gotten worse. I guess most PRs take about 6 weeks to resolve FYI.

Hardening Networking

2025-12-25T00:00:00+00:00

Hardening Networking

✔️ Table of Contents

Since networks and systems vary, some adjustments may cause unexpected issues, especially around critical components like DNS or firewalls. Always review and test changes in a controlled environment before applying them broadly.

Understand the trade-offs and tailor the settings to your threat model and workflow. Take what’s useful, adapt as needed, and seek expert guidance for more advanced scenarios.

Introduction

Every setup is unique, feel free to adapt or skip sections based on your needs. Start with the basics and build up as you gain confidence. The goal is practical, tested hardening tailored to you.

Safe Browsing / Privacy Enhancing Habits

I recently broke this chapter down and added another chapter: Browser/Browsing Security

Adopt Encrypted DNS and HTTPS Everywhere

Configure your system and browsers to use DNS over HTTPS (DoH), DNS over TLS (DoT), or DNSCrypt to prevent DNS leakage. Use HTTPS-Only mode in browsers to encrypt all web traffic. Prefer browsers with strong privacy defaults or add recommended extensions.
Privacy Guides dnscrypt-proxy recommendation
Disable browser “remember password” and autofill features, clear cookies and site data upon exit, and carefully vet suspicious URLs with tools like VirusTotal.

Limit Account Linking and Use Unique Credentials

Create separate accounts with unique passwords instead of signing in with Google, Facebook, or similar services to limit broad data exposure from compromises.

Use Metadata Cleaning Tools

Many files like images, PDFs, and office documents contain hidden metadata information such as location data, device details, and more that can reveal your identity or other sensitive information when you share files publicly.
To protect your privacy, always sanitize files by removing this metadata before sharing. Tools like mat2 are designed to strip metadata from a wide range of media files efficiently. (pkgs.mat2). You just type mat2 swappy-2025.png for example and there will then be a new mat2 swappy-2025.cleaned.png that can safely be shared.

Use Anonymous File-Sharing Tools

For sensitive transfers, consiter tools like OnionShare that provide anonymity and security.(pkgs.onionshare)

Avoid Scanning Random QR Codes Without Verification

Use QR code scanner apps that check for malicious content before loading links.

Understand Your Threat Model

Apply these basics universally, but tailor advanced hardening according to your unique environment, connectivity needs, and risk profile.

Delete cookies and site data when the browser is closed. (security not usability).

Use Strong, Unique Passwords and a Password Manager

Avoid reused passwords by using reliable password managers like KeePassXC or Bitwarden, both available on NixOS. Pair this with enabling two-factor authentication (2FA) wherever possible.
It’s advisable to only use the desktop version and not the browser extension for a number of reasons. One is that you can store your passwords completely offline and have complete ownership of them.

environment.systemPackages = [
    pkgs.keepassxc
    pkgs.kpcli     # KeePass CLI
    # OR
    pkgs.bitwarden-desktop
    pkgs.bitwarden-cli
];

With KeePassXC, you can require 3 different authentication methods at the same time. You can choose a password, a keyfile, and a security key where it won’t open unless all 3 are present giving you additional security. All 3 might not be necessary but it’s possible. It’s also easy to migrate to KeePassXC, you can import your vault from many different managers.

KeepassXC also makes it easy to keep your complete password database offline which can significantly reduce the risk of a breach.

With Bitwarden, to enable 2 factor authentication, you need to log in with your master password through the web interface.

PrivacyGuides Intro to Passwords

Why Follow These Basics?

These recommended steps help protect your privacy and security while maintaining usability and minimizing system interruptions. They catch common threats like network eavesdropping, password reuse, fingerprinting, and data leakage, providing a solid foundation to build on.

A vast majority of secure and privacy-focused browsers available for NixOS are based on Firefox.

❗ NOTE: Firefox does lack some security features available in Chrome and sandbox escapes in Linux are relatively easy. People such as madaidan say to never use Linux or Firefox period when you’re worried about security and privacy. I’m not personally going to jump to proprietary software with known backdoors in a misguided attempt at increasing security/privacy.

EU Hits Google with 3.5 Billion Antitrust

This GrapheneOS article, breaks down why they use Chromium-based browsers and specifically mentions that it’s not recommended to use Firefox, especially on Linux because of the weak sandboxing.

As a Chromium-based browser, Brave has been growing on me. Brave uses randomization rather than standardization for fingerprinting protection. If you run Cover Your Tracks with Brave, it will show a randomized fingerprint.

✔️ Click To Expand United States Patriot Act Overview

Section 215 USA Patriot Act permits the collection of “Tangible Things” or “Business Records”, e.g., your phone records, medical records, etc. for an investigation to obtain foreign intelligence information. If it does relate to a US person it must be relevant to preventing terrorism or espionage, and not be based solely on activities protected by the first amendment. “Relevant” is the key word here and it is at the governments discretion meaning they sweep everything and sift it later. Criticized for violating American citizens Fourth Amendment protections against warrantless search and seizure and proven to be ineffective.

What is “normal” and allowed today might be suppressed tomorrow, look at the UK Online Safety Act purported to protect children, accused of banning privacy. This is because the only way to verify age is to make everyone submit KYC with their drivers license or ID, completely taking away any anonymity of adults and children alike.

Also see BBC 4chan refuses to pay fine

The mere existence of a surveillance state breeds fear and conformity and stifles free expression.–The Intercept

There are much more scary examples in Privacy, The new Oil

Protections from Surveillance in the U.S.

✔️ Click to Expand U.S. Surveillance protections

⚠️ A crucial caveat to keep in mind regarding surveillance protections in the U.S., whether grounded in the Fourth Amendment, the First Amendment, or statutory laws is that these protections are not foolproof and have repeatedly failed or been circumvented in practice.

Fourth Amendment Basics: It demands reasonableness in searches and usually requires a warrant. This means government agents cannot arbitrarily listen to your private communications or search your digital data without judicial approval
Electronic Surveillance Challenges: Courts have wrestled with how the Fourth Amendment applies to modern communications. The Supreme Court has ruled in some cases that pervasive or non-consensual electronic surveillance violates reasonable expectations of privacy, but other rulings have allowed broader state actions in national security contexts.
The Third-Party Doctrine: A major limitation arises from the “third-party doctrine,” which holds that information voluntarily shared with third parties (like phone companies or internet providers) has reduced Fourth Amendment protections. This means data held by third parties may be subject to government access without a warrant in some cases
The First Amendment guarantees free speech and the freedom to receive information without government censorship or intimidation. Excessive or secretive government surveillance can chill free speech by making people afraid their communications are monitored, discouraging open expression and participation in public discourse.
- Advocates argue that courts should recognize government surveillance not only as a Fourth Amendment search issue but also as a First Amendment violation where surveillance suppresses or chills constitutionally protected expression.

While the Fourth Amendment traditionally governs searches and surveillance legality, the First Amendment frames the broader impact on free speech and democratic engagement. Invoking both provides a more comprehensive constitutional shield against intrusive surveillance practices.

Encrypted DNS

DNS (Domain Name System) resolution is the process of translating a website’s domain name into its corresponding IP address. By default, this traffic isn’t encrypted, which means anyone on the network, from your ISP to potential hackers, can see the websites you’re trying to visit. Encrypted DNS uses protocols to scramble this information, protecting your queries and responses from being intercepted and viewed by others.

❗ NOTE: There are many other ways for someone monitoring your traffic to see what domain you looked up via DNS that it’s effectiveness is questionable without also using Tor or a VPN. Encrypted DNS will not help you hide any of your browsing activity.

There are 3 main types of DNS protection:

DNS over HTTPS (DoH): Uses the HTTPS protocol to encrypt data between the client and the resolver.
DNS over TLS (DoT): Similar to (DoH), differs in the methods used for encryption and delivery using a separate port from HTTPS.
DNSCrypt: Uses end-to-end encryption with the added benefit of being able to prevent DNS spoofing attacks.

Useful resources:

✔️ Click to Expand DNS Resources

Hot Take:

Encrypted DNS is ineffective without a VPN or Tor by madaidan

The following sets up dnscrypt-proxy using ODoH (Oblivious DNS over HTTPS) with an oisd blocklist:

Add oisd to your flake inputs:

# flake.nix
inputs = {
    oisd = {
      url = "https://big.oisd.nl/domainswild";
      flake = false;
    };
};

✔️ Add more blocklists: HaGeZi Multi PRO

To use the Hagezi Multi PRO Blocklist either with oisd or alone you could do the following:

# flake.nix
inputs = {
    oisd = {
      url = "https://big.oisd.nl/domainswild";
      flake = false;
    };
    hagezi = {
      url = "https://raw.githubusercontent.com/hagezi/dns-blocklists/main/wildcard/pro-onlydomains.txt";
      flake = false;
    };
};

add it to the extraBlocklist variable in the following dnscrypt-proxy.nix:

# dnscrypt-proxy.nix
extraBlocklist = builtins.readFile inputs.hagezi;

More blocklist url’s:

# NextDNS CNAME cloaking list
https://raw.githubusercontent.com/nextdns/cname-cloaking-blocklist/master/domains

# AdGuard Simplified Domain Names filter
https://adguardteam.github.io/AdGuardSDNSFilter/Filters/filter.txt

# OISD Big list
https://big.oisd.nl/domainswild

# HaGeZi Multi PRO
https://raw.githubusercontent.com/hagezi/dns-blocklists/main/wildcard/pro-onlydomains.txt

# HaGeZi Threat Intelligence Feeds
https://raw.githubusercontent.com/hagezi/dns-blocklists/main/wildcard/tif-onlydomains.txt

❗ NOTE: The oisd blocklist is a plain text file that updates frequently. This can cause nh os switch to fail with a NarHash mismatch error. To fix this, you need to run nix flake update to refresh the blocklist and its hash in your flake.lock file. After that, you can run your nh command again.

And the import the following into your configuration.nix:

# dnscrypt-proxy.nix
{
  pkgs,
  lib,
  inputs,
  ...
}: let
  blocklist_base = builtins.readFile inputs.oisd;
  extraBlocklist = "";
  blocklist_txt = pkgs.writeText "blocklist.txt" ''
    ${extraBlocklist}
    ${blocklist_base}
  '';
  hasIPv6Internet = true;
  StateDirName = "dnscrypt-proxy"; # Used for systemd StateDirectory
  StatePath = "/var/lib/${StateDirName}";
in {
  networking = {
    nameservers = ["127.0.0.1" "::1"];
    networkmanager.dns = "none";
  };

  services.resolved.enable = lib.mkForce false;

  services.dnscrypt-proxy = {
    enable = true;
    settings = {
      sources.public-resolvers = {
        urls = [
          "https://raw.githubusercontent.com/DNSCrypt/dnscrypt-resolvers/master/v3/public-resolvers.md"
          "https://download.dnscrypt.info/resolvers-list/v3/public-resolvers.md"
        ];
        minisign_key = "RWQf6LRCGA9i53mlYecO4IzT51TGPpvWucNSCh1CBM0QTaLn73Y7GFO3";
        cache_file = "${StatePath}/public-resolvers.md";
      };

      sources.relays = {
        urls = [
          "https://raw.githubusercontent.com/DNSCrypt/dnscrypt-resolvers/master/v3/relays.md"
          "https://download.dnscrypt.info/resolvers-list/v3/relays.md"
        ];
        cache_file = "${StatePath}/relays.md";
        minisign_key = "RWQf6LRCGA9i53mlYecO4IzT51TGPpvWucNSCh1CBM0QTaLn73Y7GFO3";
      };

      sources.odoh-servers = {
        urls = [
          "https://raw.githubusercontent.com/DNSCrypt/dnscrypt-resolvers/master/v3/odoh-servers.md"
          "https://download.dnscrypt.info/resolvers-list/v3/odoh-servers.md"
        ];
        cache_file = "${StatePath}/odoh-servers.md";
        minisign_key = "RWQf6LRCGA9i53mlYecO4IzT51TGPpvWucNSCh1CBM0QTaLn73Y7GFO3";
      };

      sources.odoh-relays = {
        urls = [
          "https://raw.githubusercontent.com/DNSCrypt/dnscrypt-resolvers/master/v3/odoh-relays.md"
          "https://download.dnscrypt.info/resolvers-list/v3/odoh-relays.md"
        ];
        cache_file = "${StatePath}/odoh-relays.md";
        minisign_key = "RWQf6LRCGA9i53mlYecO4IzT51TGPpvWucNSCh1CBM0QTaLn73Y7GFO3";
      };

      server_names = ["odoh-cloudflare" "odoh-snowstorm"];

      # This creates the [anonymized_dns] section in dnscrypt-proxy.toml
      anonymized_dns = {
        skip_incompatible = true;
        routes = [
          {
            server_name = "odoh-snowstorm";
            via = ["odohrelay-crypto-sx"];
          }
          {
            server_name = "odoh-cloudflare";
            via = ["odohrelay-crypto-sx"];
          }
        ];
      };

      ipv6_servers = hasIPv6Internet;
      block_ipv6 = !hasIPv6Internet;
      blocked_names.blocked_names_file = "${blocklist_txt}";
      require_dnssec = true;
      require_nolog = false;
      require_nofilter = false;
      odoh_servers = true;
      dnscrypt_servers = true;
    };
  };

  # This creates /var/lib/dnscrypt-proxy with correct permissions
  systemd.services.dnscrypt-proxy2.serviceConfig.StateDirectory = StateDirName;
}

This module follows a “Zero Trust” model for your internet traffic, ensuring no single entity can see both who you are and where you are going.

# You should see that dnscrypt-proxy chooses the Server with the lowest initial latency
sudo systemctl status dnscrypt-proxy2
# verify that dnscrypt-proxy is listening
sudo ss -lnp | grep 53
# Test a DNS query, if you get valid responses it's working
dig @127.0.0.1 example.com +short
# check the logs
sudo journalctl -u dnscrypt-proxy2

dnscrypt-proxy2 acts as your local DNS resolver listening on your machine (127.0.0.1) for IPv4 and ::1 for iPv6.

The system’s DNS settings (networking.nameservers) point to localhost, so all DNS queries go to dnscrypt-proxy accept for your browser. Your browser has to be configured separately with a local resolver in which I haven’t figured out yet. I recommend setting your browsers DNS over HTTPS to strict with a respected custom DNS resolver such as https://dns.quad9.net/dns-query.

inputs.oisd refers to the flake input oisd blocklist, it prevents your device from connecting to unwanted or harmful domains.

dnscrypt-proxy2 then encrypts and forwards our DNS requests to third-party public DNSCrypt or DoH servers.

ODoH Relays: This is the “Oblivious” part. It breaks the link between your IP address and your browsing history.

Setting up Tailscale

I was surprised at how easy this actually was to set up. Either go to https://www.tailscale.com and/or download the app for either Android or IOS, sign up with your identity provider, and click Start connecting devices ->

Tailscale quickstart

To add tailscale to NixOS:

# tailscale.nix
{...}: {
  services.tailscale.enable = true;
  # Tell the firewall to implicitly trust packets routed over Tailscale:
  networking.firewall.trustedInterfaces = ["tailscale0"];
}

Tailscale will automatically use the hostname of your device as the name of the network. If you want to change it to something else:

sudo tailscale set --hostname=<name>
# You can also give your account a nickname
sudo tailscale set --nickname=<name>

This allows you to refer to your network by name rather than IP address.

Tailscale uses MagicDNS which is enabled by default, and they recommend you keep it enabled.

The docs say that by default, devices in your tailnet prefer their local DNS settings and only use the tailnet’s DNS servers when needed. I had to completely disable my Androids DNS settings for tailscale to access the internet through MagicDNS.

sudo tailscale set --accept-dns=false

To connect to tailscale after rebuilding you can run:

sudo tailscale up

Use nslookup to review and debug DNS responses:

nslookup google.com
Server:         127.0.0.1
Address:        127.0.0.1#53

Non-authoritative answer:
Name:   google.com
Address: 142.251.40.206
Name:   google.com
Address: 2a00:1450:4001:827::200e

The 127.0.0.1#53 indicate that instead of using the DNS server pushed by your ISP, router, or Tailscale’s MagicDNS, the system is sending all DNS requests through the loopback device to dnscrypt-proxy in my case.

Get the status of your connections to other Tailscale devices:

tailscale status
1           2         3           4         5
100.1.2.3   device-a  apenwarr@   linux     active; direct <ip-port>, tx 1116 rx 1124
100.4.5.6   device-b  crawshaw@   macOS     active; relay <relay-server>, tx 1351 rx 4262
100.7.8.9   device-c  danderson@  windows   idle; tx 1214 rx 50
100.0.1.2   device-d  ross@       iOS       —

Tailscale Best Practices
Tailscale CLI
There is much more you can do with Tailscale, including integrating Mullvad-VPN and using Exit Nodes.

MAC Randomization

All network cards have a unique identifier called a MAC address. They’re stored in hardware and are used to assign an address to computers on the local network.

The MAC address is typically only traceable on the local network, it’s not passively sent out beyond the local router making it more critical on untrusted, public networks.

Leak-proof MAC randomization is very difficult to implement:

Leak-proof MAC Randomization Implementation Challenges

Android and iPhone already implement MAC Randomization by default.

MAC Randomization enhances privacy by making it harder for third parties to track users across different networks.

Randomizing MAC adresses obscures a device’s unique hardware identity when scanning for or connecting to Wi-Fi, blocking passive tracking as well as location tracking across networks.

If you use NetworkManager you can set MAC randomization with:

    networking = {
      networkmanager = {
        enable = true;
        wifi.scanRandMacAddress = true;
        wifi.macAddress = "random";
        plugins = [];
      };

Right when I rebuilt, I got an alert from my router saying that a new device just connected to the network.

There is also a utility for viewing/manipulating the MAC address of network interfaces, pkgs.macchanger. This is less reliable than the NetworkManager setting.

Firewalls

NixOS includes an integrated firewall based on iptables/nftables.

✔️ Click to Expand Firewall Resources

Cloudflare What is a Firewall

Beginners guide to nftables

Arch Wiki nftables

The following firewall setup is based on the dnscrypt setup above utilizing nftables.

This nftables firewall configuration is a strong recommended practice for enforcing encrypted DNS on your system by restricting all outbound DNS traffic to a local dnscrypt-proxy process. It greatly reduces DNS leak risks and enforces privacy by limiting DNS queries to trusted, encrypted upstream servers.(This was edited on 08-08-25) replace <DNSCRYPT-UID> with the UID given from the command ps -o uid,user,pid,cmd -C dnscrypt-proxy:

{ ... }: {
  networking.nftables = {
    enable = true;

    ruleset = ''
      table inet filter {
        chain output {
          type filter hook output priority 0; policy accept;

          # Allow localhost DNS for dnscrypt-proxy2
          ip daddr 127.0.0.1 udp dport 53 accept
          ip6 daddr ::1 udp dport 53 accept
          ip daddr 127.0.0.1 tcp dport 53 accept
          ip6 daddr ::1 tcp dport 53 accept

          # Allow dnscrypt-proxy2 to talk to upstream servers
          # Replace <DNSCRYPT-UID> with:
          # ps -o uid,user,pid,cmd -C dnscrypt-proxy
          meta skuid <DNSCRYPT-UID> udp dport { 443, 853 } accept
          meta skuid <DNSCRYPT-UID> tcp dport { 443, 853 } accept

          # Block all other outbound DNS
          udp dport { 53, 853 } drop
          tcp dport { 53, 853 } drop
        }
      }
    '';
  };
  networking.firewall = {
    enable = true;
    allowedTCPPorts = [
      # Ports open for inbound connections.
      # Limit these to reduce the attack surface.

      22 # SSH – Keep open only if you need remote access.
         # To change the SSH port in NixOS:
         # services.openssh.ports = [ 2222 ];
         # Update this list to match the new port.

      # 53  # DNS – Only if running a public DNS server.
      # 80  # HTTP – Only if hosting a website.
      # 443 # HTTPS – Only if hosting a secure website.
    ];
    allowedUDPPorts = [
      # Ports open for inbound UDP traffic.
      # Most NixOS workstations won't need any here.

      # 53 # DNS – Only if running a public DNS server.
    ];
  };
}

✔️ Click to Expand Tip on changing the default SSH Port

❗ TIP: Reduce SSH noise by changing the default port On most systems, SSH listens on TCP port 22 — which means automated bots and scanners will hit it constantly. While this doesn’t replace real security measures, moving SSH to a different port drastically cuts down on drive-by brute-force attempts you’ll see in your logs.

In NixOS, change both the SSH daemon port and your firewall rule:
 # Example: Move SSH to port 2222
 networking.firewall.allowedTCPPorts = [ 2222 ];
 services.openssh.ports = [ 2222 ];
After rebuilding, test from another terminal/session before closing your existing one:
ssh -p 2222 user@host

nft is a cli tool used to set up, maintain and inspect packet filtering and classification rules in the Linux kernel, in the nftables framework. The Linux kernel subsystem is known as nftables, and ‘nf’ stands for Netfilter.–man nft

sudo nft list ruleset

Since we declare our firewall, we’ll only use nft to inspect our ruleset.

NixOS Firewall vs `nftables` Ruleset

networking.nftables: This section provides a raw nftables ruleset that gives you granular, low-level control. The rules here are more specific and are meant to handle the intricate logic of the DNS proxy setup. They will be applied directly to the kernel’s nftables subsystem and prevent DNS leaks.

networking.firewall: This is a higher-level, simpler NixOS option that uses iptables rules to open ports for inbound traffic. The rules defined here (allowing port 22) is for incoming SSH connections to the machine, not for outbound traffic, so they do not interfere with the nftables rules that filter the outgoing traffic. (Make sure to comment out or remove this if you don’t SSH into your machine).

The firewall ensures only authorized, local encrypted DNS proxy process can speak DNS with the outside world, and that all other DNS requests from any other process are blocked unless they’re to 127.0.0.1 (our local proxy). This is a robust policy against both DNS leaks and local compromise.

Testing

Review listening ports: After each rebuild, use ss -tlpn, nmap or netstat to see which services are accepting connections. Close or firewall anything unnecessary.

You can also test firewall DNS restrictions using dig:

dig @127.0.0.1 example.com  # Should work

dig @8.8.8.8 example.com    # Should fail/time out for normal users

This test is actually what alerted me of an improper configuration in the above firewalls nftables rules allowing me to fix it. Initially the second dig command gave results letting me know that the restrictions weren’t being applied correctly.

Since we defined an output chain inside table inet filter with the line:

type filter hook output priority 0; policy accept;

This attaches the chain to the kernel’s OUTPUT hook, so all locally generated packets, including DNS queries are filtered by this chain.

Within this chain, the rules:

Explicitly allow DNS queries to localhost addresses (127.0.0.1 and ::1).
Allow the dnscrypt-proxy process (running with UID 62396) to send DNS queries on ports 443 and 853 (for DNS-over-HTTPS and DNS-over-TLS).
Drop all other outbound DNS traffic on ports 53 and 853.

Because of this setup, dig queries to your local resolver at 127.0.0.1 pass, but queries directly to public DNS servers like 8.8.8.8 are blocked for users/processes other than the allowed DNS proxy.

OpenSnitch

NixOS Wiki OpenSnitch

Opensnitch is an open-source application firewall that focuses on monitoring and controlling outgoing network connections on a per-application basis.

This can be used to block apps from accessing the internet that shouldn’t need to (i.e., block telemetry and more). Opensnitch will report that the app has attempted to make an outbound internet connection and block it or allow it based on the rules you set.

Resources

✔️ Click to Expand Resources

Cloudflare What is HTTPS
Surveillance Self-Defence has a lot of helpful info to protect your privacy.
What is Fingerprinting, more than you realize is being tracked constantly.
oisd.nl the oisd website
For potentially dangerous file types like PDFs, office documents, or images, especially those downloaded from untrusted sources such as torrents, consider converting them to a safe PDF format with dangerzone. Dangerzone not only removes metadata but also applies robust sanitization to neutralize malicious content.
NixOS Wiki LibreWolf, the options in the wiki make it less secure and aren’t recommended settings to use. They explicitly disable several of LibreWolf’s default privacy-enhancing features, such as fingerprinting resistance and clearing session data on shutdown.
LibreWolf Features You still need to enable DNS over HTTPS through privacy settings.
SearXNG on NixOS
- Welcome to SearXNG
Firefox Hardening Guide
Firefox ghacks
Arkenfox
PrivacyTools.io
simeononsecurity Firefox-Privacy-Script
brianfucksec firefox-hardening-Guide 2023
STIG Firefox Hardening

If you should trust the U.S. Governments recommendations is another story but it can be good to compare and contrast with other trusted resources. You’ll have to think whether the CISA recommending that everyone uses Signal is solid advice or guiding you towards a honeypot, I can’t say for sure.

Mozilla Firefox Security Technical Implementation Guide The STIG for Mozilla Firefox (Security Technical Implementation Guide) is a set of security configuration standards developed by the U.S. Department of Defense. They are created by the Defense Information Systems Agency (DISA) to secure and harden DoD information systems and software.
Privacy, The New Oil (Why Privacy & Security Matter)
PrivacyGuides
Firefox Relay can be used to create email aliases that forward to your real email address. The paid plan also lets you create phone number aliases that forward to your phone number.
Zebra Crossing digital safety checklist
DataDetoxKit
DataDetox Degooglise
Tor Browser User Manual
Tor Wiki
Linux Network Administrators Guide
IBM Networking

Browsing Security

2025-12-21T00:00:00+00:00

✔️ Table of Contents

Browser/Browsing Security: Defense in Depth

“The major problem with current systems is their inability to provide effective isolation between various programs running on one machine. E.g. if the user’s Web browser gets compromised (due to a bug exploited by a malicious web site), the OS is usually unable to protect other user’s applications and data from also being compromised.” –Qubes arch-spec

The web browser is the most complex, most exposed, and most vulnerable application on a hardened Linux system. It is your primary interface with the internet and, consequently, the primary vector for exploitation and tracking.

The Three Pillars of Web Defense To secure your browsing, you must balance three often-conflicting goals:

Security (Exploit Mitigation): Preventing malicious sites from escaping the browser sandbox to access your local files or execute code.
Privacy (Tracking Protection): Preventing advertisers and sites from linking your current session to your real-world identity or browsing history.
Anonymity (Identity Obfuscation): Making your traffic indistinguishable from thousands of other users to hide your physical location and legal identity.

Methods of Protection

Browser hardening focuses on reducing attack surface and blocking tracking by disabling or restricting features like JavaScript, cookies, telemetry, and third-party scripts.
Fingerprint protection, on the other hand, aims to make your browser indistinguishable from others. Instead of just blocking data collection, it ensures that your browser’s configuration; screen size, fonts, user agent, etc. matches a large group of users, so you blend in.
Anonymity: Maximizing anonymity often means restricting or masking features (setting a generic fingerprint, disabling browser APIs, blocking trackers) so the browser blends in with many others. This reduces uniqueness but can break website functionality, cause CAPTCHAs, and limit usability.
Browser compartmentalization is a technique where different browsers are dedicated to distinct online activities to isolate cookies, trackers, and browsing data. For example, Mullvad Browser can be used solely for activities where fingerprinting resistance is critical, such as anonymous browsing or visiting privacy-sensitive sites. Meanwhile, a hardened LibreWolf or Firefox can be used for general browsing, email, or banking where you want solid security and feature flexibility but aren’t as concerned about fingerprint uniqueness.

On a hardened Linux system, the browser is most often the weakest link exposed to the internet, and so security, privacy, and anti-tracking features of browsers are now as important, or even more important than platform-level protections.

Browsers leak identity in two main ways: network identifiers (IP address, DNS, TLS metadata) and browser identifiers (fingerprinting + tracking). This chapter focuses on the browser side first, then covers when a VPN or Tor changes the network side. Before tweaking anything, pick the browsing goal (anonymity vs privacy vs convenience), because the “best” settings differ.

If the goal is blending in, prefer a browser that ships with a shared, consistent fingerprint (Tor Browser / Mullvad Browser). If the goal is mainly reducing cross-site tracking for normal browsing, a hardened Firefox/LibreWolf profile with minimal extensions is usually easier to live with.

Fingerprinting

Modern web APIs make rich, customized experiences possible, but they also reveal enough low‑level details about your device and browser to build a unique fingerprint. This fingerprint can be used for hidden, persistent tracking, even when cookies are blocked.

Browser fingerprinting is a tracking technique, often done by third-party companies that specialize in it. They provide code (usually JavaScript) that a website owner can embed on their site. When you visit the site, the script runs in the background, silently collecting data about your device and browser.

Entropy: in this context, is a measure of how much unique information a specific browser feature contributes to your fingerprint. It’s often quantified in bits of entropy, where higher bits mean more uniqueness (i.e., easier to identify you).
- A “bit” is a basic unit of information for computers. Entropy measuring sites results are measured in “bits of identifying information”.

There are two main approaches to obfuscating your fingerprint:

Standardization: Make browsers standardized and therefore have the same fingerprint to blend into a crowd. This is what Tor and Mullvad Browser do. Best for anonymity; increases the crowd you blend into, but may decrease usability (site breakage, CAPTCHAs); adversaries may still find subtle differences.
Randomization: Randomize fingerprint metrics so it’s not directly linkable to you. Brave has this feature, if you run coveryourtracks with Brave you will get a result of “your browser has a randomized fingerprint”. This is good for privacy but may be detectable by advanced scripts.

Fingerprint Testing

You can test your browser to see how well you are protected from tracking and fingerprinting at Cover Your Tracks.

Also check out, Am I Unique

⚠️ WARNING: Don’t put too much weight into the results as people often check their fingerprint, change one metric and check it again over and over skewing the results. It is helpful for knowing the fingerprint values that trackers track.

Browsers

I currently run NixOS in a VM with a secureblue host, Trivalent is my default browser, a security-focused, Chromium-based browser.

In this section, the goal is to outline several browser options on NixOS and show concrete configurations (with a focus on LibreWolf that can be adapted to Firefox). Browsers are complicated and people have different security, privacy, and usability needs, so this is not an endorsement of a single “best” choice. Instead, the following subsections describe trade-offs and example setups so you can decide which browser and configuration best match your own threat model and workflow.

IMO there aren’t many Chromium-based browsers on NixOS that hit the sweet spot of being both security-forward and privacy-respecting. Many of the “privacy browser” options you’ll see on NixOS are Firefox forks; with the right tweaks they can be made pretty private, but they generally don’t match Chromium-family browsers on exploit mitigations and sandbox depth.

Brave

Brave is basically “Chromium, but with privacy features turned on by default,” and the big win is that most of the protection comes from the browser itself (Shields + anti-fingerprinting) instead of from a pile of extensions. Brave’s fingerprinting story is also unusually practical: instead of trying to make every Brave user look identical, it mixes API blocking with per-site/per-session randomization (“farbling”) so the fingerprint is harder to reuse across contexts.

On NixOS, IMO the best available Chromium-based browser is Brave. Brave strips out Google’s tracking code and includes a native add/tracker blocker (Brave Shields). It also ships a best‑effort anti‑fingerprinting system that combines (1) blocking/removing/modifying certain high-signal APIs and (2) “privacy through randomization” (farbling), where it returns slightly altered values so fingerprints don’t stay stable across sites/sessions.

Things to Note about Brave:

Shields is a bundle of controls (trackers/ads, cookies, fingerprinting defenses, HTTPS upgrades, referrer/query stripping, storage cleanup), so turning Shields off for a broken site is a big privacy downgrade for that site—not just “adblock off.”
Brave explicitly recommends validating fingerprinting defenses with realistic tests (new private window, restart browser, different profile, clear site storage) and expects the fingerprint to change across those boundaries.
Extension bloat will break Brave’s privacy and security story: each extension increases attack surface and usually has broad privileges, while Brave’s core pitch is that you can get most of the privacy wins without third-party code in your browser process

Drawbacks worth mentioning:

Brave is still Chromium/Blink, so using it doesn’t help with engine diversity; if Gecko dies, the web becomes even more “whatever Chromium implements,” which is a long-term ecosystem risk.
Brave ships a lot (Rewards, Wallet, VPN upsells, Leo/AI features depending on build/channel), and every extra subsystem is more UI complexity and potentially more bugs/attack surface than some browsers.
Brave’s model assumes the browser does most privacy work; piling on extensions increases privileged code, fingerprint uniqueness, and the chance of a malicious/compromised extension.
Farbling and API defenses reduce stability/linkability, but sophisticated trackers can still correlate behavior, logins, IP ranges, and high-level patterns—so “I enabled anti-fingerprinting” shouldn’t be read as “I can’t be tracked.”
Brave’s built-in ad system (Rewards) is opt-in, but Brave also promotes features like Rewards and can show sponsored content (e.g., sponsored new-tab images) unless you disable/hide it

Firefox

Firefox is kind of its own thing: it runs on Gecko, not on Chromium or WebKit, so it’s one of the only mainstream browsers that isn’t just another Chrome fork. That uniqueness matters if you care about engine diversity and not having the entire web effectively dictated by a single vendor. It’s also very tweakable, so if you’re willing to flip some prefs and add a couple of key extensions, you can turn it into a solid privacy‑focused daily driver without giving up a non‑Chromium stack.

Firefox will usually get security fixes sooner than any fork, and some forks lag behind on patching, which can leave known vulnerabilities exploitable for longer. If you use Firefox’s built‑in Enhanced Tracking Protection (ETP), Resist Fingerprinting (RFP), and hardening templates like ghacks or Arkenfox together with uBlock Origin configured for dynamic filtering, you can replicate what used to require a pile of separate extensions.

Site Isolation & Firefox Links

Firefox does implement Site Isolation via Project Fission, but it’s newer and historically less mature than Chromium’s site‑per‑process model, and it may not be enabled everywhere by default. To check that it is active, go to about:config and ensure both fission.autostart and gfx.webrender.all are set to true.

With uBlock Origin you can disable JavaScript per‑site (similar to NoScript), enable a bunch of high‑quality blocklists, and selectively relax rules when a trusted site breaks. To turn on Enhanced Tracking Protection and fingerprinting protections in the UI, go to Settings -> Privacy & Security -> Enhanced Tracking Protection -> Custom; if that causes breakage on a particular website, click the shield icon in the URL bar and disable protections just for that site.

uBlock Wiki

Once you select Custom, you’ll see that among the options is to block Known fingerprinters as well as Suspected fingerprinters. The “Known Fingerprinters” protection works by blocking scripts listed in Disconnect’s fingerprinting list For most users they suggest using the above FPP to avoid breakage. To go further and enable RFP, go to about:config and set privacy.resistFingerprinting to true.

✔️ Further Reading on Firefox Defenses

Mozilla Resist Fingerprinting
- To ensure Site Isolation is enabled, in about:config, set fission.autostart, and gfx.webrender.all prefs to true.(It’s disabled by default on android).
Entropy: in this context, is a measure of how much unique information a specific browser feature contributes to your fingerprint. It’s often quantified in bits of entropy, where higher bits mean more uniqueness (i.e., easier to identify you).
- A “bit” is a basic unit of information for computers. Entropy measuring sites results are measured in “bits of identifying information”.
Origin: Web content’s origin is defined by the scheme (protocol), hostname (domain), and port of the URL used to access it. Two objects have the same origin only when the scheme, hostname, and port all match.
Same-origin policy: is a critical security mechanism that restricts how a document or script loaded by one origin can interact with a resource from another origin. It helps isolate potentially malicious documents, reducing possible attack vectors.
Firefox Site-Isolation. Firefox does provide site-isolation as well.
Protection from side-channel attacks
MDN Insecure passwords
- Risks of reused passwords

LibreWolf

LibreWolf is an open-source fork of Firefox with a strong focus on privacy, security, and user freedom. LibreWolf enables always HTTPS, includes uBlockOrigin, and only includes privacy focused search engines by default.

Example LibreWolf config implementing many of the STIG recommendations:

✔️ Click to expand LibreWolf Example

# librewolf.nix
{pkgs, lib, config, ...}: let
  cfg = config.custom.librewolf;
in {
  options.custom.librewolf = {
    enable = lib.mkOption {
      type = lib.types.bool;
      default = true;
      description = "Enable the LibreWolf Module";
    };
  };

  config = lib.mkIf cfg.enable {
    programs.librewolf = {
      enable = true;
      policies = {
        # A bit annoying
        DontCheckDefaultBrowser = true;
        # Pocket is insecure according to DoD
        DisablePocket = true;
        # No imperative updates
        DisableAppUpdate = true;
      };
      settings = {
        # // SV-16925 - DTBF030
        "security.enable_tls" = true;
        # // SV-16925 - DTBF030
        "security.tls.version.min" = 2;
        # // SV-16925 - DTBF030
        "security.tls.version.max" = 4;

        # // SV-111841 - DTBF210
        "privacy.trackingprotection.fingerprinting.enabled" = true;

        # // V-252881 - Retaining Data Upon Shutdown
        "browser.sessionstore.privacy_level" = 0;

        # // SV-251573 - Customizing the New Tab Page
        "browser.newtabpage.activity-stream.enabled" = false;
        "browser.newtabpage.activity-stream.feeds.section.topstories" = false;
        "browser.newtabpage.activity-stream.showSponsored" = false;
        "browser.newtabpage.activity-stream.feeds.snippets" = false;

        # // V-251580 - Disabling Feedback Reporting
        "browser.chrome.toolbar_tips" = false;
        "browser.selfsupport.url" = "";
        "extensions.abuseReport.enabled" = false;
        "extensions.abuseReport.url" = "";

        # // V-251558 - Controlling Data Submission
        "datareporting.policy.dataSubmissionEnabled" = false;
        "datareporting.healthreport.uploadEnabled" = false;
        "datareporting.policy.firstRunURL" = "";
        "datareporting.policy.notifications.firstRunURL" = "";
        "datareporting.policy.requiredURL" = "";

        # // V-252909 - Disabling Firefox Studies
        "app.shield.optoutstudies.enabled" = false;
        "app.normandy.enabled" = false;
        "app.normandy.api_url" = "";

        # // V-252908 - Disabling Pocket
        "extensions.pocket.enabled" = false;

        # // V-251555 - Preventing Improper Script Execution
        "dom.disable_window_flip" = true;

        # // V-251554 - Restricting Window Movement and Resizing
        "dom.disable_window_move_resize" = true;

        # // V-251551 - Disabling Form Fill Assistance
        "browser.formfill.enable" = false;

        # // V-251550 - Blocking Unauthorized MIME Types
        "plugin.disable_full_page_plugin_for_types" = "application/pdf,application/fdf,application/xfdf,application/lso,application/lss,application/iqy,application/rqy,application/lsl,application/xlk,application/xls,application/xlt,application/pot,application/pps,application/ppt,application/dos,application/dot,application/wks,application/bat,application/ps,application/eps,application/wch,application/wcm,application/wb1,application/wb3,application/rtf,application/doc,application/mdb,application/mde,application/wbk,application/ad,application/adp";
      };
    };
    xdg.desktopEntries.librewolf = {
      name = "LibreWolf";
      exec = "${pkgs.librewolf}/bin/librewolf";
    };
    xdg.mimeApps = {
      enable = true;
      defaultApplications = {
        "text/html" = "librewolf.desktop";
        "x-scheme-handler/http" = "librewolf.desktop";
        "x-scheme-handler/https" = "librewolf.desktop";
        "x-scheme-handler/about" = "librewolf.desktop";
        "x-scheme-handler/unknown" = "librewolf.desktop";
      };
    };
  };
}

And enable it in your home.nix or equivalent with:

# home.nix
custom.librewolf.enable = true;

The xdg settings at the end make LibreWolf the defaults for what is listed.

Thanks to JosefKatic for putting the above STIG settings in NixOS format.

Also, go to accounts.firefox and turn off “Allow Mozilla accounts to send technical and interaction data to Mozilla”. Also set 2-fa in Security Settings

I always set Max Protection for DNS over HTTPS and personally set a custom resolver to https://dns.quad9.net/dns-query

Mullvad is also a good option: Mullvad no-logging-data-policy

✔️ Alternative LibreWolf Configuration utilizing Arkenfox

{
  pkgs,
  lib,
  config,
  ...
}: let
  cfg = config.custom.librewolf;
in {
  options.custom.librewolf = {
    enable = lib.mkOption {
      type = lib.types.bool;
      default = true;
      description = "Enable the LibreWolf Module";
    };
  };

  config = lib.mkIf cfg.enable {
    programs.librewolf = {
      enable = true;
      policies = {
        DontCheckDefaultBrowser = true;
        DisablePocket = true;
        DisableAppUpdate = true;
      };
      profiles.my-default = {
        isDefault = true;
        name = "Default Profile";
        extraConfig = ''
          ${builtins.readFile ./user.js}
          "general.autoScroll" = true;
          "sidebar.verticalTabs" = true;
        '';

        settings = {
        };
      };
    };
    xdg.desktopEntries.librewolf = {
      name = "LibreWolf";
      exec = "${pkgs.librewolf}/bin/librewolf";
    };
    xdg.mimeApps = {
      enable = true;
      defaultApplications = {
        "text/html" = "librewolf.desktop";
        "x-scheme-handler/http" = "librewolf.desktop";
        "x-scheme-handler/https" = "librewolf.desktop";
        "x-scheme-handler/about" = "librewolf.desktop";
        "x-scheme-handler/unknown" = "librewolf.desktop";
      };
    };
  };
}

Download the Arkenfox user.js and review it making sure that you agree with the settings. If you do, place it in the same directory as your librewolf.nix.

Read the Arkenfox Wiki

The user.js is full of comments and information, read it and adjust it for your needs. The following enables RFP fingerprint protection:

***/ user.js ***/
user_pref("privacy.resistFingerprinting", true); // [FF41+]
user_pref("privacy.resistFingerprinting.pbmode", true); // [FF114+]

As you learn more, you can get more strict if you so choose.

Rebuild, launch LibreWolf, and check your ~/.librewolf/my-default/user.js. It should match the Arkenfox settings. Initially, only the user.js will be listed, as you run LibreWolf other profile files and folders are created dynamically.

In LibreWolf type Ctrl + Shift + J and look for any errors.

Type about:config into the address bar and search a few of the settings that Arkenfox changes, do they match?

The user.js is read in order, if there are 2 of the same setting, the last one will be applied. Adding overrides to the settings attribute above places the changes at the beginning of the user.js which isn’t what we want. Placing them after the ${builtins.readFile ./user.js} in extraConfig amends them to the end of the user.js allowing us to override the defaults.

The process is the same with Firefox but since Arkenfox strongly recommends Ublock Origin and it is built into LibreWolf it makes sense to use the browser with the stronger defaults.

❗ NOTE: There is a home-manager module called arkenfox-nixos that is supposed to make updates easier but IMO the documentation leaves you guessing how to use it. As updates come in to Firefox/LibreWolf some of the settings become unnecessary so it’s important to keep an eye on both Firefox and Arkenfox updates. Which both have RSS feeds that will alert you upon changes.

I personally use Feeder as my open-source RSS feed reader, available in most app stores including F-Droid. It is listed on PrivacyTools.

Search Defaults

Startpage: Advertised as the world’s most private search engine. “Startpage delivers Google search results via their proprietary personal data protection technology.”

Startpage
To add Startpage as a search engine, add https://www.startpage.com/sp/search?query=%s.

SearXNG an open-source, privacy-respecting metasearch engine that aggregates results from various search services, such as Google, DuckDuckGo, etc. without tracking you or profiling your searches. You can add SearXNG to firefox by going to about:preferences#search and at the bottom click Add, URL will be https://searx.be/search?q=%s.

❗️ NOTE: SearXNGs google results are not working as of 11-17-25 and haven’t for a while now leading to bad results being returned for most instances. It’s my understanding this is because Google is actively blocking automated requests from SearXNG. Devs sometimes publish patches or workarounds, but these are quickly blocked when Google changes their back-end.

❗️ NOTE: The above searx is the default and doesn’t give many relevant results. To get relevant results find a public instance with a good rating from your area and add the search?q=%s to the end of it. For example, I’m using https://priv.au/search?q=%s.

Searx is a bit different, you can choose which search engine you want for your current search with !ddg search term to use duckduckgo for example.

Tor Browser

❗ NOTE: Tor is not the most secure browser, anonymity and security can often be at odds with each other. Having the exact same browser as many other people isn’t the best security practice, but it is great for anonymity. Tor is also based on Firefox Esr, which only receives patches for vulnerabilities considered Critical or High which can be taken advantage of.

Tor is a modified version of Firefox specifically designed for use with Tor.

Tor routes your internet traffic through a global volunteer-operated network, masking your IP address and activities from local observers, ISPs, websites, and surveillance systems. This helps you protect personal information and maintain anonymity when browsing, communicating, or using online services.

Adding browser plugins to Tor can de-anonymize you, don’t do it. Tor is already built with the necessary plugins and privacy protecting rules, so adding more is unnecessary and actually dangerous for your anonymity.

A Tor exit node can easily see your traffic, and if you’re not using HTTPS then it may be able to modify that traffic. Only use HTTPS when browsing the clear net with Tor, this doesn’t apply to onion services (.onion) as the traffic stays inside the Tor network all the way to the destination.

You can visit both the clear web and .onion sites on Tor. Whenever possible you should utilize Onion Services (.onion addresses) so communications and web browsing stay within the Tor network. .onion URLS form a tunnel that is end-to-end encrypted using a random rendezvous point and incorporating perfect forward secrecy (PFS).

Bridges are only necessary in countries that don’t allow people to use Tor. Using Bridges when they aren’t needed takes resources away from people in oppressive regimes that need, only use them if necessary. Read the guides, and use Tails OS, or Whonix when it really matters.

Whonix KVM on NixOS

You will see a lot of conflicting information about using Tor with a VPN. If you are in an area that blocks access to Tor or it is dangerous to use Tor, by all means use a trusted VPN.

TorPlusVPN

Learn about Tor

I recommend starting with Privacy Guides In Praise of Tor and then reading their Tor Overview they have been the most informative resources I’ve come across yet.

The Electronic Frontier Foundation sponsors and helps fund Tor and so does the United States Government.

If you are fortunate to live outside of oppressive regimes with extreme censorship, using Tor for every day, mundane activities is likely safe and won’t put you on any harmful “list.” Even if it did, you’d be in good company—these lists mostly contain great people working tirelessly to defend human rights and online privacy worldwide.

By using Tor regularly for ordinary browsing, you help strengthen the network, making it more robust and anonymous for everyone. This collective support makes staying private easier for activists, journalists, and anyone facing online surveillance or censorship. The writer of the PrivacyGuides article mentions using Tor when he needs to access Google Maps to protect his privacy

So, consider embracing Tor not only for sensitive browsing but also for daily routine tasks. Every user adds valuable noise to the network, helping protect privacy and freedom for all.

Tor is at risk, and needs our help. Despite its strength and history, Tor isn’t safe from the same attacks oppressive regimes and misinformed legislators direct at encryption and many other privacy-enhancing technologies.–How to Support Tor

Tor on NixOS

Mullvad-Browser

Rather than try to tweak a browser into fingerprinting submission, I recommend using either Tor or Mullvad-Browser when fingerprintability is the highest issue. Both Tor and Mullvad-Browser were designed specifically for this purpose and you likely won’t get as much out of tweaking another browser.

Mullvad-Browser is free and open-source and was developed by the Tor Project in collaboration with Mullvad VPN.(Another Firefox Derivative). It is also the top recommended browser from PrivacyGuides.

It is the Tor Browser without the Tor Network, allowing you to use the privacy features Tor created along with a VPN if you so choose.

Mullvad-Browser, is in Nixpkgs as: pkgs.mullvad-browser

Making Your Browser Amnesic, the Nix Way

Problem: Browsers leak data via .cache and .config.

Pro Tip: Even if you use a persistent home directory, you should mount your ~/.cache folder to tmpfs.

Performance: Browsers perform thousands of small read/writes to the cache. In-memory storage is significantly faster.
Disk Health: It prevents “SSD wear” from constant caching of temporary web assets.
Forensic Hygiene: It ensures that volatile “junk” like images, scripts, and stylesheets never touches your physical platter.

Note: This will not wipe your browser session (tabs, cookies, history), as those are stored in ~/.config. If you want a truly “amnesic” browsing session that wipes everything on reboot, you must also mount your browser’s profile directory (e.g., ~/.mozilla or ~/.config/BraveSoftware) to tmpfs.

fileSystems."/home/youruser/.cache" = {
  device = "none";
  fsType = "tmpfs";
  options = [ "size=4G" "mode=777" ];
};

Ensure it was applied with:

findmnt /home/youruser/.cache

You can apply the same tmpfs logic to your config folder. Warning: This will wipe your settings, extensions, and history every reboot.

Manual tmpfs mounts in configuration.nix are powerful because they happen at the system level, but they require explicit ownership (uid/gid) to work with user-level applications.

fileSystems."/home/youruser/.config/BraveSoftware" = {
  device = "none";
  fsType = "tmpfs";
  options = [
  "size=4G"
  "mode=700" # Use 700 for privacy
  "noatime"
  # Replace `1000` with the output of `id -u`
  "uid=1000"
  # Replace `100` with output of `id -g`
  "gid=100"
  ];
};

How to find your UID/GID

id -u && id -g

Replace the above uid=, and gid= values with the output of the above command.

✔️ Example Script to wipe cache and generate new `machine-id`

If you followed the above “Nix way” of Amnesic cache, the following script is unnecessary, I’m leaving it here for now for those that are interested in changing their machine-id imperatively.

man page machine-id(5)
The following example is adapted from Firejail All About Tor section, adapted for NixOS.

Save the following script as cleanup.sh, change Your-User to your username:

#!/bin/sh -e
USER="Your-User"
HOME_DIR="/home/$USER"
# clear user cache directly as root
sudo -u "$USER" rm -fr "$HOME_DIR/.cache"
# generate a new machine-id
rm -f /var/lib/machine-id
dbus-uuidgen > /var/lib/machine-id
cp /var/lib/machine-id /etc/machine-id
chmod 444 /etc/machine-id
exit 0

The ~/.cache directory is where most programs store runtime information: webpages you visited, torrent trackers you connected to, and deleted emails. It’s a good idea to remove them at shutdown. –Firejail all-about-tor

Check /etc/machine-id & ~/.cache before running the script:

cat /etc/machine-id
# Output
0b46feb27a20469da0ee62baaeb51c5c
ls ~/.cache

chmod +x cleanup.sh
sudo ./cleanup.sh

Recheck your machine-id and ~/.cache directories, you should have a newly generated machine-id and minimal files in the ~/.cache directory. The Firejail example shows a systemd unit that runs the above script at every shutdown but that may be overkill, I suggest running it occasionally to make it harder for sites to link your machine-id to you.

Privacy protection doesn’t need to be perfect to make a difference. The best protection against tracking and fingerprinting available is to use Tor. Many add-ons are redundant, do some research and avoid using an add-on for something that can be accomplished with built-in settings.

Surveillance Self-Defense How to: Use Tor

There are more hardening parameters that can be set but this should be a good starting point for a hardened version of LibreWolf. When testing with Cover your tracks, customized LibreWolf tested as having stronger tracking protection than default Mullvad-Browser and NoScript significantly cuts down the data available for fingerprinting by disabling JavaScript.

The Garuda Privacy-Guide has good tips and recommendations for browser add-ons.

Virtual Private Networks (VPNs)

A VPN (Virtual Private Network) encrypts your Internet connection and routes your traffic through a VPN provider’s servers, masking your IP address from local network observers, ISPs, and websites. Using a VPN can prevent your ISP or local Wi-Fi owner from tracking what sites you visit (they only see a connection to the VPN), and can help circumvent some regional restrictions or filtering.

However, VPNs simply shift your trust: Instead of your ISP seeing your activity, your VPN provider can, so you must trust their privacy policies and infrastructure. Quality and privacy protections vary widely from one VPN company to another.

I see over and over again that Mullvad VPN is the best, I am in no way affiliated with them this is just what I hear. They allow you to pay with cash completely anonymously and keep very minimal metadata. Metadata is a big deal, the US gov has admitted to killing people based solely on their metadata.

Your ISP almost certainly does sketchy stuff with your data, personally I would rather trust a company like Mullvad whose whole reputation is based on their trustworthiness, transparency, and data protection.

You can use a VPN with Tor, but it’s not recommended by the Tor Project unless you’re an advanced user who knows how to configure both in a way that doesn’t compromise your privacy.

Popular VPNs on NixOS

Mullvad VPN Mullvad VPN uses WireGuard under the hood and only works if systemd-resolvd is enabled.
WireGuard VPN, WireGuard is a protocol, but also a VPN provider on NixOS.
Tailscale
OpenVPN, OpenVPN is both a protocol and full-featured VPN provider on NixOS.

JJ VCS

2025-12-08T00:00:00+00:00

Version Control with JJ

✔️ Click to Expand Table of Contents

**Image Source:** This image is from the [Jujutsu VCS repository](https://github.com/jj-vcs/jj) and is licensed under the Apache 2.0 License.

⚠️ Security Reminder: Never commit secrets (passwords, API keys, tokens, etc.) in plain text to your Git repository. If you plan to publish your NixOS configuration, always use a secrets management tool like sops-nix or agenix to keep sensitive data safe. See the Sops-Nix Guide for details.

Getting Started

Jujutsu (jj) is a modern, Git-compatible version control system designed to simplify and improve the developer experience. It offers a new approach to distributed version control, focusing on a more intuitive workflow, powerful undo capabilities, and a branchless model that reduces common pitfalls of Git.

Recommended resources:

Steve’s Jujutsu Tutorial (most up to date). Steve does an excellent job explaining the ins and outs of Jujutsu.
zerowidth jj-tips-and-tricks
Official:

jj help -k tutorial

Every time you run a jj command, it examines the working copy and takes a snapshot.
Command help:

jj <command> --help
jj git init --help
jj git push --help

🔑 Key Concepts

✔️ Click to Expand Key Concepts

Working Copy as Commit

In JJ your working copy is always a real commit. Any changes you make are automatically recorded in this working commit. The working copy is always (@) and the Parent commit is always (@-) keep this in mind.
There is no staging area (index) as in Git. You do not need to run git add or git commit for every change. Modifications are always tracked in the current commit.

Branchless Workflow and Bookmarks

JJ does not have the concept of a “current branch.” Instead, use bookmarks, which are named pointers to specific commits.
Bookmarks do not move automatically. Commands like jj new and jj commit move the working copy, but the bookmark stays were it was. Use jj bookmark move to move bookmarks. (e.g., jj bookmark move main). You can also use jj bookmark set main -r @ to explicitly set the main bookmark to point at the working copy commit.
Only commits referenced by bookmarks are pushed to remotes, preventing accidental sharing of unfinished work.

Automatic Tracking and Simpler Workflow

To stop tracking a specific file, first add it to your .gitignore, then run jj untrack <file>

The working copy acts as a live snapshot of your workspace. Commands first sync filesystem changes into this commit, then perform the requested operation, and finally update the working copy if needed.

Operation Log and Undo

JJ records every operation (commits, merges, rebases, etc.) in an operation log. Inspect it with: jj op log
You can view and undo any previous operation, not just the most recent one, making it easy to recover from mistakes, a feature not present in Git’s core CLI.

First-Class Conflict Handling

Conflicts happen when JJ can’t figure out how to merge different changes made to the same file.

Conflicts are stored inside commits, not just in the working directory. You can resolve them at any time, not just during a merge or rebase.
Conflict markers are inserted directly into files, and JJ can reconstruct the conflict state from these markers. You can resolve conflicts by editing the files or using jj resolve.

Revsets and Filesets

Revsets: JJ’s powerful query language for selecting sets of commits, inspired by Mercurial. For example, jj log -r "author(alice) & file(*.py)" lists all commits by Alice that touch Python files.
Filesets:JJ supports a functional language for selecting sets of files, allowing advanced file-based queries and operations.

Feature	Git	Jujutsu (jj)
Staging Area	Yes (git add/index)	No, working copy is always a commit
Commit Workflow	Stage → Commit	All changes auto-recorded in working commit
Branches	Central to workflow	Optional, bookmarks used for sharing
Undo/Redo	Limited, complex	Easy, operation log for undo
Conflict Handling	Manual, can be confusing	Conflicts tracked in commits, easier to fix
Integration with Git	Native	Fully compatible, can switch back anytime

Anonymous branches: In Git a branch is a pointer to a commit that needs a name.

If you haven’t taken the time to deep dive Git, it may be a good time to learn about a new way of doing Version Control that is actually less complex and easier to mentally map out in my opinion.

Jujutsu is a new front-end to Git, and it’s a new design for distributed version control. –jj init

You can use jujutsu (jj) with existing Git repositories with one command. jj git init --colocate or jj git init --git-repo /path/to/git_repository. The native repository format for jj is still a work in progress so people typically use a git repository for backend.

Unlike git, jj has no index “staging area”. It treats the working copy as an actual commit. When you make changes to files, these changes are automatically recorded to the working commit. There’s no need to explicitly stage changes because they are already part of the commit that represents your current working state.

Simplified Workflow

Check where you’re at, JJ doesn’t care about commits without descriptions but Git and GitHub do:

❯  jj st
The working copy has no changes.
Working copy  (@) : n a8b19ca2 (empty) (no description set)
Parent commit (@-): k 8c487558 edit(jj): ui.color = always diff.format color-words

We can see that the Working copy is (empty) and has (no description set), lets give it a description:

❯  jj desc -m "chore: nix flake update"
Working copy  (@) now at: n 5c36a33d (empty) chore: nix flake update
Parent commit (@-)      : k 8c487558 edit(jj): ui.color = always diff.format color-words

I ran nix flake update, let’s check our status:

❯  jj st
Working copy changes:
M flake.lock
Working copy  (@) : n d54ab019 chore: nix flake update
Parent commit (@-): k 8c487558 edit(jj): ui.color = always diff.format color-words

We can see that running nix flake update modified M our flake.lock. To finalize this change we can run jj new.

❯  jj new
Working copy  (@) now at: v cad9d50b (empty) (no description set)
Parent commit (@-)      : n d54ab019 chore: nix flake update

Now, looking at the output of jj new above, we can see that the Working copy is empty and has no description set. If we want to push these changes to GitHub, we have to point the main bookmark where the changes exist, the Parent commit in this case:

❯  jj bookmark set main -r @-
Moved 1 bookmarks to n d54ab019 main* | chore: nix flake update

Notice the main*, the * indicates that our local main has changes that main@origin does not have.

Ok, our main bookmark is now pointing at our latest changes. We can now run jj git push to push them to the remote and make them a part of the permanent record:

❯  jj git push
Changes to push to origin:
  Move forward bookmark main from 3956b1386d0a to d54ab0197bef
git: Enumerating objects: 14, done.
git: Counting objects: 100% (14/14), done.
git: Delta compression using up to 16 threads
git: Compressing objects: 100% (10/10), done.
git: Writing objects: 100% (10/10), 1.52 KiB | 520.00 KiB/s, done.
git: Total 10 (delta 7), reused 0 (delta 0), pack-reused 0 (from 0)
remote: Resolving deltas: 100% (7/7), completed with 4 local objects.

Success! Let’s check out our status again:

❯  jj st
The working copy has no changes.
Working copy  (@) : v cad9d50b (empty) (no description set)
Parent commit (@-): n d54ab019 main | chore: nix flake update

Notice that main* is now just main, indicating our local and remotes are in sync!

Let’s check out the log:

❯  jj log
@  v sayls8@proton.me 2026-03-22 12:35:34 5835b760
│  (no description set)
◆  n sayls8@proton.me 2026-03-22 12:26:20 main d54ab019
│  chore: nix flake update
~

The ◆ indicates that change n is now immutable after the push. Since it is now immutable, jj automatically creates a new change on top of main and moves the working copy to it.

This is the hardest part for most people to grasp so let’s try another example where this time we push changes from the working copy.

I’ll add a simple README.md to our flake root:

❯ touch README.md


❯  jj st
Working copy changes:
A README.md
Working copy  (@) : v 5835b760 (no description set)
Parent commit (@-): n d54ab019 main | chore: nix flake update

Let’s give the change a description. Remember that jj commands default to the working copy, so jj desc is the same is jj desc -r @

❯  jj desc -m "chore: add README"
Working copy  (@) now at: v cdbb489f chore: add README
Parent commit (@-)      : n d54ab019 main | chore: nix flake update

Now rather than finalizing the current change with jj new, we will just point the main bookmark at the working copy @ and then push.

❯  jj bookmark set main -r @
Moved 1 bookmarks to v cdbb489f main* | chore: add README

  flake   HEAD [!]
❯  jj git push
Changes to push to origin:
  Move forward bookmark main from d54ab0197bef to cdbb489fecc0
  git: Enumerating objects: 4, done.
  git: Counting objects: 100% (4/4), done.
  git: Delta compression using up to 16 threads
  git: Compressing objects: 100% (2/2), done.
  git: Writing objects: 100% (3/3), 332 bytes | 332.00 KiB/s, done.
  git: Total 3 (delta 1), reused 0 (delta 0), pack-reused 0 (from 0)
  remote: Resolving deltas: 100% (1/1), completed with 1 local object.
  Warning: The working-copy commit in workspace 'default' became immutable, so a new commit has been created on top of it.
  Working copy  (@) now at: s 51306e16 (empty) (no description set)
  Parent commit (@-)      : v cdbb489f main | chore: add README

With jujutsu, most commands allow you to pass -r/--revision

What is the Jujutsu Working Copy

✔️ Click To Expand Working Copy Description

@ is a revset for “whichever commit the working copy reflects”. Think of @ as where you are currently making changes.

Every time you run a jj command, it examines the working copy (the files on disk) and takes a snapshot. –Steves JJ Tutorial

Let’s version control an existing nix development environment.

cd projects/rust

❯  ls
 flake.lock   flake.nix

jj git init --colocate
Initialized repo in "."
Hint: Running `git clean -xdf` will remove `.jj/`!

❯  jj log
@  t sayls8@proton.me 2026-03-15 08:49:21 e8fd7ee0
│  (no description set)
◆  z root() 00000000

Let’s give this change a description:

 jj desc -m "Initial commit of dev environment"
Working copy  (@) now at: t d671f27c Initial commit of dev environment
Parent commit (@-)      : z 00000000 (empty) (no description set)

❯  jj log
# The change ID stays the same, but the commit ID changes
@  t sayls8@proton.me 2026-03-15 09:04:17 d671f27c
│  Initial commit of dev environment
◆  z root() 00000000

Ok, I’m done with that change. Let’s start a new one, based off of t:

jj new
Working copy  (@) now at: q a3f5afe8 (empty) (no description set)
Parent commit (@-)      : t d671f27c Initial commit of dev environment

jj log
@  q sayls8@proton.me 2026-03-15 09:10:46 a3f5afe8
│  (empty) (no description set)
○  t sayls8@proton.me 2026-03-15 09:04:17 d671f27c
│  Initial commit of dev environment
◆  z root() 00000000

Since the repo wasn’t an existing git repo there are no existing branches (bookmarks). To share our work we’ll want to create a branch:

Above is a repo that was just created with jj git init --colocate. Notice that there is already 2 changes with change IDs t & z and 2 commits with identifiers e8fd7ee0 & 00000000.

Every jj repo has a root commit with zzzzzzzz 00000000 identifiers. The diamond ◆` represents an immutable, protected revision. This is the foundation of the repo. Jujutsu created a second change based on top of the empty root commit.

The working copy in Jujutsu is an actual commit that represents the current state of the files you’re working on. Unlike Git, where the working copy is separate from commits and changes must be explicitly staged and committed, in JJ the working copy is a live commit that automatically records changes as you modify files.

Adding or removing files in the working copy implicitly tracks or untracks them without needing explicit commands like git add

The working copy commit acts as a snapshot of your current workspace. When you run commands, Jujutsu first syncs the filesystem changes into this commit, then performs the requested operation, and finally updates the working copy if needed

To finalize your current changes and start a new set of changes, you use the jj new command, which creates a new working-copy commit on top of the current one. This replaces the traditional Git workflow of staging and committing changes separately.

Conflicts in the working copy are represented by inserting conflict markers directly into the files. Jujutsu tracks the conflicting parts and can reconstruct the conflict state from these markers. You resolve conflicts by editing these markers and then committing the resolution in the working copy

This means that you don’t need to worry about making a change, running git add ., running git commit -m "commit message" because it’s already done for you. This is handy with flakes by preventing a “dirty working tree” and can instantly be rebuilt after making a change.

Example JJ Module

✔️ Click to Expand JJ home-manager module example

For lazygit fans, Nixpkgs has lazyjj. I’ve seen that it’s recommended to use jj with meld. I’ll share my jj.nix here for an example:
I got a lot of the aliases and such from the zerowidth post, this has been a game changer:

{
  lib,
  config,
  pkgs,
  # userVars ? {},
  #
  #
  #
  ...
}: let
  cfg = config.custom.jj;
in {
  options.custom.jj = {
    enable = lib.mkOption {
      type = lib.types.bool;
      default = true;
      description = "Enable the Jujutsu (jj) module";
    };

    userName = lib.mkOption {
      type = lib.types.nullOr lib.types.str;
      default = "sayls8";
      description = "Jujutsu user name";
    };

    userEmail = lib.mkOption {
      type = lib.types.nullOr lib.types.str;
      default = "sayls8@proton.me";
      description = "Jujutsu user email";
    };

    packages = lib.mkOption {
      type = lib.types.listOf lib.types.package;
      default = with pkgs; [lazyjj meld];
      description = "Additional Jujutsu-related packages to install";
    };

    settings = lib.mkOption {
      type = lib.types.attrs;
      default = {
        ui = {
          # default-command = "log-recent";
          default-command = ["status" "--no-pager"];
          diff-editor = "gitpatch";
          # diff-editor = ["nvim" "-c" "DiffEditor" "$left" "$right" "$output"];
          # diff-formatter = ["meld" "$left" "$right"];
          merge-editor = ":builtin";
          conflict-marker-style = "diff";
        };
        git = {
          # remove the need for `--allow-new` when pushing new bookmarks
          auto-local-bookmark = true;
          push-new-bookmarks = true;
        };
        revset-aliases = {
          "closest_bookmark(to)" = "heads(::to & bookmarks())";
          "immutable_heads()" = "builtin_immutable_heads() | remote_bookmarks()";
          # The following command is incorrect, TODO
          # "default()" = "coalesce(trunk(),root())::present(@) | ancestors(visible_heads() & recent(), 2)";
          "recent()" = "committer_date(after:'1 month ago')";
          trunk = "main@origin";
        };
        template-aliases = {
          "format_short_change_id(id)" = "id.shortest()";
        };
        merge-tools.gitpatch = {
          program = "sh";
          edit-args = [
            "-c"
            ''
              set -eu
              rm -f "$right/JJ-INSTRUCTIONS"
              git -C "$left" init -q
              git -C "$left" add -A
              git -C "$left" commit -q -m baseline --allow-empty
              mv "$left/.git" "$right"
              git -C "$right" add --intent-to-add -A
              git -C "$right" add -p
              git -C "$right" diff-index --quiet --cached HEAD && { echo "No changes done, aborting split."; exit 1; }
              git -C "$right" commit -q -m split
              git -C "$right" restore . # undo changes in modified files
              git -C "$right" reset .   # undo --intent-to-add
              git -C "$right" clean -q -df # remove untracked files
            ''
          ];
        };
        aliases = {
          c = ["commit"];
          ci = ["commit" "--interactive"];
          e = ["edit"];
          i = ["git" "init" "--colocate"];
          tug = ["bookmark" "move" "--from" "closest_bookmark(@-)" "--to" "@-"];
          log-recent = ["log" "-r" "default() & recent()"];
          nb = ["bookmark" "create" "-r" "@-"]; # new bookmark
          upmain = ["bookmark" "set" "main"];
          squash-desc = ["squash" "::@" "-d" "@"];
          rebase-main = ["rebase" "-d" "main"];
          amend = ["describe" "-m"];
          pushall = ["git" "push" "--all"];
          push = ["git" "push" "--allow-new"];
          pull = ["git" "fetch"];
          dmain = ["diff" "-r" "main"];
          l = ["log" "-T" "builtin_log_compact"];
          lf = ["log" "-r" "all()"];
          r = ["rebase"];
          s = ["squash"];
          si = ["squash" "--interactive"];
        };
        revsets = {
          # log = "main@origin";
          # log = "master@origin";
        };
      };
      description = "Jujutsu configuration settings";
    };
  };

  config = lib.mkIf cfg.enable {
    home.packages = cfg.packages;

    programs.jujutsu = {
      enable = true;
      settings = lib.mergeAttrs cfg.settings {
        user = {
          name = cfg.userName;
          email = cfg.userEmail;
        };
      };
    };
  };
}

In my home.nix I have this to enable it:

custom = {
    jj = {
        enable = true;
        userName = "sayls8";
        userEmail = "sayls8@proton.me";
        packages = "";
    };
};

The custom.jj module allows me to override the username, email, packages, and whether jj is enabled from a single, centralized place within my Nix configuration. So only if jj is enabled, lazyjj and meld will be installed.

With the above gitpatch setup, say you did more work than you want to commit which is common with jj since it automatically tracks everything. I can now run:

jj commit -i

And an interactive diff will come up allowing you to choose what to include in the current commit. This also works for jj split -i and jj squash -i.

Example, using jj commit -i:

You can also use the jj tug command to make pushing to a remote more straightforward. Since JJ’s bookmarks don’t automatically move as they do with Git, you can use jj tug after you’ve made a few commits to move the bookmark that is closest to the parent commit of your current position to your current commit:

jj tug
jj git push

The tug alias works for both the squash and edit workflows. After running jj tug, jj git push should work. If you get an error saying no bookmarks to move, you can run jj new and then run jj tug, this happens when the bookmark is already at the parent commit.

# jj.nix
mb = ["bookmark" "set" "-r" "@"];

Another option would be to run jj mb main before running jj git push in this situation, but you will have to describe the commit first.

Issues I’ve Noticed

I have run into a few issues, such as every flake command reloading every single input every time. What I mean by this is what you see when you run a flake command for the first time, it adds all of your flakes inputs. I believe the fix for this is deleting and regenerating your flake.lock. The same thing can happen when you move your flake from one location to another.

JJ doesn’t seem to automatically track completely new files, running git add /file/path.nix enables JJ to start tracking the new file.

That said, I recommend doing just that after running something like jj git init --colocate. Delete your flake.lock and run nix flake update, nix flake lock --recreate-lock-file still works but is being depreciated.

Sometimes the auto staging doesn’t pick up the changes in your configuration so rebuilding changes nothing, this has been more rare but happens occasionally.

One of the most fundamental differences between Jujutsu and Git is how pushing works. If you’re coming from Git, it’s important to understand this shift so you don’t get tripped up by “nothing happened” warnings or missing changes on your remote.

In Git, you’re always “on” a branch (e.g., main).
When you make a commit, the branch pointer automatically moves forward.
git push pushes the current branch’s new commits to the remote.
If you forget to switch branches, you might accidentally push to the wrong place, but you rarely have to think about “moving” the branch pointer yourself.

The JJ Push Model

JJ has no concept of a “currrent branch”
Bookmarks do not move automatically. When you make a new commit, the bookmark (e.g., main) stays where it was. You must explicitly move it to your new commit with jj bookmark set main (or create a new one).
JJ only pushes commits that are referenced by bookmarks. If your latest work isn’t pointed to by a bookmark, jj git push will do nothing and warn you. This is to prevent accidental pushes and gives you more control over what gets shared.

Typical JJ Push Workflow

Check out where your working copy and Parent commit are, you will notice that jj highlights the minimal amount of characters needed to reference this change:

jj st
Working copy changes:
M README.md
Working copy  (@) : mnkrokmt 7f0558f8 say hello and goodbye
Parent commit (@-): ywyvxrts 986d16f5 main | test3

Being more explicit about your commands ensures both you and jj know where everything should go. (i.e. jj desc @ -m explicitly describes @, the working copy.) This will save you some headaches.

Our new change, the Working copy is now built off of main. The working copy will always be (@).

Make some changes

jj st
Working copy changes:
A dev/flake.lock
A dev/flake.nix
Working copy  (@) : kxwrsmmu 42b011cd Add a devShell
Parent commit (@-): ywyvxrts 986d16f5 main | test3

Now I’m done, and since we built this change on top of main the following command will tell jj we know what we want to push:

jj bookmark set main
jj git push

If you forget to move a bookmark, JJ will warn you and nothing will be pushed. This is a safety feature, not a bug. That’s what the mb alias does, moves the bookmark to the working copy.

# home-manager alias (move bookmark)
mb = ["bookmark" "set" "-r" "@"];

If you really have problems, jj git push --change @ explicitly pushes the working copy.

This is a bit different than Git and takes some getting used to but you don’t need to move the bookmark after every commit, just when you want to push. I know I’ve made the mistake of pushing to the wrong branch before this should prevent that.

Here’s an example of using JJ in an existing Git repo

Say I have my configuration flake in the ~/flakes/ directory that is an existing Git repository. To use JJ as the front-end I could do something like:

cd ~/flakes
jj git init --colocate
Done importing changes from the underlying Git repo.
Setting the revset alias `trunk()` to `main@origin`
Initialized repo in "."

By default, JJ defines trunk() as the main development branch of your remote repository. This is usually set to main@origin, but could be named something else. This means that whenever you use trunk() in JJ commands, it will resolve to the latest commit on main@origin. This makes it easier to refer to the main branch in scripts and commands without hardcoding the branch name.

Bookmarks in jj are named pointers to specific revisions, similar to branches in Git. When you first run jj git init --colocate in a git repo, you will likely get a Hint saying “Run the following command to keep local bookmarks updated on future pulls”.:

jj bookmark list
track main@origin

jj st
The working copy has no changes.
Working copy  (@) : qzxomtxq 925eca75 (empty) (no description set)
Parent commit (@-): qnpnrklz bf291074 main | notes

This shows that running jj git init --colocate automatically started tracking main in this case. If it doesn’t, use jj bookmark track main@origin.

I’ll create a simple change in the README.md:

jj st
Working copy changes:
M README.md
Working copy  (@) : qzxomtxq b963dff0 (no description set)
Parent commit (@-): qnpnrklz bf291074 main | notes

We can see that the working copy now contains a modified file M README.md and has no description set. Lets give it a description before pushing to github.

jj desc @ -m "Added to README"
jj bookmark set main -r @
Moved 1 bookmarks to pxwnopqo 1e6e08a2 main* | Added to README

jj bookmark set main -r @ moves the main bookmark to the current revision (the working copy), which is the explicit, recommended way to update bookmarks in JJ. Without this step, your bookmark will continue to point at the old commit, not your latest work. This is a major difference from Git.

And finally push to GitHub:

jj git push
Changes to push to origin:
  Move forward bookmark main from bf291074125e to e2a75e45237b
remote: Resolving deltas: 100% (1/1), completed with 1 local object.
Warning: The working-copy commit in workspace 'default' became immutable, so a new commit has been created on top of it.
Working copy  (@) now at: pxwnopqo 8311444b (empty) (no description set)
Parent commit (@-)      : qzxomtxq e2a75e45 main | Added to README

Create a Repo without an existing Git Repo

Or to do this in a directory that isn’t already a git repo you can do something like:

cargo new hello-world --vcs=none
cd hello-world
jj git init
Initialized repo in "."

JJ and Git Side by Side

Or for example, with Git if you wanted to move to a different branch before running nix flake update to see if it introduced errors before merging with your main branch, you could do something like:

git checkout -b update-test

nix flake update

sudo nixos-rebuild test --flake .

If you’re satisfied you can merge:

git checkout main
git add . # Stage the change
git commit -m "update"
git merge update-test
git branch -D update-test
sudo nixos-rebuild switch --flake .

With JJ a similar workflow could be:

Run jj st to see what you have:

jj st
The working copy has no changes.
Working copy  (@) : ttkstzzn 3f55c42c (empty) (no description set)
Parent commit (@-): wppknozq e3558ef5 main@origin | jj diff

If you don’t have a description set for the working copy set it now.

jj desc @ -m "enable vim"
jj st
The working copy has no changes.
Working copy  (@) : ttkstzzn 63fda123 (empty) enable vim
Parent commit (@-): wppknozq e3558ef5 main@origin | jj diff

Start from the working copy (which is mutable). The working copy in JJ is itself a commit that you can edit and squash changes into. Since main is immutable, you can create your new change by working on top of the working copy commit.

Create a new change off of the working copy:

jj new @

Make your edits:

jj st
Working copy changes:
M home/editors/vim.nix
Working copy  (@) : qrsxltmt 494b5f18 (no description set)
Parent commit (@-): wytnnnto a07e775c (empty) enable vim

Squash your changes into the new change:

jj squash
The working copy has no changes.
Working copy  (@) : tmlwppnu ba06bb99 (empty) (no description set)
Parent commit (@-): wytnnnto 52928ed9 enable vim

This moves your working copy changes into the new commit you just created.

Describe the new change, this might feel weird but the jj squash command created a new commit that you have to describe again:

jj desc @ -m "Enabled Vim"
Working copy  (@) : tmlwppnu 5c1569c3 (empty) Enabled Vim
Parent commit (@-): wytnnnto 52928ed9 enable vim

Set the bookmark to the Parent commit that was squashed into:

jj bookmark set wyt

Finally Push to the remote repository:

jj git push --allow-new
Changes to push to origin:
  Add bookmark wyt to 5c1569c35b22
remote: Resolving deltas: 100% (4/4), completed with 4 local objects.
remote:
remote: Create a pull request for 'wyt' on GitHub by visiting:
remote:      https://github.com/sayls8/flake/pull/new/wyt
remote:

This command does the following:

Uploads your bookmark and the associated commit to the remote repository (e.g., GitHub).
If the bookmark is new (not present on the remote), --allow-new tells JJ it’s okay to create it remotely.
After pushing, GitHub (or your code host) will usually suggest creating a pull request for your new branch/bookmark, allowing you or your collaborators to review and merge the change into main.

Merging your Change into main

Option 1. Go to the URL suggested in the output, visit in this case:

https://github.com/sayls8/flake/pull/new/wyt

Click Create PR
Click Merge PR if it shows it can merge cleanly.

Option 2.

Switch to main (if not already there):

jj bookmark set main

Create a new change that combines the new change with main:

jj new tml wyt -m "Merge: enable vim"

This creates a new commit with both tml and wyt as parents, which is how JJ handles merges (since jj merge depreciated). JJ merges are additive and history-preserving by design especially for folks used to Git’s fast-forward and squash options.

Summary

With jj you’re creating a new commit rather than a new branch.
Amending vs. Squashing: Git’s git commit --amend updates the last commit. jj squash combines the current commit with its parent, effectively doing the same thing in terms of history.
Merging: Git’s merge command is explicit. In jj, the concept is similar, but since there’s no branch, you’re “merging” by moving your working commit to include these changes.
No need to delete branches: Since there are no branches in jj, there’s no equivalent to git branch -D to clean up. Instead commits that are no longer needed can be “abandoned” with jj abandon if you want to clean up your commit graph.
jj describe without a flag just opens $EDITOR where you can write your commit message save and exit.
In git, we finish a set of changes to our code by committing, but in jj we start new work by creating a change, and then make changes to our code. It’s more useful to write an initial description of your intended changes, and then refine it as you work, than it is creating a commit message after the fact.
I have heard that jj can struggle with big repositories such as Nixpkgs and have noticed some issues here and there when using with NixOS. I’m hoping that as the project matures, it gets better on this front.

The 2 main JJ Workflows

The Squash Workflow

This workflow is the most similar to Git and Git’s index.

The workflow:

Describe the work we want to do with jj desc -m "message"
We create a new empty change on top of that one with jj new
When we are done with a feature, we run jj squash to move the changes from @ into the change we described in step 1. @ is where your working copy is positioned currently.

For example, let’s say we just ran jj git init --colocate in our configuration Flake directory making it a jj repo as well using git for backend.

cd flake
jj git init --colocate
jj log
@  lnmmxwko sayls8@proton.me 2025-06-27 10:14:57 1eac6aa0
│  (empty) (no description set)
○  qnknltto sayls8@proton.me 2025-06-27 09:04:08 git_head() 5358483a
│  (empty) jj

The above log output shows that running jj git init creates an empty working commit (@) on top of the git_head()

jj desc -m "Switch from nixVim to NVF"
jj new  # Create a new empty change
jj log
@  nmnmznmm sayls8@proton.me 2025-06-27 10:16:30 52dd7ee0
│  (empty) (no description set)
○  lnmmxwko sayls8@proton.me 2025-06-27 10:16:24 git_head() 3e8f9f3a
│  (empty) Switch from nixVim to NVF
○  qnknltto sayls8@proton.me 2025-06-27 09:04:08 5358483a
│  (empty) jj

The above log shows that running jj desc changes the current (@) commits description, and then jj new creates a new empty commit on top of it, moving (@) to this new empty commit.

The “Switch from nixVim to NVF” commit is now the parent of (@).

Now, we’d make the necessary changes and to add them to the commit we just described in the previous steps.

The changes are automatically “staged” so theres no need to git add them, so we just make the changes and squash them.

jj squash  # Squash the commit into its parent commit (i.e., our named commit)
jj log
@  zsxsolsq sayls8@proton.me 2025-06-27 10:18:01 2c35d83f
│  (empty) (no description set)
○  lnmmxwko sayls8@proton.me 2025-06-27 10:18:01 git_head() 485eaee9
│  (empty) Switch from nixVim to NVF

This shows jj squashes effect, it merges the changes from the current (@) commit into its parent. The (@) then moves to this modified parent, and a new empty commit is created on top, ready for the next set of changes.

sudo nixos-rebuild switch --flake .

We’re still in the nameless commit and can either continue working or run jj desc -m "" again describing our new change, then jj new and jj squash it’s pretty simple. The nameless commit is used as an adhoc staging area.

When you are ready to push, it’s important to know where your working copy currently is and if it’s attached to a bookmark. It’s common for jj new to detach the head, all you have to do is tell JJ which branch to attach to, then push:

jj st
Working copy changes:
M hosts/magic/configuration.nix
M hosts/magic/container.nix
Working copy  (@) : youptvvn 988e6fc9 (no description set)
Parent commit (@-): qlwqromx 4bb754fa mdbook container

The above output means that the working copy has modifications (M) in two files. And these changes are not yet committed.

jj bookmark set main
jj git push

The Edit Workflow

This workflow adds a few new commands jj edit, and jj next.

Here’s the workflow:

Create a new change to work on the new feature with jj new
If everything works exactly as planned, we’re done.
If we realize we want to break this big change up into multiple smaller ones, we do it by making a new change before the current one, swapping to it, and making the necessary change.
Lastly, we go back to the main change.

The squash workflow leaves @ at an empty undescribed change, with this workflow, @ will often be on the existing change.

If @ wasn’t at an empty change, we would start this workflow with:

jj new -m "Switch from NVF to nixVim"

since our @ is already at an empty change, we’ll just describe it and get started:

For this example, lets say we want to revert back to nixVim:

jj desc -m "Switch from NVF to nixVim"
jj log
@  zsxsolsq sayls8@proton.me 2025-06-27 10:18:47 606abaa7
│  (empty) Switch from NVF to nixVim
○  lnmmxwko sayls8@proton.me 2025-06-27 10:18:01 git_head() 485eaee9
│  (empty) Switch from nixVim to NVF
○  qnknltto sayls8@proton.me 2025-06-27 09:04:08 5358483a
│  (empty) jj

Again, this shows jj desc renaming the current empty @ commit.

We make the changes, and it’s pretty straightforward so we’re done, every change is automatically staged so we can just run sudo nixos-rebuild switch --flake . now to apply the changes.

If we wanted to make more changes that aren’t described we can use jj new -B which is similar to git add -a.

jj new -B @ -m "Adding LSP to nixVim"
Rebased 1 descendant commits
Working copy  (@) now at: lpnxxxpo bf929946 (empty) Adding LSP to nixVim
Parent commit (@-)      : lnmmxwko 485eaee9 (empty) Switch from nixVim to NVF

The -B tells jj to create the new change before the current one and it creates a rebase. We created a change before the one we’re on, it automatically rebased our original change. This operation will always succeed with jj, we will have our working copy at the commit we’ve just inserted.

You can see below that @ moved down one commit:

jj log
○  zsxsolsq sayls8@proton.me 2025-06-27 10:22:03 ad0713b6
│  (empty) Switch from NVF to nixVim
@  lpnxxxpo sayls8@proton.me 2025-06-27 10:22:03 bf929946
│  (empty) Adding LSP to nixVim
○  lnmmxwko sayls8@proton.me 2025-06-27 10:18:01 git_head() 485eaee9
│  (empty) Switch from nixVim to NVF
○  qnknltto sayls8@proton.me 2025-06-27 09:04:08 5358483a
│  (empty) jj
○  qnknltto sayls8@proton.me 2025-06-27 09:04:08 git_head()

The “Adding LSP to nixVim” commit is directly above “Switch from nixVim to NVF” (the old git_head())

The “Switch from NVF to nixVim” commit (which was your @ before jj new -B) is now above “Adding LSP to nixVim” in the log output, meaning “Adding LSP to nixVim” is its new parent.

@ has moved to “Adding LSP to nixVim”

jj log example output

Operation Log and Undo

JJ records every operation (commits, merges, rebases, etc.) in an operation log. You can view and undo previous operations, making it easy to recover from mistakes, a feature not present in Git’s core CLI

jj op log
@  fbf6e626df22 jr@magic 15 minutes ago, lasted 9 milliseconds
│  new empty commit
│  args: jj new -B @ -m 'Adding LSP to nixVim'
○  bde40b7c17cf jr@magic 19 minutes ago, lasted 8 milliseconds
│  describe commit 2c35d83f75031dc582bf28b64d4af1c218177f90
│  args: jj desc -m 'Switch from NVF to nixVim'
○  3a2bfe1c0b0a jr@magic 19 minutes ago, lasted 8 milliseconds
│  squash commits into 3e8f9f3a6a58fef86906e16e9b4375afb43e73e3
│  args: jj squash
○  80abcb58dcb6 jr@magic 21 minutes ago, lasted 8 milliseconds
│  new empty commit
│  args: jj new
○  8c80314cbcd7 jr@magic 21 minutes ago, lasted 8 milliseconds
│  describe commit 1eac6aa0b88ba014785ee9c1c2ad6e2abc6206e9
│  args: jj desc -m 'Switch from nixVim to NVF'
○  44b5789cb4d1 jr@magic 22 minutes ago, lasted 6 milliseconds
│  track remote bookmark main@origin
│  args: jj bookmark track main@origin
○  dbefee04aa85 jr@magic 23 minutes ago, lasted 4 milliseconds
│  import git head
│  args: jj git init --git-repo .

jj op undo <operation-id>
# or
jj op restore <operation-id>

Conflict Resolution

In JJ, conflicts live inside commits and can be resolved at any time, not just during a merge. This makes rebasing and history editing safer and more flexible

JJ treats conflicts as first-class citizens: conflicts can exist inside commits, not just in the working directory. This means if a merge or rebase introduces a conflict, the conflicted state is saved in the commit itself, and you can resolve it at any time there’s no need to resolve conflicts immediately or use “--continue” commands as in Git

Here’s how it works:

When you check out or create a commit with conflicts, JJ materializes the conflicts as markers in your files (similar to Git’s conflict markers)

You can resolve conflicts by editing the files to remove the markers, or by using:

jj resolve

Revsets

Jujutsu Revsets

JJ includes a powerful query language for selecting commits. For example:

jj log -r "author(alice) & file(*.py)"

This command lists all commits by Alice that touch Python files.

Filesets

Jujutsu Filesets

Jujutsu supports a functional language for selecting a set of files. Expressions in this language are called “filesets” (the idea comes from Mercurial). The language consists of file patterns, operators, and functions. –JJ Docs

Summary

Jujutsu (jj) offers a streamlined, branchless, and undo-friendly approach to version control, fully compatible with Git but designed to be easier to use and reason about. Its workflows, operation log, and conflict handling provide a safer and more flexible environment for managing code changes, making it a compelling alternative for both new and experienced developers.

Resources

KVM

2025-12-06T00:00:00+00:00

Running NixOS in a VM with Maximum Isolation (Beginner Guide)

Click to Expand Table of Contents

Why This Setup?

Host secureblue = Fedora Atomic with SELinux enforcing, sVirt, Secure Boot, and hardened defaults.
Guest: NixOS in a VM → full declarative power, near zero risk to host.
Isolation: Mandatory Access Control (MAC) via SELinux + KVM + no direct hardware access.

NOTE: Secureblue enables the hardened_malloc by default which causes problems for many browsers and will cause screen flashing with Firefox and others within the VM. See:

secureblue standard_malloc

Step 1: Install secureblue (Hardened Host)

Download a secureblue image
Use Fedora Media Writer (Flatpak):

flatpak install flathub org.fedoraproject.MediaWriter

Flash the secureblue image & enable Secure Boot in UEFI before install. This is now possible with Fedora, when you boot into Fedora Media Writer (not Ventoy or Rufus), you will be allowed to enroll the secure boot key with secure boot pre-enabled.
On first boot:

ujust enroll-secureblue-secure-boot-key

Reboot -> Enroll key in MOK manager with password: secureblue

Post-install hardening See: post-install
Install virtualization stack:

ujust install-libvirt-packages

The above command enables qemu, libvirt, & virt-manager with SELinux labels.
Read the secureblue FAQ to learn the quirks of an atomic fedora image.

Secureblue recommends installing GUI apps with Flatpak, CLI apps with homebrew, and apps that require more system access to be layered with rpm-ostree. It takes some getting used to but is very stable.

secureblue how to install software

Create NixOS VM (via virt-manager)

Easiest way to get a working configuration IMO:

Download: NixOS Graphical ISO
Open virt-manager -> File -> New Virtual Machine

Select ISO
CPU: host-passthrough (optional, for performance)
Do some research to find the ideal Memory and Storage for your system.

Ensure SELinux is enabled (the default for secureblue) with: getenforce
Ensure sVirt is enabled (the default) with run0 ps -eZ | grep qemu.

run0 ps -eZ | grep qemu
# Output
system_u:system_r:svirt_t:s0:c383,c416 14793 ?   00:01:37 qemu-system-x86

Boot -> Follow graphical installer:

Enable LUKS
Create an admin user
Optionally skip desktop -> install your own after first boot.

The attack surface is reduced significantly when running NixOS within a hardened hosts VM. The VM operates on virtualized hardware, which is a powerful form of attack surface reduction.

Devices like your host’s Bluetooth adapter, Wi-Fi card, microphone, webcam, and USB ports are not directly exposed to the guest operating system. The VM only sees virtual versions of these devices. If an exploit targets a vulnerability in the Bluetooth stack within the VM, it compromises the VM environment, but it cannot typically reach and exploit the physical Bluetooth hardware on the host.

You can also choose not to pass through certain devices, like Bluetooth or webcam to the VM at all, effectively disabling that attack vector. Since your host likely already has these hardened features you may not need the additional functionality within the VM.

If something breaks, you have an option to rollback to the previous generation with rpm-ostree rollback. The previous generation will be applied on next reboot. You can also just reboot and choose the previous generation through the grub menu, this way it is temporary and will revert back on next reboot.

🔒 How Host MAC Secures the NixOS VM

The host uses a classic defense-in-depth model: the hardened outer layer (the host) is treated as the real security boundary, and it is designed to remain safe even if the inner layer (the NixOS guest) is fully compromised.

MAC confinement with SELinux and sVirt

On the secureblue host, sVirt automatically applies SELinux labels to all VM-related processes and resources.

QEMU process confinement: The QEMU process that runs the NixOS VM runs under a dedicated SELinux type, typically svirt_t. The host’s MAC policy tightly restricts what this process can access, so even a successful VM escape is still trapped inside a very limited sandbox rather than gaining normal host privileges.
Disk image protection: VM disk images are labeled (for example, virt_image_t), which prevents unrelated host processes from reading or modifying them and keeps the VM’s storage isolated from the rest of the system.

KVM and host hardening

KVM provides the hardware-assisted virtualization layer and forms a strong barrier between the guest and the host kernel. On top of that, the secureblue host is hardened with SELinux in enforcing mode, Secure Boot, a hardened kernel, and hardened_malloc by default. Together, these measures reduce the attack surface and help ensure the integrity of the platform that is actually running the VM.

Isolation and “zero host compromise”

The host and guest are deliberately decoupled from a security perspective. The assumption is that the NixOS VM can be misconfigured, vulnerable, or even fully compromised. If that happens, KVM plus the host MAC policy (SELinux + sVirt) are responsible for containing the damage. In other words, the security boundary is not the NixOS configuration inside the VM, but the hypervisor and the host’s mandatory access control rules that enforce strict isolation of the guest from the host.

Hardening the NixOS Guest is Still Worth It

Even with a hardened host and MAC confinement, treating the NixOS VM as “untrusted but hardened” adds another independent safety layer. The goal is to minimize what an attacker can do inside the guest, even if they never manage a breakout.

Minimize VM device exposure

Use snapshots aggressively: Take a snapshot right after a fresh install and initial configuration. That snapshot becomes your “known-good” state for testing risky software or malware, so you can revert and wipe out any changes afterward.
Avoid unnecessary passthrough: Only pass through hardware (USB, GPU, network interfaces, etc.) if the VM genuinely needs it. Every extra device is another potential attack surface.
Prefer simple virtual devices: Use virtio and other paravirtualized devices where possible, and avoid legacy or fully emulated devices unless there is a specific need.

Network isolation for guests

Keep networks virtual and segmented: Favor isolated virtual networks, VLANs, or internal-only networks over bridged physical interfaces, so VMs cannot talk to the host or each other unless you explicitly design for it.
Filter traffic tightly: Use libvirt nwfilter, firewall rules (nftables/iptables/firewalld), and similar tools to restrict VM-to-VM and VM-to-external traffic, especially for services exposed on multiple guests.
Be cautious with IPv6: Full IPv6 inside the VM usually implies bridged networking, which connects the VM more directly to the host’s LAN. That improves connectivity but reduces isolation, so enable it only if you truly need it.

Guest-side hardening measures

Harden the allocator: Enabling graphene-hardened or graphene-hardened-light inside the guest improves memory safety for many applications:

# configuration.nix
environment.memoryAllocator.provider = "graphene-hardened";
# OR for a more permissive and better performing allocator:
# environment.memoryAllocator.provider = "graphene-hardened-light";

Some software (notably certain browsers) can be finicky with hardened mallocs and may require rebuilding or alternatives; be prepared to switch to another browser or allocator profile when you hit incompatibilities.

Disable nonessential features: Turn off USB redirection/debugging, audio devices, and other “extras” you do not need in the VM. These often pull in complex subsystems that are rarely worth the extra attack surface for a security-focused guest.

For deeper NixOS-specific hardening, see: hardening NixOS

Nix Toolbox

⚠️ Warning: toolbx containers are integrated with the host system, don’t do things you wouldn’t do on your host. Toolbx containers are not fully isolated environments like VMs.

That said, they are a fast and convenient way to spin up a Nix development environment. Know the limitations and benefits, and when you need more isolation, just spin up a VM instead.

Secureblue enforces restrictive container image policies by default, blocking unsigned or unverified images from registries like GitHub Container Registry. This requires explicit trust configuration for each container source.

ujust set-container-userns on

Without this setting, containers will fail with OCI permission denied errors.

Allow the Nix-Toolbox Image

# For system-wide configuration (affects all users)
run0 podman image trust set -t accept ghcr.io/thrix/nix-toolbox

# For user-specific configuration (recommended for development)
podman image trust set -t accept ghcr.io/thrix/nix-toolbox

The -t accept flag allows images from this registry without requiring signature verification.

# Check that the policy has been updated correctly:
podman image trust show

Create the nix-toolbox container:

toolbox create --image ghcr.io/thrix/nix-toolbox:42

You will be prompted whether you want Home Manager installed or not as well.

Enter the toolbox:

toolbox enter nix-toolbox-42

You can then use nix and home-manager to setup a fully declarative dev-environment.

Real-world recovery example

Secureblue’s design and the underlying firmware safeguards also make certain failures recoverable. On a mini PC, running a firmware update command resulted in a boot error (“Something went seriously wrong, MOK is full”) and a forced shutdown. Resetting NVRAM by moving the jumper on the motherboard briefly, then restoring it to the original position, allowed the system to retrain and boot again, after which the Secure Boot key could be re-enrolled and the system returned to a known-good, secure state.

✔️ My Experience with Secureblue

Using secureblue as the host OS with NixOS in a VM has been surprisingly smooth for day‑to‑day work. Performance has been more than adequate for editing, development, and browsing, and every issue so far has been fixable with rollbacks or small config changes—no “nuke and reinstall” moments required.

Software installation and workflows

Flatpak takes a bit of relearning if you are used to installing everything with full root on a mutable distro. Tools like Flatseal help a lot: you can see exactly which permissions an app has, then selectively tighten them instead of blindly trusting defaults. On secureblue, running the ujust flatpak-permissions-lockdown helper gives you a very strict baseline, then you add back only what each app truly needs.

In practice, a hybrid approach has worked best. One editor runs as a Flatpak, and another is installed via rpm-ostree for tighter system integration and the “traditional” root behavior when needed. The same thing happened with yazi: to get the exact workflow wanted, it was easier to install it via rpm-ostree rather than poking so many holes in the Flatpak sandbox that most isolation benefits disappeared.

Toolbx also fits into this nicely. Putting Homebrew and Flatpak inside a toolbox lets more config be shared while keeping the host image clean. The general pattern on Silverblue/secureblue is: Flatpak for most GUI apps, toolbox (plus brew or distro packages) for CLI tooling, and only a small number of host‑layer rpm-ostree installs when deep integration is really warranted.

One quirk worth knowing about: on secureblue, /home is a symlink to /var/home. Most tools don’t care, but a few development workflows get confused by the indirection. In those cases, pointing the tool directly at /var/home/username instead of /home/username usually clears things up.

Graphics and drivers in the NixOS VM

For GPU and display, the safest approach has been to let secureblue own the hardware stack and keep the NixOS guest as simple as possible. Extra GPU drivers or compositor tweaks inside the VM tended to make things less stable, showing up as flicker, random freezes, or generally janky graphics because the guest was effectively fighting the host’s configuration. Sticking close to the defaults in the VM has consistently produced smoother and more predictable graphics behavior.

The main issue I’ve had is with the dns-selector occasionally causing networking problems. I configure global DNS with their ujust command and I’m assuming that updates were incompatible with my DNS setup. Running ujust dns-selector and pressing 1 (Reset to defaults), and a reboot typically fix the connection and within a few days the global DNS will work again.

Resources

Understanding the Helix Flake

2025-12-05T00:00:00+00:00

Chapter 4.4

✔️ Click to Expand Table of Contents

–helix-editor.com

Understanding the Helix Flake and Modifying its Behavior

As we’ve seen from previous examples, the helix editor repository includes a few .nix files including a flake.nix. Their flake uses a lot of idiomatic Nix code and advanced features. First I will break down their flake.nix and default.nix to understand why they do certain things. And finally, we will change the build to “debug” mode demonstrating how easily you can modify the behavior of a package defined within a Nix flake without changing the original source code or the upstream flake directly.

Let’s clone the Helix repository:

git clone https://github.com/helix-editor/helix.git
cd helix

When you enter the helix directory, direnv is setup for you already. All you would have to do is direnv allow and it will ask you a few questions then you are good to go. Looking at their .envrc it mentions “try to use flakes, if it fails use normal nix (i.e., shell.nix)”. If it’s successful you’ll see a long list of environment variables displayed.

Enter the Development Shell:

The Helix project’s flake.nix includes a devShells.default output, specifically designed for development.

nix develop

You’re now in a fully configured development environment:

When you run nix develop, Nix builds and drops you into a shell environment with all the dependencies specified in devShells.default. This means you don’t have to manually install or manage tools like Rust, Cargo, or Clang, it’s all handled declaratively through Nix.

You can now build and run the project using its standard tooling:

cargo check
cargo build
cargo run

Making Changes and Testing Them

Since you’re in a reproducible environment, you can confidently hack on the project without worrying about your system setup. Try modifying some code in helix and rebuilding with Cargo. The Nix shell ensures consistency for every contributor or device you work on.

Run Just the Binary

If you only want to run the compiled program without entering the shell, use the nix run command:

nix run

This builds and runs the default package defined by the flake. In the case of Helix, this launches the hx editor directly.

Build Without Running

To just build the project and get the path to the output binary:

nix build

You’ll find the compiled binary under ./result/bin.

Pinning and Reproducing

Because the project uses a flake, you can ensure full reproducibility by pinning the inputs. For example, you can clone with --recurse-submodules and copy the flake.lock to ensure you’re using the same dependency versions as upstream. This is great for debugging or sharing exact builds.

✅ Recap:

With flakes, projects like Helix provide everything you need for development and running in a single flake.nix. You can nix develop to get started hacking, nix run to quickly try it out, and nix build to produce binaries all without installing or polluting your system.

Understanding the Helix flake.nix

The helix flake is full of idiomatic Nix code and displays some of the more advanced things a flake can provide:

{
  description = "A post-modern text editor.";

  inputs = {
    nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
    rust-overlay = {
      url = "github:oxalica/rust-overlay";
      inputs.nixpkgs.follows = "nixpkgs";
    };
  };

  outputs = {
    self,
    nixpkgs,
    rust-overlay,
    ...
  }: let
    inherit (nixpkgs) lib;
    systems = [
      "x86_64-linux"
      "aarch64-linux"
      "x86_64-darwin"
      "aarch64-darwin"
    ];
    eachSystem = lib.genAttrs systems;
    pkgsFor = eachSystem (system:
      import nixpkgs {
        localSystem.system = system;
        overlays = [(import rust-overlay) self.overlays.helix];
      });
    gitRev = self.rev or self.dirtyRev or null;
  in {
    packages = eachSystem (system: {
      inherit (pkgsFor.${system}) helix;
      /*
      The default Helix build. Uses the latest stable Rust toolchain, and unstable
      nixpkgs.

      The build inputs can be overridden with the following:

      packages.${system}.default.override { rustPlatform = newPlatform; };

      Overriding a derivation attribute can be done as well:

      packages.${system}.default.overrideAttrs { buildType = "debug"; };
      */
      default = self.packages.${system}.helix;
    });
    checks =
      lib.mapAttrs (system: pkgs: let
        # Get Helix's MSRV toolchain to build with by default.
        msrvToolchain = pkgs.pkgsBuildHost.rust-bin.fromRustupToolchainFile ./rust-toolchain.toml;
        msrvPlatform = pkgs.makeRustPlatform {
          cargo = msrvToolchain;
          rustc = msrvToolchain;
        };
      in {
        helix = self.packages.${system}.helix.override {
          rustPlatform = msrvPlatform;
        };
      })
      pkgsFor;

    # Devshell behavior is preserved.
    devShells =
      lib.mapAttrs (system: pkgs: {
        default = let
          commonRustFlagsEnv = "-C link-arg=-fuse-ld=lld -C target-cpu=native --cfg tokio_unstable";
          platformRustFlagsEnv = lib.optionalString pkgs.stdenv.isLinux "-Clink-arg=-Wl,--no-rosegment";
        in
          pkgs.mkShell {
            inputsFrom = [self.checks.${system}.helix];
            nativeBuildInputs = with pkgs;
              [
                lld
                cargo-flamegraph
                rust-bin.nightly.latest.rust-analyzer
              ]
              ++ (lib.optional (stdenv.isx86_64 && stdenv.isLinux) cargo-tarpaulin)
              ++ (lib.optional stdenv.isLinux lldb)
              ++ (lib.optional stdenv.isDarwin darwin.apple_sdk.frameworks.CoreFoundation);
            shellHook = ''
              export RUST_BACKTRACE="1"
              export RUSTFLAGS="''${RUSTFLAGS:-""} ${commonRustFlagsEnv} ${platformRustFlagsEnv}"
            '';
          };
      })
      pkgsFor;

    overlays = {
      helix = final: prev: {
        helix = final.callPackage ./default.nix {inherit gitRev;};
      };

      default = self.overlays.helix;
    };
  };
  nixConfig = {
    extra-substituters = ["https://helix.cachix.org"];
    extra-trusted-public-keys = ["helix.cachix.org-1:ejp9KQpR1FBI2onstMQ34yogDm4OgU2ru6lIwPvuCVs="];
  };
}

Top-Level Metadata:

{
  description = "A post-modern text editor.";
}

This sets a human-readable description for the flake.

Inputs

inputs = {
  nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
  rust-overlay = {
    url = "github:oxalica/rust-overlay";
    inputs.nixpkgs.follows = "nixpkgs";
  };
};

nixpkgs: Uses the nixos-unstable branch of the Nixpkgs repository.
rust-overlay: follows the same nixpkgs, ensuring compatibility between inputs.

Outputs Function:

outputs = { self, nixpkgs, rust-overlay, ... }:

This defines what this flake exports, including packages, devShells, etc.

Common Setup:

let
  inherit (nixpkgs) lib;
  systems = [ ... ];
  eachSystem = lib.genAttrs systems;

systems: A list of the supported systems
eachSystem: A Helper to map over all platforms.

pkgsFor = eachSystem (system:
  import nixpkgs {
    localSystem.system = system;
    overlays = [(import rust-overlay) self.overlays.helix];
  });

This imports nixpkgs for each system and applies overlays

📦 packages

packages = eachSystem (system: {
  inherit (pkgsFor.${system}) helix;
  default = self.packages.${system}.helix;
});

For each platform:
- Includes a helix package (defined in ./default.nix)
- Sets default to helix (used by nix build, nix run)

Let’s look at the helix default.nix:

{
  lib,
  rustPlatform,
  callPackage,
  runCommand,
  installShellFiles,
  git,
  gitRev ? null,
  grammarOverlays ? [],
  includeGrammarIf ? _: true,
}: let
  fs = lib.fileset;

  src = fs.difference (fs.gitTracked ./.) (fs.unions [
    ./.envrc
    ./rustfmt.toml
    ./screenshot.png
    ./book
    ./docs
    ./runtime
    ./flake.lock
    (fs.fileFilter (file: lib.strings.hasInfix ".git" file.name) ./.)
    (fs.fileFilter (file: file.hasExt "svg") ./.)
    (fs.fileFilter (file: file.hasExt "md") ./.)
    (fs.fileFilter (file: file.hasExt "nix") ./.)
  ]);

  # Next we actually need to build the grammars and the runtime directory
  # that they reside in. It is built by calling the derivation in the
  # grammars.nix file, then taking the runtime directory in the git repo
  # and hooking symlinks up to it.
  grammars = callPackage ./grammars.nix {inherit grammarOverlays includeGrammarIf;};
  runtimeDir = runCommand "helix-runtime" {} ''
    mkdir -p $out
    ln -s ${./runtime}/* $out
    rm -r $out/grammars
    ln -s ${grammars} $out/grammars
  '';
in
  rustPlatform.buildRustPackage (self: {
    cargoLock = {
      lockFile = ./Cargo.lock;
      # This is not allowed in nixpkgs but is very convenient here: it allows us to
      # avoid specifying `outputHashes` here for any git dependencies we might take
      # on temporarily.
      allowBuiltinFetchGit = true;
    };

    nativeBuildInputs = [
      installShellFiles
      git
    ];

    buildType = "release";

    name = with builtins; (fromTOML (readFile ./helix-term/Cargo.toml)).package.name;
    src = fs.toSource {
      root = ./.;
      fileset = src;
    };

    # Helix attempts to reach out to the network and get the grammars. Nix doesn't allow this.
    HELIX_DISABLE_AUTO_GRAMMAR_BUILD = "1";

    # So Helix knows what rev it is.
    HELIX_NIX_BUILD_REV = gitRev;

    doCheck = false;
    strictDeps = true;

    # Sets the Helix runtime dir to the grammars
    env.HELIX_DEFAULT_RUNTIME = "${runtimeDir}";

    # Get all the application stuff in the output directory.
    postInstall = ''
      mkdir -p $out/lib
      installShellCompletion ${./contrib/completion}/hx.{bash,fish,zsh}
      mkdir -p $out/share/{applications,icons/hicolor/{256x256,scalable}/apps}
      cp ${./contrib/Helix.desktop} $out/share/applications/Helix.desktop
      cp ${./logo.svg} $out/share/icons/hicolor/scalable/apps/helix.svg
      cp ${./contrib/helix.png} $out/share/icons/hicolor/256x256/apps/helix.png
    '';

    meta.mainProgram = "hx";
  })

Breaking Down `helix/default.nix`

✔️ Click to Expand `helix/default.nix` breakdown

This default.nix file is a Nix derivation that defines how to build the Helix editor itself. It’s designed to be called by the main flake.nix as part of its packages output.

Here’s a breakdown of its components:

Function Arguments:

{
  lib,
  rustPlatform,
  callPackage,
  runCommand,
  installShellFiles,
  git,
  gitRev ? null,
  grammarOverlays ? [],
  includeGrammarIf ? _: true,
}:

lib: The Nixpkgs lib (library) functions, essential for common operations like fileset and strings.

rustPlatform: A helper function from Nixpkgs specifically for building Rust projects. It provides a buildRustPackage function, which simplifies the process significantly.

callPackage: A Nixpkgs function used to instantiate a Nix expression (like grammars.nix) with its dependencies automatically supplied from the current Nix environment.

runCommand: A Nixpkgs primitive that creates a derivation by running a shell command. It’s used here to construct the runtimeDir.

installShellFiles: A utility from Nixpkgs for installing shell completion files.

git: The Git package, needed for determining the gitRev.

gitRev ? null: The Git revision of the Helix repository. It’s an optional argument, defaulting to null. This is passed in from the main flake.nix.

grammarOverlays ? []: An optional list of overlays for grammars, allowing customization.

includeGrammarIf ? _: true: An optional function to control which grammars are included.

Local Variables (let ... in)

let
  fs = lib.fileset;

  src = fs.difference (fs.gitTracked ./.) (fs.unions [
    ./.envrc
    ./rustfmt.toml
    ./screenshot.png
    ./book
    ./docs
    ./runtime
    ./flake.lock
    (fs.fileFilter (file: lib.strings.hasInfix ".git" file.name) ./.)
    (fs.fileFilter (file: file.hasExt "svg") ./.)
    (fs.fileFilter (file: file.hasExt "md") ./.)
    (fs.fileFilter (file: file.hasExt "nix") ./.)
  ]);

  grammars = callPackage ./grammars.nix { inherit grammarOverlays includeGrammarIf; };
  runtimeDir = runCommand "helix-runtime" {} ''
    mkdir -p $out
    ln -s ${./runtime}/* $out
    rm -r $out/grammars
    ln -s ${grammars} $out/grammars
  '';
in

fs = lib.fileset;: Aliases lib.fileset for convenient file set operations.

src: This is a crucial part. It defines the source files that will be used to build Helix by:

Taking all Git-tracked files in the current directory (fs.gitTracked ./.).
Excluding configuration files (e.g., .envrc, flake.lock), documentation (.md), images (.svg), and Nix files (.nix) using fs.difference and fs.unions. This ensures a clean build input, reducing Nix store size and avoiding unnecessary rebuilds.
grammars: Builds syntax grammars by calling grammars.nix, passing grammarOverlays (for customizing grammar builds) and includeGrammarIf (a filter for selecting grammars).
runtimeDir: Creates a runtime directory for Helix by:
- Symlinking the runtime directory from the source.
- Replacing the grammars subdirectory with a symlink to the grammars derivation, ensuring Helix uses Nix-managed grammars.

The Build Derivation (rustPlatform.buildRustPackage)

The core of this default.nix is the rustPlatform.buildRustPackage call, which is a specialized builder for Rust projects:

in
  rustPlatform.buildRustPackage (self: {
    cargoLock = {
      lockFile = ./Cargo.lock;
      # ... comments ...
      allowBuiltinFetchGit = true;
    };

cargoLock: Specifies how Cargo dependencies are handled.

lockFile = ./Cargo.lock; Points to the Cargo.lock file for reproducible builds.

allowBuiltinFetchGit = true: Allows Cargo to fetch Git dependencies directly from repositories specified in Cargo.lock. This is discouraged in Nixpkgs because it can break build reproducibility, but it’s used here for convenience during development, eliminating the need to manually specify outputHashes for Git dependencies.

nativeBuildInputs = [
      installShellFiles
      git
    ];

nativeBuildInputs: Are tools needed during the build process but not necessarily at runtime.

buildType = "release";

buildType: Specifies that Helix should be built in “release” mode (optimized).

name = with builtins; (fromTOML (readFile ./helix-term/Cargo.toml)).package.name;
    src = fs.toSource {
      root = ./.;
      fileset = src;
    };

name: Dynamically sets the package name by reading it from the Cargo.toml file.

src: Uses the src file set defined earlier as the source for the build.

# Helix attempts to reach out to the network and get the grammars. Nix doesn't allow this.
    HELIX_DISABLE_AUTO_GRAMMAR_BUILD = "1";

    # So Helix knows what rev it is.
    HELIX_NIX_BUILD_REV = gitRev;

Environment Variables: Sets environment variables that Helix uses.

HELIX_DISABLE_AUTO_GRAMMAR_BUILD = "1": Prevents Helix from downloading grammars during the build, as Nix’s sandboxed environment disallows network access. Instead, grammars are provided via the runtimeDir derivation.

HELIX_NIX_BUILD_REV = gitRev: Embeds the specified Git revision (or null if unspecified) into the Helix binary, allowing Helix to display its version or commit hash.

doCheck = false;
   strictDeps = true;

doCheck = false;: Skips running tests during the build. This is common for faster builds, especially in CI/CD, but tests are often run in a separate checks output (as seen in the flake.nix).

strictDeps = true;: Ensures that all dependencies are explicitly declared.

# Sets the Helix runtime dir to the grammars
env.HELIX_DEFAULT_RUNTIME = "${runtimeDir}";

# Sets the Helix runtime dir to the grammars
env.HELIX_DEFAULT_RUNTIME = "${runtimeDir}";

env.HELIX_DEFAULT_RUNTIME: Tells Helix where to find its runtime files (including the Nix-managed grammars).

# Get all the application stuff in the output directory.
postInstall = ''
  mkdir -p $out/lib
  installShellCompletion ${./contrib/completion}/hx.{bash,fish,zsh}
  mkdir -p $out/share/{applications,icons/hicolor/{256x256,scalable}/apps}
  cp ${./contrib/Helix.desktop} $out/share/applications/Helix.desktop
  cp ${./logo.svg} $out/share/icons/hicolor/scalable/apps/helix.svg
  cp ${./contrib/helix.png} $out/share/icons/hicolor/256x256/apps/helix.png
'';

postInstall: A shell script that runs after the main build is complete. This is used for installing additional files that are part of the Helix distribution but not directly built by Cargo.

Installs shell completion files (hx.bash, hx.fish, hx.zsh). This enables tab completion.

Installs desktop entry files (Helix.desktop) and icons (logo.svg, helix.png) for desktop integration for GUI environments.

    meta.mainProgram = "hx";

})

meta.mainProgram: Specifies the primary executable provided by this package, allowing nix run to automatically execute hx.

A lot going on in this derivation!

Making Actual Changes

Locate the packages output section. It looks like this:

packages = eachSystem (system: {
      inherit (pkgsFor.${system}) helix;
      /*
      The default Helix build. Uses the latest stable Rust toolchain, and unstable
      nixpkgs.

      The build inputs can be overridden with the following:

      packages.${system}.default.override { rustPlatform = newPlatform; };

      Overriding a derivation attribute can be done as well:

      packages.${system}.default.overrideAttrs { buildType = "debug"; };
      */
      default = self.packages.${system}.helix;
    });

Modify the default package. The comments actually tell us exactly how to do this. We want to use overrideAttrs to change the buildType

Change this line:

default = self.packages.${system}.helix;

To this:

default = self.packages.${system}.helix.overrideAttrs { buildType = "debug"; };

This tells Nix to take the standard Helix package definition and override one of its internal attributes (buildType) to “debug” instead of “release”.

Build the “Hacked” Helix:

nix build

Nix will now rebuild Helix, but this time, it will compile it in debug mode. You’ll likely notice the build takes a bit longer, and the resulting binary will be larger due to the included debugging symbols.

Run the Debug Binary:

./result/bin/hx

You’re now running your custom-built debug version of Helix! This is useful if you were, for example, attatching a debugger.

This is a simple yet powerful “hack” that demonstrates how easily you can modify the behavior of a package defined within a Nix flake without changing the original source code or the upstream flake directly. You’re simply telling Nix how you’d like your version of the package to be built.

Another way to Modify Behavior

Since we are already familiar with the structure and behavior of Helix’s flake.nix, we can leverage that understanding to create our own Nix flake. By analyzing how Helix organizes its inputs, outputs, and package definitions, we gain the confidence to modify and extend a flake’s functionality to suit our specific needs—whether that’s customizing builds, adding overlays, or integrating with home-manager.

Create a flake.nix in your own directory (outside the helix repo):

{
  description = "Customized Helix build with debug features";

  inputs = {
    helix.url = "github:helix-editor/helix";
    nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
    rust-overlay = {
      url = "github:oxalica/rust-overlay";
      inputs.nixpkgs.follows = "nixpkgs";
    };
  };
  outputs = {
    self,
    helix,
    nixpkgs,
    rust-overlay,
  }: let
    system = "x86_64-linux";
    pkgs = import nixpkgs {
      system = system;
      overlays = [rust-overlay.overlay.overlays.default];
    };
  in {
    packages.${system}.default = helix.packages.${system}.helix.overrideAttrs (old: {
      buildType = "debug";

      # Add additional cargo features
      cargoBuildFlags =
        (old.cargoBuildFlags or [])
        ++ [
          "--features"
          "tokio-console"
        ];

      # Inject custom RUSTFLAGS
      RUSTFLAGS = (old.RUSTFLAGS or "") + " -C debuginfo=2 -C opt-level=1";
    });
  };
}

Check it:

nix flake check
warning: creating lock file '"/home/jr/world/flake.lock"':
• Added input 'helix':
    'github:helix-editor/helix/8961ae1dc66633ea6c9f761896cb0d885ae078ed?narHash=sha256-f14perPUk%2BH15GyGRbg0Akqhn3rxFnc6Ez5onqpzu6A%3D' (2025-05-29)
• Added input 'helix/nixpkgs':
    'github:nixos/nixpkgs/5135c59491985879812717f4c9fea69604e7f26f?narHash=sha256-Vr3Qi346M%2B8CjedtbyUevIGDZW8LcA1fTG0ugPY/Hic%3D' (2025-02-26)
• Added input 'helix/rust-overlay':
    'github:oxalica/rust-overlay/d342e8b5fd88421ff982f383c853f0fc78a847ab?narHash=sha256-3SdPQrZoa4odlScFDUHd4CUPQ/R1gtH4Mq9u8CBiK8M%3D' (2025-02-27)
• Added input 'helix/rust-overlay/nixpkgs':
    follows 'helix/nixpkgs'
• Added input 'nixpkgs':
    'github:nixos/nixpkgs/96ec055edbe5ee227f28cdbc3f1ddf1df5965102?narHash=sha256-7doLyJBzCllvqX4gszYtmZUToxKvMUrg45EUWaUYmBg%3D' (2025-05-28)
• Added input 'rust-overlay':
    'github:oxalica/rust-overlay/405ef13a5b80a0a4d4fc87c83554423d80e5f929?narHash=sha256-k0nhPtkVDQkVJckRw6fGIeeDBktJf1BH0i8T48o7zkk%3D' (2025-05-30)
• Added input 'rust-overlay/nixpkgs':
    follows 'nixpkgs'

The nix flake check command will generate a flake.lock file if one doesn’t exist, and the warnings you see indicate that new inputs are being added and locked to specific versions for reproducibility. This is expected behavior for a new or modified flake.

Inspect the outputs:

nix flake show
path:/home/jr/world?lastModified=1748612128&narHash=sha256-WEYtptarRrrm0Jb/0PJ/b5VPqLkCk5iEenjbKYU4Xm8%3D
└───packages
    └───x86_64-linux
        └───default: package 'helix-term'

The └───packages line indicates that our flake exposes a top-level packages attribute.
└───x86_64-linux: System architecture specificity
└───default: package 'helix-term' Signifies that within the x86_64-linux packages, there’s a package named default. This is a special name that allows you to omit the package name when using commands like nix build.
package 'helix-term' This is the most direct confirmation of our “hack”. It tells us that our default package is helix-term. This confirms that our overrideAttrs in the packages.${system}.default section successfully targeted and modified the Helix editor package, which is internally named helix-term by the Helix flake.

What This Does:

overrideAttrs lets you change only parts of the derivation without rewriting everything.
buildType = "debug" enables debug builds.
cargoBuildFlags adds extra features passed to Cargo, e.g., --features tokio-console
RUSTFLAGS gives you even more control over compiler behavior, optimization levels, etc.

Run It:

nix run

Or drop into the dev shell:

nix develop

(assuming you also wire in a devShells output)

Adding the devShells output:

Since we already have the helix flake as an input to our own flake.nix we can now forward or extend Helix’s devShells like this:

outputs = { self, nixpkgs, helix, rust-overlay, ... }: {
  devShells = helix.devShells;
};

Or if you want to pick a specific system:

outputs = { self, nixpkgs, helix, rust-overlay ... }:
  let
    system = "x86_64-linux";
  in {
    devShells.${system} = helix.devShells.${system};
  };

Optional: Combine with your own devShell

You can also extend or merge it with your own shell like so:

outputs = { self, nixpkgs, helix, rust-overlay, ... }:
  let
    system = "x86_64-linux";
    pkgs = import nixpkgs { inherit system; };
  in {
    devShells.${system} = {
      default = pkgs.mkShell {
        name = "my-shell";
        inputsFrom = [ helix.devShells.${system}.default ];
        buildInputs = [ pkgs.git ];
      };
    };
  };

Cachix devour-flake

2025-12-05T00:00:00+00:00

Cachix and the devour-flake

✔️ Table of Contents

Using devour-flake to Cache All Your Flake Outputs to Cachix

When working with Nix flakes, it’s common to have many outputs: packages, apps, dev shells, NixOS or Darwin configurations, and more. Efficiently building and caching all these outputs can be challenging, especially in CI or when collaborating. This is where devour-flake and Cachix shine.

Why Use the devour-flake?

By default, building all outputs of a flake with nix build .#a .#b ... .#z can be slow and inefficient, as Nix will evaluate the flake multiple times, once for each output. devour-flake solves this by generating a “consumer” flake that depends on all outputs, allowing you to build everything in one go with a single evaluation

Installation

There quite a few ways to do this, choose a method of installation from the devour-flake repository and then continue with step 1.

Nix will only download binaries from binary caches if they are cryptographically signed with any of the keys listed in nix.settings.trusted-public-keys.

# This is the default
nix.settings.require-sigs = true;

Example:

nix.settings = {
  builders-use-substitutes = true;
  substituters = [
    "https://cache.nixos.org"
  ];
  trusted-public-keys = [
    "cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDShjY="
  ];
};

You can even build it without installing with the following command:

nix build github:srid/devour-flake \
  -L --no-link --print-out-paths \
  --override-input flake path/to/flake | cachix push <name>

nix-shell -p cachix

This will push all flake outputs to cachix if you have a valid authentication token and have created a cache already.

How to Use devour-flake with Cachix

Prerequisites

A Cachix cache: Create one on Cachix and generate a “Write + Read” auth token. You’ll click the cache you just created and select Settings, in the settings you’ll find Auth Tokens. When in the Auth Tokens section give your token a Description, Expiration date, and finally click Generate.

(Optional) Configure your token locally, copy your auth token for the following command:

cachix authtoken <YOUR_TOKEN>
# Use cachix cli for the following
cachix use your-cache-name

cachix use adds your substitutors and trusted-public-keys to your ~/.config/nix/nix.conf and creates one if it doesn’t exist.

Push All Flake Inputs to Cachix

Replace <mycache> with the name of the cache you just created.

nix flake archive --json \
  | jq -r '.path,(.inputs|to_entries[].value.path)' \
  | cachix push <mycache>

You should see output similar to the following:

Pushing 637 paths (2702 are already present) using zstd to cache sayls8 ⏳

✓ /nix/store/0aqvmjvhkar3j2f7zag2wjl4073apnvk-vimplugin-crates.nvim-2025-05-30 (734.65 KiB)
✓ /nix/store/02wm10zck7rb836kr0h3afjxl80866dp-X-Restart-Triggers-keyd (184.00 B)
✓ /nix/store/0asdaaax0lf1wa6m6lqqdvc8kp6qn3f6-dconf-cleanup (1008.00 B)
✓ /nix/store/09ki2jlh6sqbn01yw6n15h8d55ihxygf-helix-tree-sitter-mojo-3d7c53b8038f9ebbb57cd2e61296180aa5c1cf64 (601.37 KiB)
✓ /nix/store/0i2c29nldqvb9pnypvp3ika4i7fhc0ck-devour-output (312.00 B)
✓ /nix/store/0c0mwfb78xm862a7g4h9fhgzn55zppj6-helix-term (29.88 MiB)
✓ /nix/store/0fhdpb2qck1kbngq1dlc8lyqqadj2pb1-hyprcursor-0.1.12+date=2025-06-05_45fcc10-lib (487.30 KiB)
✓ /nix/store/0mfpi51bswgd91l8clqcz6mxy5k5zcd4-vimplugin-auto-pairs-2019-02-27 (40.60 KiB)
✓ /nix/store/0k2zq8y78vrhhkf658j6i45vz3y89v11-helix-tree-sitter-tcl-56ad1fa6a34ba800e5495d1025a9b0fda338d5b8 (110.25 KiB)
✓ /nix/store/0qxmahrw935136dbxkmvrg14fgnzi6bb-vimplugin-obsidian.nvim-2025-07-01 (493.02 KiB)
✓ /nix/store/0wjppqzcbnlf9srhr6k27pz403j3mg2j-hm-session-vars.sh (1.86 KiB)
✓ /nix/store/0z41071z33zg1zqyasccc3cfhxj389k0-helix-tree-sitter-swift-57c1c6d6ffa1c44b330182d41717e6fe37430704 (2.77 MiB)
✓ /nix/store/0n5f1x8lpc93zm81bxrfh6yccyngvrdl-unit-plymouth-read-write.service (1.19 KiB)
✓ /nix/store/0z8ac35n89lv2knzaj6kkp0cfxr6pmgc-hm_face.png (300.60 KiB)
✓ /nix/store/0zp5846pry5rknnvzz81zlvj4ghnkxp5-hyprutils-0.8.1+date=2025-07-07_a822973 (421.64 KiB)
✓ /nix/store/118ihgwjw6kp0528igns3pnvzbszljmg-unit-dbus.service (1.34 KiB)
✓ /nix/store/0pajdq9mfgkcdwbqp38j7d4clc9h9iik-hm_.mozillafirefoxdefault.keep (112.00 B)
✓ /nix/store/0nlvffvpx6s8mpd2rpnqb1bl5idd16yk-hm-dconf.ini (224.00 B)
✓ /nix/store/1fiqgqvi574rdckav0ikdh8brwdhvh69-vimplugin-alpha-nvim-2025-05-26 (69.38 KiB)
✓ /nix/store/1fqxw31p1llag0g7wg7izq22x5msz47r-vimplugin-persistence.nvim-2025-02-25 (37.74

❗ NOTE: The effectiveness of pushing the rest to cachix depend on your network speed. I actually noticed a slow down after pushing the nix/store. Pushing the nix/store is rarely necessary and can be very slow and bandwidth-intensive. Most users will only need to push relevant outputs.

Push the Entire /nix/store

nix path-info --all | cachix push <mycache>

Pushing shell environment

nix develop --profile dev-profile -c true
# then run
cachix push <mycache> dev-profile

For the Flake way of doing things you would create something like the following:

{
  config,
  lib,
  pkgs,
  ...
}: let
  cfg = config.custom.cachix;
in {
  options = {
    custom.cachix.enable = lib.mkEnableOption "Enable custom cachix configuration";
  };

  config = lib.mkIf cfg.enable {
    environment.systemPackages = with pkgs; [cachix];

    # to prevent garbage collection of outputs immediately after building
    nix.extraOptions = "gc-keep-outputs = true";
    nix.settings = {
      substituters = [
        "https://nix-community.cachix.org"
        "https://hyprland.cachix.org"
        "https://ghostty.cachix.org"
        "https://neovim-nightly.cachix.org"
        "https://yazi.cachix.org"
        "https://helix.cachix.org"
        "https://nushell-nightly.cachix.org"
        "https://wezterm.cachix.org"
        "https://sayls88.cachix.org"
        # "https://nixpkgs-wayland.cachix.org"
      ];
      trusted-public-keys = [
        "nix-community.cachix.org-1:mB9FSh9qf2dCimDSUo8Zy7bkq5CX+/rkCWyvRCYg3Fs="
        "hyprland.cachix.org-1:a7pgxzMz7+chwVL3/pzj6jIBMioiJM7ypFP8PwtkuGc="
        "ghostty.cachix.org-1:QB389yTa6gTyneehvqG58y0WnHjQOqgnA+wBnpWWxns="
        "neovim-nightly.cachix.org-1:feIoInHRevVEplgdZvQDjhp11kYASYCE2NGY9hNrwxY="
        "yazi.cachix.org-1:Dcdz63NZKfvUCbDGngQDAZq6kOroIrFoyO064uvLh8k="
        "helix.cachix.org-1:ejp9KQpR1FBI2onstMQ34yogDm4OgU2ru6lIwPvuCVs="
        "nushell-nightly.cachix.org-1:nLwXJzwwVmQ+fLKD6aH6rWDoTC73ry1ahMX9lU87nrc="
        "wezterm.cachix.org-1:kAbhjYUC9qvblTE+s7S+kl5XM1zVa4skO+E/1IDWdH0="
        "sayls88.cachix.org-1:LT8JnboX8mKhabC3Mj/ONHb5tyrjlnsdauQkD8Lu0us="
        # "nixpkgs-wayland.cachix.org-1:3lwxaILxMRkVhehr5StQprHdEo4IrE8sRho9R9HOLYA="
      ];
    };
  };
}

The sayls8 entries are my custom cache. To find your trusted key go to the cachix website, click on your cache and it is listed near the top.
I enable this with custom.cachix.enable = true; in my configuration.nix or equivalent.
Another option is to use the top-level nixConfig attribute for adding your substitutors and trusted-public-keys. You only need to choose 1 method FYI:

{
  description = "NixOS & Flake Config";

# the nixConfig here only affects the flake itself, not the system configuration!
  nixConfig = {
    experimental-features = [ "nix-command" "flakes" ];
    trusted-users = [ "ryan" ];

    substituters = [
      # replace official cache with a mirror located in China
      "https://mirrors.ustc.edu.cn/nix-channels/store"
      "https://cache.nixos.org"
    ];

    # nix community's cache server
    extra-substituters = [
      "https://nix-community.cachix.org"
      "https://nixpkgs-wayland.cachix.org"
    ];
    extra-trusted-public-keys = [
      "cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDShjY="
      "nix-community.cachix.org-1:mB9FSh9qf2dCimDSUo8Zy7bkq5CX+/rkCWyvRCYg3Fs="
      "nixpkgs-wayland.cachix.org-1:3lwxaILxMRkVhehr5StQprHdEo4IrE8sRho9R9HOLYA="
    ];
  };
# ... snip

❗️ WARNING: trusted-users is a list of users who are allowed to bypass many of Nix’s normal safety restrictions and change daemon-level settings. Keep trusted-users as small as possible (often just root and maybe your own user on a single-user box)

Building and Caching All Outputs

You can build and push all outputs of your flake to Cachix using the following command when in your flake directory:

nix build github:srid/devour-flake \
 -L --no-link --print-out-paths \
 --override-input flake . \
 | cachix push <your-cache-name>

Replace your-cache-name with your actual Cachix cache name.

This command will:
Use devour-flake to enumerate and build all outputs of your flake (including packages, devShells, NixOS configs, etc.)
Pipe the resulting store paths to cachix push, uploading them to your binary cache.

Example

Suppose your cache is named my-flake-cache:

nix build github:srid/devour-flake \
 -L --no-link --print-out-paths \
 --override-input flake . \
 | cachix push my-flake-cache

Integration in CI

This approach is particularly useful in CI pipelines, where you want to ensure all outputs are built and cached for collaborators and future builds. You can add the above command to your CI workflow, ensuring the Cachix auth token is provided as a secret

Advanced: Using as a Nix App

You can add devour-flake as an input to your flake for local development:

{
  inputs = {
    devour-flake.url = "github:srid/devour-flake";
    devour-flake.flake = false;
  };
}

And in your flake’s outputs, add an overlay that makes devour-flake available in your package set:

outputs = { self, nixpkgs, devour-flake, ... }@inputs: {
  overlays.default = final: prev: {
    devour-flake = import devour-flake { inherit (prev) pkgs; };
  };

  # Example: Add devour-flake to your devShell
  devShells.x86_64-linux.default = let
    pkgs = import nixpkgs {
      system = "x86_64-linux";
      overlays = [ self.overlays.default ];
    };
  in pkgs.mkShell {
    buildInputs = [ pkgs.devour-flake ];
  };
};

Use devour-flake in your devShell:

nix develop

You’ll have the devour-flake command available for local use, so you can quickly build and push all outputs as needed.

TIP: Alternatively, use devour-flake as an app:

apps.x86_64-linux.devour-flake = {
 type = "app";
 program = "${self.packages.x86_64-linux.devour-flake}/bin/devour-flake";
};

What Gets Built and Cached?

devour-flake detects and builds all standard outputs of a flake, including:

packages
apps
checks
devShells
nixosConfigurations.*
darwinConfigurations.*
home-manager configurations

This ensures that everything your flake produces is available in your Cachix cache for fast, reproducible builds.

References:

devour-flake documentation

Discourse Cachix for Flakes

Cachix docs: Flakes

Tweag Evaluation Caching

Scrive Caching

Whonix KVM on NixOS

2025-12-04T00:00:00+00:00

Whonix KVM on NixOS

✔️ Table of Contents

⚠️ WARNING: There is no general software that can guarantee absolute anonymity or security; perfect security is a myth. Security is a continuous process, not a one-time product. It also depends on time and resources: if an adversary has enough of either, eventual compromise is probable. However, by layering defenses and following best practices, we can make attacks costly and time-consuming, deterring all but highly targeted adversaries.

It is highly recommended to harden your Host Machine as Type 2 hypervisors are only as secure as their host. KVM is actually a type 1 hypervisor but relies on QEMU for emulation which is a Type 2 hypervisor. This actually makes it a sort of hybrid in between Type 1 and Type 2 but is in theory less secure than running a Xen hypervisor (Type 1) on bare-metal.

Whonix offers many benefits, including the convenience of running within your current operating system without needing to reboot or use a separate Tails USB. It provides similar strong anonymity protections by routing all traffic through Tor in isolated virtual machines. The Whonix documentation is transparent about its limitations, which helps build trust and confidence in its security model.

Whonix Compared to Tails
Tails is great but they add an add blocker to Tor that makes every Tails user unique from the rest of Tor Browser users reducing anonymity.

⚠️ Never rely solely on the Virtual Machine to protect you, if your host OS isn’t secure a Virtual Machine won’t protect you. If you have high threat model, you may want to choose a Host with better support for AppArmor and Selinux as they are highly limited on NixOS.

That being said, there is a lot you can do to harden NixOS…

Harden NixOS and set up GnuPG

A Few Things to Consider when using Whonix

No activity conducted inside Whonix-Workstation can cause IP/DNS leaks so long as Whonix-Gateway is left unchanged or only documented changes are made like configuring bridges, establishing onion services and running updates.
Whonix does not and does not claim to protect users against advanced adversaries such as nation state actors, if they target you, you will be infected! If used correctly, Whonix can provide partial protection against passive surveillance programs, it all depends on whether Tor can provide adequate protection or not, which is not clear at this time.
You shouldn’t use a VPN with Whonix and it is obvious that you’re using Tor because connections are made to known Tor Relays, which are publicly listed and identifiable.

⚠️It is impossible to Hide Tor use from the internet service provider (ISP). It has been concluded this goal is difficult beyond practicality. –Whonix Hide Tor from your ISP

Millions of people use Tor daily for wholly legitimate reasons, particularly to assert their privacy rights when faced with countless corporate / government network observers and censors.
True anonymity is very difficult to successfully pull off and not something that you can maintain for a long time.
- Whonix Tips for remaining Anonymous

🔑 Key Terms

Whonix is an operating system based on Debian base (Kicksecure Hardened) and the Tor network, which is designed for maximum anonymity and security. Whonix consists of two Debian based VMs, the Whonix-Gateway and Whonix-Workstation.

In this case NixOS is the Host Operating System, NixOS runs the KVM kernel module, libvirtd service, and QEMU virtualization service which together enable hosting VMs. It is recommended to harden the host before moving on.

Guests are the virtualized operating systems running inside the host’s virtual machines. In this case the Whonix VMs are the Guest Machines.

Whonix-Gateway the first of 2 VMs runs Tor processes and forces all traffic through the Tor network using iptables.

Whonix-Workstation the second VM, is responsible for running user applications such as the Tor Browser. The Whonix-Workstation is isolated from both the Whonix-Gateway and the Host OS, if an app misbehaves, it is contained within the isolated Whonix-Workstation. It is largely unaware of sensitive info and won’t leak unless an advanced adversary is able to break out of the VM.

The primary goal of Whonix is to be safer than Tor alone and that no one can find out the user’s IP, location, or de-anonymize the user. It offers full spectrum anti-tracking protection that is much safer than VPNs. Whonix provides this through security by isolation, no app is trusted.

Whonix Concept: Whonix is an Isolating Proxy with an additional Transparent Proxy, which can be optionally disabled. –Whonix Docs

Since Whonix is based on Kicksecure which is based on Debian stable, you can typically look up solutions in a Kicksecure, Debian, or Ubuntu forum.

The Whonix Team recommends KVM over VirtualBox for a number of reasons:Why choose KVM over VirtualBox

If you really want to use VirtualBox, I got it working off of this config:

VirtualBox = Type 2 hypervisor

✔️ Click to Expand VirtualBox Example

Change your-user to your username

# vbox.nix
{
  config,
  lib,
  ...
}: let
  cfg = config.custom.virtualbox;
in {
  options.custom.virtualbox = {
    enable = lib.mkEnableOption "Enable VirtualBox";
  };

  config = lib.mkIf cfg.enable {
    virtualisation.virtualbox.host = {
      enable = false;
      # enableExtensionPack = true;
    };

    user.user.your-user.extraGroups = ["vboxusers"];

    boot.kernelModules =
      if config.hardware.cpu.amd.updateMicrocode
      then ["kvm-amd"]
      else ["kvm-intel"];
  };
}

Enable it with custom.virtualbox.enable = true;.

Whonix VBox Download

After rebuilding with virtualbox enabled and downloading the virtualbox whonix, open VirtualBox and import the Whonix file.

Fix the error:: VirtualBox can’t enable the AMD-V extension. Please disable the KVM kernel extension:

If both of these are active, they compete with each other:

sudo lsmod | grep -E 'kvm|vbox'

Check the currently in use modules:

modprobe -r kvm

Disable kvm and kvm_amd:

sudo rmmod kvm_amd
sudo rmmod kvm
# To re-enable them when necessary
# sudo modprobe kvm
# sudo modprobe kvm_amd

Quick fix

There is an opposite viewpoint, Why choose VirtualBox over KVM

Whonix-Gateway

The whonix-gateway is software designed to run Tor.

The Gateway acts as a firewall and is what is routing all your traffic through Tor.

You will spend minimal time in the Gateway, it’s mainly used for Tor configuration which is reserved for advanced users.

Whonix-Workstation

All user applications should only be launched from Whonix-Workstation to ensure they utilize the Tor network. (Never launch the Tor browser or any other user app from Whonix-Gateway.)

Leaky applications can’t breakout of the Workstation, all network connections are forced to go through the Whonix-Gateway where they are torrified and routed to the internet.

Whonix KVM (Kernel Virtual Machine) on NixOS

KVM (Kernel-based Virtual Machine) is a Linux kernel module that provides hardware-assisted virtualization.

It allows the Linux kernel to act as a hypervisor, enabling virtual machines (VMs) to run with near-native speeds by using CPU virtualization extensions (Intel VT-x or AMD-V).

KVM itself doesn’t handle the entire VM lifecycle; it provides the core virtualization infrastructure.

QEMU (Quick Emulator) is an open-source user-space program that emulates hardware for virtual machines.

When combined with KVM, QEMU uses hardware acceleration to run VMs much faster by offloading CPU virtualization to KVM.

So, QEMU provides the device emulation and VM management interface, while KVM provides the fast virtualization engine within the kernel.

Install Qemu-KVM:

{
  config,
  pkgs,
  ...
}: {
  ##  QEMU-KVM
  environment.systemPackages = with pkgs; [
    qemu
    # Optional
    virt-viewer
  ];

  # Virt-Manager GUI
  programs.virt-manager.enable = true;
  virtualisation = {
    # libvirtd daemon
    libvirtd = {
      enable = true;
      qemu = {
        # enables a TPM emulator
        swtpm.enable = true;
      };
    };
    # allow USB device to be forwarded
    spiceUSBRedirection.enable = true;
  };
  # Spice protocol improves VM display and input responsiveness
  services.spice-vdagentd.enable = true;
}

The libvirtd is the primary daemon (service) in the libvirt virtualization management system. It runs on your host machine and acts as the core management component for virtual machines (VMs).

Add libvirtd & kvm to your users extraGroups:

users.users = {
    your-user = {
        extraGroups = [
            "libvirtd"
            "kvm"
        ];
    };
};

Restart libvirtd:

sudo systemctl restart libvirtd

Network Start

Ensure KVM’s / QEMU’s default network is enabled and has started:

sudo virsh -c qemu:///system net-autostart default

sudo virsh -c qemu:///system net-start default

Download Whonix (KVM) (stable)

Whonix (KVM) (stable) Download
Go to whoniix.org to verify the signature. Download the OpenPGP Signature, and the Download Whonix OpenPGP Key. Your Downloads directory will look like this:

~/Downloads󰏫 ls
╭───┬───────────────────────────────────────────────────────┬──────┬─────────┬───────────────╮
│ # │                         name                          │ type │  size   │   modified    │
├───┼───────────────────────────────────────────────────────┼──────┼─────────┼───────────────┤
│ 0 │ Whonix-Xfce-17.4.4.6.Intel_AMD64.qcow2.libvirt.xz     │ file │  3.3 GB │ 2 minutes ago │
│ 1 │ Whonix-Xfce-17.4.4.6.Intel_AMD64.qcow2.libvirt.xz.asc │ file │  1.0 kB │ a minute ago  │
│ 2 │ derivative.asc                                        │ file │ 77.3 kB │ 3 minutes ago │
╰───┴───────────────────────────────────────────────────────┴──────┴─────────┴───────────────╯

Import derivative.asc:

gpg --import derivative.asc

Verify the Public Key:

gpg --verify Whonix-Xfce-17.4.4.6.Intel_AMD64.qcow2.libvirt.xz.asc Whonix-Xfce-17.4.4.6.Intel_AMD64.qcow2.libvirt.xz
gpg: Signature made Sun 10 Aug 2025 09:04:13 AM EDT
gpg:                using RSA key 6E979B28A6F37C43BE30AFA1CB8D50BB77BB3C48
gpg: Good signature from "Patrick Schleizer <adrelanos@kicksecure.com>" [unknown]
gpg:                 aka "Patrick Schleizer <adrelanos@riseup.net>" [unknown]
gpg:                 aka "Patrick Schleizer <adrelanos@whonix.org>" [unknown]
gpg: WARNING: This key is not certified with a trusted signature!
gpg:          There is no indication that the signature belongs to the owner.
Primary key fingerprint: 916B 8D99 C38E AF5E 8ADC  7A2A 8D66 066A 2EEA CCDA
     Subkey fingerprint: 6E97 9B28 A6F3 7C43 BE30  AFA1 CB8D 50BB 77BB 3C48
~/Downloads󰏫                                                                                                 09/04/2025 11:53:10 AM

Now gpg --list-keys will show Patrick Schleizer’s Key.

It is good practice to sign your verified key and then push it to the public keyserver to contribute to the web of trust but optional.

Decompress the Image and follow the rest of the Whonix KVM install instructions from there.

Nixpkgs doesn’t have the xz-utils package but it does have the xz package.

Nixpkgs also has nixpkgs.safe-rm if you wanted to follow the suggestions from Whonix.

nix-shell -p xz safe-rm

tar -xvf Whonix*.libvirt.xz

Import the Whonix VM Templates

The following commands come directly from the Whonix KVM Docs Importing Whonix VM Templates

Add the virtual networks. This step only needs to be done once and not with every upgrade.

sudo virsh -c qemu:///system net-define Whonix_external*.xml

sudo virsh -c qemu:///system net-define Whonix_internal*.xml

Activate the virtual networks:

sudo virsh -c qemu:///system net-autostart Whonix-External

sudo virsh -c qemu:///system net-start Whonix-External

sudo virsh -c qemu:///system net-autostart Whonix-Internal

sudo virsh -c qemu:///system net-start Whonix-Internal

Import the Whonix Gateway and Workstation images:

sudo virsh -c qemu:///system define Whonix-Gateway*.xml

sudo virsh -c qemu:///system define Whonix-Workstation*.xml

After the above steps, either copy or move the qcow2 images to /var/lib/libvirt/images:

❗ It’s recommended to move the files into place, if you want to copy them you need to use a special command FYI.

sudo mkdir -p /var/lib/libvirt/images

sudo mv Whonix-Gateway*.qcow2 /var/lib/libvirt/images/Whonix-Gateway.qcow2

sudo mv Whonix-Workstation*.qcow2 /var/lib/libvirt/images/Whonix-Workstation.qcow2

Cleanup

safe-rm Whonix*

safe-rm -r WHONIX*

Launch virt-manager and start the VMs

virt-manager

From here it will take a bit to load both VMs, you can click on one and go to Edit, Virtual Machine Details and from there you have some options to give the VM more CPUs and memory.

Considering that the Whonix-Workstation is where all of the user applications will be opened, it makes sense to give it more CPUs and memory.

I’ve seen recommendations for a minimum of 4G of RAM for the Workstation and 2GB for the Gateway.

Increase vCPU count for better performance
Enable XML editing in settings
Enable copy pasting by adding <clipboard copypaste="yes"/>

Start Whonix-Gateway

Always start the Whonix-Gateway first.

Click on Whonix-Gateway, press Play, and choose the default Persistent VM.

To view the gateway press Open.

You can use the “System Maintenance Panel” to Check for Updates and then Install Updates. This can also be used for user and password creation, the default user is user with a passwordless login.

Change the password manually:

sudo passwd
changeme

Change the passwords and disable auto-login.

Run a systemcheck if it wasn’t run automatically. Click the Xfce Logo and go to System, System Check.

Whonix Common CLI Commands

Whonix-Workstation

Whonix-Workstation is another VM, designed to provide users with a secure and anonymous environment for running applications and performing online tasks.

When you first launch Whonix-Workstation, choose the second option down or reboot, and then choose “Persistent Mode Sysmaint Session”. From there, you can go through the same steps as you did for the Gateway.

With the workstation, a security feature disables sudo for the default user. Instead of the user account, a separate sysmaint (system maintenance) account is used for administrative tasks that require root privileges, such as updates and package installations.

Change all user passwords and disable auto-login

After you get your system updated and upgraded, you’ll want to reboot the Workstation and start it in the first Persistent mode available rather than the sysmaint mode.

Once Workstation is running and both VMs are updated and upgraded, check that your IP address is a Tor IP:

curl ip.me
#
curl ip.me

Each consecutive time that you run curl ip.me, Tor establishes a new circuit and you will get a different IP returned each time for as many Tor nodes are available. Not that you would want to but it’s cool functionality giving us a visual of the new circuit.

Start Tor and check what you are fingerprinted as by typing deviceinfo.me into the URL.

Launching Tor Browser

Click the Xfce logo and choose Tor Browser. On the first launch, you will need to update Tor by clicking in the top right corner.

Or you can open the terminal and type:

update-torbrowser

Every time you run the above command, the old browser will be killed, along with your old browser profile, including bookmarks and passwords. If the update suggests a downgrade from your current version don’t do it, it is likely a downgrade attack.

Make sure you don’t forget to go to the Settings, Privacy and Security, and set the Security Level to Safest to disable JavaScript and more before exploring the dark web.

Visit https://check.torproject.org, you should see “Congratulations. This browser is configured to use Tor.”

If you need a place to start, check out https://tor.taxi by plugging that into the URL. Always include the https yourself!

❗ NOTE: Use HTTPS and TLS wherever possible, since Tor only encrypts traffic as it travels through the network of three nodes. Traffic at Exit nodes is vulnerable if unencrypted, because when it reaches the Exit node it is plain text. Prefer the use of .onion services because they form a tunnel that is encrypted end-to-end, using a random rendezvous point within the Tor network; HTTPS isn’t required within Onion services. Prefer the use of .onion services because they form a tunnel that is encrypted end-to-end, using a random rendezvous point within the Tor network; HTTPS isn’t required within Onion services. –All my traffic is encrypted by default?

Live Mode

To get Whonix to perform more similarly to Tails you could run Whonix in Live Mode. Live Mode is a privacy-focused mode where nothing is saved at shutdown, making it great for handling sensitive data.

Live Mode

Same process, reboot the Workstation and Choose LIVE Mode | USER Session | disposable use

Anti Forensics Precautions

Download and Verify Kicksecure KVM

Kicksecure KVM wiki

Download Kicksecure Xfce (KVM) (stable) (FREE!)
Download OpenPGP Signature
Download Kicksecure OpenPGP Key
Import the derivative.asc file:

gpg --import derivative.asc

Make sure both files are done downloading and run the following to verify, your file names might be slightly different:

gpg --verify Kicksecure-Xfce-17.4.4.6.Intel_AMD64.qcow2.libvirt.xz.asc Kicksecure-Xfce-17.4.4.6.Intel_AMD64.qcow2.libvirt.xz
gpg: Signature made Sun 10 Aug 2025 07:32:52 AM EDT
gpg:                using RSA key 6E979B28A6F37C43BE30AFA1CB8D50BB77BB3C48
gpg: Good signature from "Patrick Schleizer <adrelanos@kicksecure.com>" [unknown]
gpg:                 aka "Patrick Schleizer <adrelanos@riseup.net>" [unknown]
gpg:                 aka "Patrick Schleizer <adrelanos@whonix.org>" [unknown]
gpg: WARNING: This key is not certified with a trusted signature!
gpg:          There is no indication that the signature belongs to the owner.
Primary key fingerprint: 916B 8D99 C38E AF5E 8ADC  7A2A 8D66 066A 2EEA CCDA
     Subkey fingerprint: 6E97 9B28 A6F3 7C43 BE30  AFA1 CB8D 50BB 77BB 3C48

Decompress

tar -xvf Kicksecure*.libvirt.xz

Don’t use unxz!

Resources

k System Hardening Checklist

Functions and NixOS Modules

2025-11-30T00:00:00+00:00

Functions and NixOS Modules

✔️ Click to Expand Table of Contents

When you start exploring NixOS configurations or tools like Home Manager, you’ll encounter a concept called Nix Modules. Modules are also functions, but they behave differently regarding their arguments, which can be a source of confusion.

What are NixOS Modules?

Nix Modules are a powerful system built on top of basic Nix functions, primarily used for declarative system configurations (like NixOS, Home Manager, NixOps, etc.). They allow you to define parts of your system configuration in separate files that are then composed together.

Each module is typically a Nix function that returns an attribute set with specific keys like options, config, and imports.

Automatic Arguments in Modules

Unlike the functions we’ve been writing, Nix’s module system automatically passes a standard set of arguments to every module function it evaluates. You don’t explicitly pass these arguments when you import a module file; the module system handles it for you.

The most common automatic arguments you’ll see are:

config: The aggregated configuration options of all modules combined. This is what you use to read other configuration values.
options: The definitions of all available configuration options across all modules.
pkgs: The standard Nixpkgs set, equivalent to import <nixpkgs> {}. This is incredibly convenient as you don’t need to import it in every module.
lib: The Nixpkgs utility library (pkgs.lib), providing helper functions for common tasks.
specialArgs: An attribute set of extra arguments to be passed to the module functions.

A typical module might start like this:

# Example NixOS module
{ config, pkgs, lib, ... }: # These arguments are passed automatically by the module system
{
  # ... module options and configuration
  environment.systemPackages = [ pkgs.firefox pkgs.git ];
  services.nginx.enable = true;
  # ...
}

In the above module, the only required argument is pkgs because we explicitly use it in the module (i.e. pkgs.firefox). Editors have pretty good support for letting you know if you’re missing arguments or have unnecessary ones. config, and lib and would be required if we were setting any options in this module.

This automatic passing of arguments is a core feature of the module system that simplifies writing configurations, as you always have access to pkgs, lib, and the evolving config and options without boilerplate.

`specialArgs`: Passing Custom Arguments to Modules

While the module system passes a standard set of arguments automatically, what if you need to pass additional, custom data to your modules that isn’t part of the standard config, pkgs, lib, or options? This is where specialArgs comes in.

specialArgs is an attribute you can pass to the import function when you load a module (or a set of modules). It’s typically used to provide data that your modules need but isn’t something Nixpkgs would normally manage.

For example, in a configuration.nix:

# From your configuration.nix
{ config, pkgs, lib, ... }: # Standard module arguments

let
  myCustomValue = "helloWorld";
in
{
  # ... imports all modules, including your custom ones
  imports = [
    ./hardware-configuration.nix
    ./my-webserver-module.nix
  ];

  # This is where specialArgs would be used (often in import statements)
  # Example: passing a custom value to ALL modules:
  # (in module context, this is more complex, but conceptually)
  # let
  #   allModules = [ ./my-module.nix ];
  # in
  # lib.nixosSystem {
  #   modules = allModules;
  #   specialArgs = {
  #     username = "johndoe";
  #     mySecretKey = "/run/keys/ssh_key";
  #   };
  #   # ...
  # };
}

And then, inside my-webserver-module.nix:

# my-webserver-module.nix
{ config, pkgs, lib, username, mySecretKey, ... }: # username and mySecretKey come from specialArgs
{
  # ... use username and mySecretKey in your module
  users.users.${username} = {
    isNormalUser = true;
    extraGroups = [ "wheel" "networkmanager" ];
    # ...
  };
  # ...
}

Any argument listed in a module’s function signature that is not one of the standard config, pkgs, lib, options (or pkgs.callPackage, etc., which are often implicit through pkgs) must be provided via specialArgs at the point where the modules are composed.

Any values listed in a module that aren’t automatically passed via Nixpkgs must be explicitly provided through specialArgs.

`specialArgs` and `extraSpecialArgs` with Flakes

NixOS modules use specialArgs and Home-Manager uses extraSpecialArgs to allow you to pass extra arguments.

Or with Flakes it would look like this:

{
  description = "My Flake";
  inputs = {
    nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
    home-manager.url = "github:nix-community/home-manager";
    home-manager.inputs.nixpkgs.follows = "nixpkgs";
   };

  outputs = { self, nixpkgs, home-manager, ... }:
    let
      lib = nixpkgs.lib;
      pkgs = nixpkgs.legacyPackages.${"x86_64-linux"};
      system = "x86_64-linux";
  host = "magic";
  username = "jr";
  userVars = {
    timezone = "America/New_York";
    locale = "en_US.UTF-8";
    gitUsername = "TSawyer87";
    dotfilesDir = "~/.dotfiles";
    wm = "hyprland";
    browser = "firefox";
    term = "ghostty";
    editor = "hx";
    keyboardLayout = "us";
  };
    in {
      nixosConfigurations = {
        YOURHOSTNAME = lib.nixosSystem {
          system = "x86_64-linux";
          modules = [ ./configuration.nix ];
          specialArgs = {
            inherit userVars; # == userVars = userVars;
            inherit host;
            inherit username;
          };
        };
      };
      homeConfigurations = {
        USERNAME = home-manager.lib.homeManagerConfiguration {
          inherit pkgs;
          modules = [ ./home.nix ];
          extraSpecialArgs = {
            inherit userVars;
            inherit host;
            inherit username;
            # or it can be written like this:
            # inherit userVars host username;
          };
        };
      };
    };
}

Now if I want to use any of these arguments in modules I can by any module file referenced by my configuration.

For example, the following is a git.nix module that uses the variables from the flake passed from extraSpecialArgs in this case because it’s a home-manager module:

# git.nix
{ userVars, ... }: {
  programs = {
    git = {
      enable = true;
      userName = userVars.gitUsername;
    };
  };
}

Feature	Regular Nix Function (e.g., `hello.nix`)	Nix Module (e.g., `my-config-module.nix`)
Arguments	You must explicitly pass every single argument.	Automatically receives `config`, `pkgs`, `lib`, `options`, etc.
Custom Args	Passed directly in the function call.	Passed via `specialArgs` when the modules are composed.
Boilerplate	Often needs `pkgs = import <nixpkgs> {};` if not explicitly passed.	`pkgs` and `lib` are always available automatically.
Purpose	Defines a package, a utility, or a single value.	Defines a reusable part of a declarative system configuration.

Git

2025-11-30T00:00:00+00:00

Version Control with Git

✔️ Click to Expand Table of Contents

⚠️ Important: Never commit secrets (passwords, API keys, tokens, etc.) in plain text to your Git repository. If you plan to publish your NixOS configuration, always use a secrets management tool like sops-nix or agenix to keep sensitive data safe. See the Sops-Nix Guide for details.

It’s also important to understand that all files in the /nix/store are world-readable by default This has important security implications for anyone managing sensitive data on a NixOS system.

What Does “World-Readable” Mean?

All files in /nix/store are readable by any user on the system.
This is by design, the nix store is intended to be shared, immutable store of all packages and configuration files.
Permissions are typically set to r-xr-xr-x(read and execute for everyone)

Security Implications

Never store secrets or sensitive data in plane text in the Nix store.
If you include secrets directly in your configuration, they will end up in the /nix/store and be accessible to any user or process on the system.
This applies to files, environment variables, and any data embedded in derivations.

Best Practices

Always use a secrets management tool (like sops-nix or agenix) that decrypts secrets at activation time and stores them outside the Nix store, with restricted permissions.
Do not embed secrets directly in Nix expressions or configuration files that will be build into the store.
Even hashed passwords can be vulnerable when stored in a public repository, be conscious of what you store where.
If you’re unsure about what’s safe to share, start with a private repository. This gives you time to learn about secrets management and review your configuration before making anything public.

First, I’ll briefly explain some of the limitations of NixOS Rollbacks and then I’ll go into how Git compliments them.

Limitations of NixOS Rollbacks

NixOS is famous for its ability to roll back to previous system generations, either from the boot menu or with commands like nixos-rebuild --rollback.

When you perform rollbacks in NixOS, whether from the boot menu or using commands like nixos-rebuild --rollback only the contents and symlinks managed by the Nix store are affected. The rollback works by switching which system generation is active, atomically updating symlinks to point to the previous version of all packages, systemd units and services stored in /nix/store.

However, it’s important to understand what these rollbacks actually do and what they don’t do. What NixOS Rollbacks Cover

System generations: When you rebuild your system, NixOS creates a new “generation” that you can boot into or roll back to. This includes all packages, services, and system configuration managed by Nix.
Quick recovery: If an upgrade breaks your system, you can easily select an older generation at boot and get back to a working state

Key Limitations:

Configuration files are not reverted: Rolling back only changes which system generation is active, it does not revert your actual configuration files (like configuration.nix or your flake files)
User data and service data are not rolled back: Only files managed by Nix are affected. Databases, user files, and other persistent data remain unchanged, which can cause problems if, for example, a service migrates its database schema during an upgrade
Manual changes persist: Any manual edits to configuration files or system state outside of Nix are not reverted by a rollback

How Git Helps

The gh-cli, simplifies quite a few things for working with GitHub from the command line.
Tracks every configuration change: By version-controlling your NixOS configs with Git, you can easily see what changed, when, and why.
True config rollback: If a configuration change causes issues, you can use git checkout or git revert to restore your config files to a previous good state, then rebuild your system
Safer experimentation: You can confidently try new settings or upgrades, knowing you can roll back both your system state (with NixOS generations) and your config files (with Git).
Collaboration and backup: Git lets you share your setup, collaborate with others, and restore your configuration if your machine is lost or damaged.

In summary: NixOS rollbacks are powerful for system state, but they don’t manage your configuration file history. Git fills this gap, giving you full control and traceability over your NixOS configs making your system both robust and truly reproducible. Version control is a fundamental tool for anyone working with NixOS, whether you’re customizing your desktop, managing servers, or sharing your configuration with others. Git is the most popular version control system and is used by the NixOS community to track, share, and back up system configurations.

Why use Git with NixOS?

Track every change: Git lets you record every modification to your configuration files, so you can always see what changed, when, and why.
Experiment safely: Try new settings or packages without fear—if something breaks, you can easily roll back to a previous working state.
Sync across machines: With Git, you can keep your NixOS setups in sync between your laptop, desktop, or servers, and collaborate with others.
Disaster recovery: Accidentally delete your config? With Git, you can restore it from your repository in minutes.

Installing Git on NixOS

You can install Git by adding it to your system packages in your configuration.nix or via Home Manager:

Git Tips

If you develop good git practices on your own repositories it will make it easier to contribute with others as well as get help from others.

Atomic Commits

Atomic commits are a best practice in Git where each commit represents a single, focused, and complete change to the codebase. The main characteristics of atomic commits are:

One purpose: Each commit should address only one logical change or task.
Complete: The commit should leave the codebase in a working state.
Descriptive: The commit message should be able to clearly summarize the change in a single sentence.

Why Atomic Commits Matter

Easier debugging: You can use tools like git bisect to quickly find which commit introduced a bug, since each commit is isolated.
Simpler reverts: You can revert without affecting unrelated changes.
Better collaboration: Code reviews and merges are more manageable when changes are small and focused.

When you lump together a bunch of changes into a single commit it can lead to quite a few undesirable consequences. They make it harder to track down bugs, it’s more difficult to revert undesired changes without reverting desired ones, make larger tickets harder to manage.

Every time a logical component is completed, commit it. Smaller commits make it easier for other devs and yourself to understand the changes and roll them back if necessary. This also makes it easier to share your code with others to get help when needed and makes merge conflicts less frequent and complex.

Finish the component, then commit it: There’s really no reason to commit unfinished work, use git stash for unfinished work and git commit for when the logical component is complete. Use common sense and break complex components into logical chunks that can be finished quickly to allow yourself to commit more often.

Write Good Commit Messages: Begin with a summary of your changes, add a line of whitespace between the summary and the body of your message. Make it clear why this change was necessary. Use consistent language with generated messages from commands like git merge which is imperative and present tense (<<change>>, not <<changed>> or <<changes>>).

Tips for Keeping Commits Atomic with a Linear History

Squashing limits the benefits of atomic commits as it combines them all into a single commit as if you didn’t take the time to write them all out atomically.

🧠 Why Rebasing Wins for Linear History

No Merge Bubbles: Rebasing avoids those extra merge commits that clutter git log --graph. You get a clean, readable timeline.
Atomic Commit Integrity: Each commit stands alone and tells a story. Rebasing preserves that narrative without diluting it with merge noise.
Better Blame & Bisect: Tools like git blame and git bisect work best when history is linear and logical.
Time-Travel Simplicity: Cherry-picking or reverting is easier when commits aren’t tangled in merge commits.

By default, when you run git pull git merges the commits into your local repo. To change this to a rebase you can set the following:

git config --global pull.rebase true
git config --global rebase.autoStash true
git config --global fetch.prune true  # auto delets remote-tracking branches that no longer exist
git config --global pull.ff only          # blocks merge pulls

Note: With pull.ff only pulls will fail if they would have had to merge. This could happen if your local branch has diverged from the remote (e.g., someone pushed new commits and you also committed locally) git pull will throw an error like:

fatal: Not possible to fast-forward, aborting.

How to fix it

You basically do what Git won’t auto-do:

git fetch origin
git rebase origin/main

This rewinds your local commits, applies remote commits, and replays yours on top, keeping the history linear.

If you don’t care about your local changes and want to discard them you can use the following command:

git reset --hard origin/main

This just makes your branch identical to the remote, no rebase required. This prevents rogue merge commits, preserving atomic commits and linear logs.

You could set an alias for this with:

git config --global alias.grs '!git fetch origin && git rebase origin/main'

To check whether a setting is active or now you can use:

git config --get rebase.autoStash
true

To set these options with home-manager:

# ... snip ...
    extraConfig = lib.mkOption {
      type = lib.types.attrs;
      default = {
        commit.gpgsign = true;
        gpg.format = "ssh";
        user.signingkey = "/etc/ssh/ssh_host_ed25519_key.pub";
        extraConfig = {
          pull = {
            rebase = true;
            ff = "only";
        };
        };
        rebase = {
          autoStash = true; # Auto stashes and unstashes local changes during rebase
        };
        fetch = {
          prune = true; # Automatically deletes remote-tracking branches that no longer exist
        };
# ... snip ...

Time Travel in Git

✔️ Click to Expand Time Travel Section

View an old commit:

git checkout <commit_hash>

This puts you in a “detached HEAD” state, letting you explore code as it was at that commit. To return, checkout your branch again.

Go back and keep history (revert):

git revert <commit_hash>

Go back and rewrite history (reset):

Soft reset (keep changes staged):

git reset --soft <commit_hash>

Mixed reset (keep changes in working directory):

git reset <commit_hash>

Hard reset (discard all changes after the commit):

git reset --hard <commit_hash>

Use the above command with caution, it can delete commits from history.

Relative time travel:

git reset --hard HEAD@{5.minutes.ago}

git reset --hard HEAD@{yesterday}

Create a branch from the past:

git checkout -b <new-brach> <commit_hash>

This starts a new branch from any previous commit, preserving current changes.

Some repositories have guidelines, such as Nixpkgs:

✔️ Click to Expand Nixpkgs Commit Conventions

Commit conventions

Create a commit for each logical unit.
Check for unnecessary whitespace with git diff --check before committing.
If you have commits pkg-name: oh, forgot to insert whitespace: squash commits in this case. Use git rebase -i. See Squashing Commits for additional information.
For consistency, there should not be a period at the end of the commit message’s summary line (the first line of the commit message).
When adding yourself as maintainer in the same pull request, make a separate commit with the message maintainers: add <handle>. Add the commit before those making changes to the package or module. See Nixpkgs Maintainers for details.

Make sure you read about any commit conventions specific to the area you’re touching. See: Commit conventions for changes to pkgs. Commit conventions for changes to lib. Commit conventions for changes to nixos. Commit conventions for changes to doc, the Nixpkgs manual.

Writing good commit messages

In addition to writing properly formatted commit messages, it’s important to include relevant information so other developers can later understand why a change was made. While this information usually can be found by digging code, mailing list/Discourse archives, pull request discussions or upstream changes, it may require a lot of work.

Package version upgrades usually allow for simpler commit messages, including attribute name, old and new version, as well as a reference to the relevant release notes/changelog. Every once in a while a package upgrade requires more extensive changes, and that subsequently warrants a more verbose message.

Pull requests should not be squash merged in order to keep complete commit messages and GPG signatures intact and must not be when the change doesn’t make sense as a single commit.

A Git workflow is a recipe or recommendation for how to use Git to accomplish work in a consistent and productive manner. Having a defined workflow lets you leverage Git effectively and consistently. This is especially important when working on a team.

Origin is the default name (alias) for the remote repository that your local repository is connected to, usually the one you cloned from.

Remote Repositories are versions of your project that are hosted on the internet or network somewhere.

When you run git push origin main, you’re telling Git to push your changes to the remote repo called origin.
You can see which URL origin points to with git remote -v.
You can have multiple remotes (like origin, upstream, etc.) each pointing to a different remote repo. Each of which is generally either read-only or read/write for you. Collaborating involves managing these remotes and pushing and pulling data to and from them when you need to share work.

❗ You can have a remote repo on your local machine. The word “remote” doesn’t imply that the repository is somewhere else, only that it’s elsewhere.

The name origin is just a convention, it’s not special. It is automatically set when you clone a repo.

Local is your local copy of the repository, git tracks the differences between local and remote which is a repo hosted elsewhere (e.g., GitHub GitLab etc.)

The Upstream in Git typically refers to the original repository from which your local repository or fork was derived. The Upstream is the remote repo that serves as the main source of truth, often the original project you forked from. You typically fetch changes from upstream to update your local repo with the latest updates from the original project, but you don’t push to upstream unless you have write access.

A Basic Git Workflow

Initialize your Repository:

If you haven’t already created a Git repo in your NixOS config directory (for example, in your flake or /etc/nixos):

cd ~/flake
git init
git add .
git commit -m "Initial commit: NixOS Configuration"

Taking this initial snapshot with Git is a best practice—it captures the exact state of your working configuration before you make any changes.

The command git add . stages all files in the directory (and its subdirectories) for commit, meaning Git will keep track of them in your project history.
The command git commit -m "message" then saves a snapshot of these staged files, along with your descriptive message, into the repository.
- Think of a commit as a “save point” in your project. You can always go back to this point if you need to, making it easy to experiment or recover from mistakes. This two-step process, staging with git add and saving with git commit is at the heart of how Git tracks and manages changes over time.

Make and Track Changes:

Now that you’ve saved a snapshot of your working configuration, you’re free to experiment and try new things, even if they might break your setup.

Suppose you want to try a new desktop environment, like Xfce. You edit your configuration.nix to add:

services.xserver.desktopManager.xfce.enable = true;

You run:

sudo nixos-rebuild switch # if configuration.nix is in /etc/nixos/

But something goes wrong: the system boots, but your desktop is broken or won’t start. You decide to roll back using the boot menu or:

sudo nixos-rebuild switch --rollback

What happens?

Your system reverts to the previous working generation in /nix/store
But: Your configuration.nix file is still changed, it still has the line enabling Xfce. If you rebuild again, you’ll get the same broken system, because your config itself wasn’t rolled back.

How does Git Help on Failure?

Git gives you quite a few options and ways to inspect what has been done.

Use git status to see what’s changed, and git checkout -- <file> to restore any file to its last committed state.
Review your changes with git diff to see exactly what you modified before deciding whether to keep or revert those changes.
Reset everything with git reset --hard HEAD, this will discard all local changes and return to your last commit.

With Git you can simply run:

git checkout HEAD~1 configuration.nix
# or, if you committed before the change:
git revert <commit-hash>

Show the full hash of the latest commit:

git rev-parse HEAD
f53fef375d89496c0174e70ce94993d43335098e

Short hash:

git log --pretty=format:'%h' -n 1
f53fef3
git revert f53fef3

Show a list of Recent commits:

git log
# a list of all commits, with hashes, author, date, and message
git log --oneline
git log --oneline
f53fef3 (HEAD -> main) thunar
b34ea22 thunar
801cbcf thunar
5e72ba5 sops
8b67c59 sops
1a353cb sops

You can copy the commit hash from any of these and use it in commands like git checkout <hash> or git revert <hash>.

Commit successful experiments

If your changes work, stage, and commit them:

git add .
# or more specifically the file you changed or created
git add configuration.nix
git commit -m "Describe the new feature or fix"

Basic Branching

With Git you’re always on a branch and the default branch is master. Many change it to main because of the suggestion Git gives you. I think people are too easily offended these days, just keep this in mind that main and master refer to the main development branch.

You can get a listing of your current branches with:

git branch
* (no branch)
  main

The * is next to the current branch and is where the HEAD is currently pointing. It says (no branch) because I’m currently in detached HEAD where HEAD points to no branch. The reason for this is because I’ve been trying out Jujutsu VCS and that’s JJ’s default setting, a detached HEAD.

Git actually gives you a warning about working in a detached HEAD:

You are in 'detached HEAD' state. You can make experimental
changes and commit them, and you can discard any commits you make
in this state without impacting any branch by switching back.

If you want to create a new branch to retain commits you create,
you can do so now (using 'git switch -c <new-branch-name>') or
later (using 'git branch <new-branch-name> <commit-id>').

See 'git help switch' for details.

To attach the HEAD (i.e., have the pointer pointing to a branch), use the git checkout command

git checkout main
Switched to branch 'main'

git branch
* main
# Ensure that you have the latest "tip" from the remote repository `origin`
git fetch origin main
From github.com:sayls8/flake
 * branch            main       -> FETCH_HEAD

Although we’re working on our own repo and there is basically no chance of our local branch diverging from our remote, it’s still good to get in the practice of getting everything in sync before merging or rebasing etc.

git fetch doesn’t update main, it just updates your references. To update main you would use git pull origin/main or git rebase origin/main

You can inspect your upstream branches with the following command:

git remote show origin
* remote origin
  Fetch URL: git@github.com:saylesss88/flake.git
  Push  URL: git@github.com:saylesss88/flake.git
  HEAD branch: main
  Remote branch:
    main tracked
  Local ref configured for 'git push':
    main pushes to main (fast-forwardable)

* branch main -> FETCH_HEAD: This line signifies that the main branch from the remote repository (likely origin) was successfully fetched, and the commit ID of its current tip (its latest commit) is now stored in your local FETCH_HEAD reference.

Now that we know our local main is up to date with our remote origin/main we can safely create a new feature branch:

git checkout -b feature/prose_wrap
Switched to a new branch 'feature/prose_wrap'

Right now the branch feature/prose_wrap is exactly the same as main and we can safely make changes without affecting main. We can try crazy or even “dangerous” things and always be able to revert to a working state with git checkout main.

If our crazy idea works out, we can then merge our feature branch into main.

Ok the feature works, I’ve added and committed the change. Now it’s time to point the HEAD to main and then either merge or rebase the feature branch into main:

git checkout main
git fetch origin main
git merge feature/prose_wrap
Updating c8bd54c..b281f79
Fast-forward
 home/editors/helix/default.nix | 69 +++++++++++++++++++++++++++++++--------------------------------------
 1 file changed, 31 insertions(+), 38 deletions(-)

“fast-forward” means that our feature/prose_wrap branch was directly ahead of the last commit on main. When you merge one commit with another commit that can be reached by following the first commits history, remember the feature branch is exactly the same as main until I made another commit. If the branches diverged more and the history can’t be followed, Git will perform a 3-way merge where it creates a new “merge commit” that combines the 2 changes.

If you have a bunch of branches and forget which have been merged yet use:

git branch --merged
feature/prose_wrap
* main
# OR to see branches that haven't been merged use:
git branch --no-merged

It’s now safe to delete the feature branch:

git branch -d feature/prose_wrap
Deleted branch feature/prose_wrap (was b281f79)

❗ TIP: If your feature branch has a lot of sloppy commits that won’t be of much benefit to anyone, squash them first then merge. The workflow would look something like this:
 # Make sure you're on the main branch
 git checkout main

 # Merge the feature branch with squash
 git merge --squash feature/prose_wrap
This combines all the commits in your branch and adds them to your main staging area, it doesn’t move HEAD or create a merge commit for you. To apply the changes into one big commit, finalize it with:
 git commit -m "Add prose wrapping feature"
This is often referred to as the “squash commit”.

Branching means to diverge from the main line of development and continue to do work without risking messing up your main branch. There are a few commits on your main branch so to visualize this it would look something like this, image is from Pro Git:

Nix flake update example with branches

Let’s say you haven’t ran nix flake update in a while and you don’t want to introduce errors to your working configuration. To do so we can first, make sure we don’t lose any changes on our main branch:

git add .
git commit -m "Staging changes before switching branches"
# I always like to make sure the configuration will build before pushing to git
sudo nixos-rebuild switch --flake .
# If everything builds and looks correct
git push origin main

OR, if you have incomplete changes that you don’t want to commit yet you can stash them with git stash:

git status
On branch main
Your branch is ahead of 'origin/main' by 1 commit.
  (use "git push" to publish your local commits)

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
        modified:   home/git.nix

no changes added to commit (use "git add" and/or "git commit -a")

Now we want to switch branches, without committing the incomplete changes to git.nix:

git stash
Saved working directory and index state WIP on main: 0e46d6b git: lol alias

git status
On branch main
Your branch is ahead of 'origin/main' by 1 commit.
  (use "git push" to publish your local commits)

nothing to commit, working tree clean

❗ git stash is equivalent to git stash push

To see which stashes you have stored, use git sash list:

git stash list
stash@{0}: WIP on main: 0e46d6b git: lol alias

To apply the most recent stash:

git stash apply
git add home/git.nix
On branch main
Your branch is ahead of 'origin/main' by 1 commit.
  (use "git push" to publish your local commits)

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
        modified:   home/git.nix

# or for multiple stashes
git stash apply stash@{2}

Running git stash apply applies the changes that were in your stash but doesn’t automatically restage them, to apply the changes and stage them in one command:

git stash apply --index

Now let’s create our branch so we can safely update:

git checkout -b update-test
Switched to a new branch 'update-test'

-b is to switch to the branch that was just created

Some may prefer a more descriptive branch name such as: update/flake-inputs, I kept it short for the example. Or if your company uses an issue tracker, including the ticket number in the branch name can be helpful: update/123-flake-inputs

The above command is equivalent to:

git branch update-test
git checkout update-test

~~Now our branches would look something like this, note how both branches currently point to the same commit:~~ I discovered that Git Book has pretty restrictive licensing and will eventually find a replacement.

Now, lets run our update:

nix flake update
sudo nixos-rebuild test --flake .
# If everything looks ok let's try applying the changes
sudo nixos-rebuild switch --flake .
# And if everything looks ok:
git add .
git commit -m "feat: Updated all flake inputs"
git push origin update-test

❗ This is the same workflow for commiting a PR. After you first fork and clone the repo you want to work on, you then create a new feature branch and push to that branch on your fork. This allows you to create a PR comparing your changes to their existing configuration.

~~At this point our graph would look similar to the following~~:

If we are satisfied, we can switch back to our main branch and merge update-test into it:

git checkout main
git merge origin/update-test
git branch -D update-test
sudo nixos-rebuild test --flake .
sudo nixos-rebuild switch --flake .

It’s good practice to delete a branch after you’ve merged and are done with it.

Rebasing Branches

To combine two seperate branches into one unified history you typically use git merge or git rebase.

git merge takes two commit pointers and finds a common base commit between them, it then creates a “merge commit” that combines the changes.

git rebase is used to move a sequence of commits to a new base commit.

Configure Git Declaratively

The following example is the git.nix from the hydenix project it shows some custom options and a way to manage everything from a single location:

# git.nix from hydenix: declarative Git configuration for Home Manager
{ lib, config, ... }:

let
  cfg = config.hydenix.hm.git;
in
{

  options.hydenix.hm.git = {
    enable = lib.mkOption {
      type = lib.types.bool;
      default = config.hydenix.hm.enable;
      description = "Enable git module";
    };

    name = lib.mkOption {
      type = lib.types.nullOr lib.types.str;
      default = null;
      description = "Git user name";
    };

    email = lib.mkOption {
      type = lib.types.nullOr lib.types.str;
      default = null;
      description = "Git user email";
    };
  };

  config = lib.mkIf cfg.enable {

    programs.git = {
      enable = true;
      userName = cfg.name;
      userEmail = cfg.email;
      extraConfig = {
        init.defaultBranch = "main";
        pull.rebase = false;
      };
    };
  };
}

❗ You can easily change the name of the option, everything after config. is custom. So you could change it to for example, config.custom.git and you would enable it with custom.git.enable = true; in your home.nix or equivalent.

Then he has a hm/default.nix with the following to enable it.

#...snip...

 # hydenix home-manager options go here
  hydenix.hm = {
    #! Important options
    enable = true;
      git = {
        enable = true; # enable git module
        name = null; # git user name eg "John Doe"
        email = null; # git user email eg "john.doe@example.com"
      };
    }

    # ... snip ...

You can enable git, and set your git username as well as git email right here.

Resources

Intro to Nushell

2025-11-30T00:00:00+00:00

Chapter 12

✔️ Click to Expand Table of Contents

Intro to Nushell on NixOS

TL;DR:I recently switched default shells from zsh to nushell, this post is about some of the challenges and advantages of using nushell with NixOS.
While the average user might not immediately see significant advantages, those who frequently work with structured data formats like JSON, YAML, and CSV – such as developers interacting with APIs, system administrators managing configurations, and data professionals – will likely find Nushell’s native data handling and powerful pipeline capabilities a plus. Additionally, users who value a more consistent and safer scripting experience might appreciate Nushell’s language-first design and features like strong typing.
I’ll start with some of the unique build design choices and unique features that I think make Nushell special, then show an example using Nushell to manipulate JSON data. Finally, I will highlight some of the visually appealing aspects of Nushell and lastly I share some resources for learning more.

The Good

Nushell borrows concepts from many shells and languages and is itself both a programming language and a shell. Because of this, it has its own way of working with files, directories, websites, and more.
Nushell is powerful and has many essential commands built directly into the shell (“internal” commands) rather than a link to an executable. You can use this set of commands across different operating systems, having this consistency is helpful when creating cross-platform code.
When internal Nushell commands (like ls, open, where, get, sort-by, etc.) produce output, they generally do so in Nushell’s structured data format (tables or records). This is the shell’s native way of representing information.
Beyond these foundational strengths, Nushell offers a range of unique features that enhance its functionality and make it particularly well-suited for data-heavy tasks. Here are some highlights that showcase its versatility.

Some Unique Features:

Besides the built-in commands, Nushell has a standard library Nushell operates on structured data. You could call it a “data-first” shell and programming language.
Also included, is a full-featured dataframe processing engine using Polars if you want to process large data efficiently directly in your shell, check out the Dataframes-Docs
Multi-Line Editing:
When writing a long command you can press Enter to add a newline and move to the next line. For example:

ls            |    # press enter
where name =~ |    # press enter, comments after pipe ok
get name      |    # press enter
mv ...$in ./backups/

This allows you to cycle through the entire multi-line command using the up and down arrow keys and then customize different lines or sections of the command.
You can manually insert a newline using Alt+Enter or Shift+Enter.
The Reedline-Editor is powerful and provides good vi-mode or emacs support built in.
It’s default Ctrl+r history command is nice to work with out of the box.
The explore command, is nu’s version of a table pager, just like less but for table structured data:

$nu | explore --peek

With the above command you can navigate with vim keybinds or arrow keys.
These features demonstrate Nushell’s user-friendly interface, but what truly sets it apart is its underlying design as a structured data scripting language. This “language-first” approach powers many of its distinctive capabilities.

Unique design:

Fundamentally designed as a structured data scripting language: and then it acts as a shell on top of that foundation. This “language first” approach is what gives it many of its distinctive features and makes it a powerful scripting language. I reiterate this here because of the implications of this. A few of those features are:
- Pipelines of structured data: Unlike traditional shells that primarily deal with plain text streams, Nushell pipelines operate on tables of structured data. Each command can understand and manipulate this structured data directly.
- Consistent syntax: Its syntax is more consistent and predictable compared to the often quirky syntax of Bash and Zsh, drawing inspiration from other programming languages.
- Strong typing Nushell has a type system, which helps catch errors early and allows for more robust scripting.
- First-class data types: It treats various data formats (like JSON, CSV, TOML) as native data types, making it easier to work with them. Because of this, Nushell aims to replace the need for external tools like jq, awk, sed, cut, and even some uses of grep and curl.
Variables are Immutable by Default: Nushell’s commands are based on a functional-style of programming which requires immutability, sound familiar?
Nushell’s Environment is Scoped: Nushell takes many design cues from compiled languages, one is that languages should avoid global mutable state. Shells have commonly used global mutation to update the environment, Nushell attempts to steer clear of this increasing reproducability.
Single-use Environment Variables:

FOO=BAR $env.FOO
# => BAR

Permanent Environment Variables: In your config.nu

# config.nu
$env.FOO = 'BAR'

Coming-From-Bash
These design principles make Nushell a powerful tool for scripting, but they’re best understood through a hands-on example. Let’s see how Nushell’s structured data capabilities shine in a common task: processing a JSON file.

Example: I wanted to provide a practical example to illustrate some of these “Good” features in action. And break it down for better understanding.

Let’s consider a common task: processing data from a JSON file. Imagine you have a file containing a list of users with their names and ages. With traditional shells, you’d likely need to rely on external tools like jq to parse and filter this data. However, Nushell can handle this directly within its own commands.
For this example you could create a test directory and move to it:

mkdir test ; cd test

Create a users.json with the following contents:

👇 users.json

[
  { "name": "Alice", "age": 25 },
  { "name": "Bob", "age": 30 },
  { "name": "Charlie", "age": 20 }
]

And create the following filter.nu that first converts users.json into its own internal structured data format with the open command, then to filters out people under 21 with the where control flow construct, then selects the name and age columns, sorts them by age, and finally converts them back to json and saves them to a file called filtered_users.json. A lot happening in a 6 line script.

# filter.nu
open users.json           # Read JSON file into structured data
| where age > 21         # Filter users older than 21
| select name age        # Select only name and age columns
| sort-by age            # Sort by age
| to json                # Convert back to JSON
| save filtered_users.json # Save result to a new file

The open command takes data from a file (or even a URL in some cases) and parses it and converts it into Nushells own internal structured data format. So this command isn’t just showing you the contents of users.json but doing a conversion to Nu’s special structured format.

open users.json
╭───┬─────────┬─────╮
│ # │  name   │ age │
├───┼─────────┼─────┤
│ 0 │ Alice   │  25 │
│ 1 │ Bob     │  30 │
│ 2 │ Charlie │  20 │
╰───┴─────────┴─────╯

The source command in Nushell is used to execute the commands within a script file (like filter.nu) in the current Nushell environment. It’s similar to running the script directly in the shell, but keeps the shell open for further use. In this example, source filter.nu runs the commands inside filter.nu, processing the users.json file and creating the filtered_users.json file:

source filter.nu
# View the contents with bat
bat filtered_users.json
───────┬──────────────────────────────────────────────────────────────────────────────────────
       │ File: filtered_users.json
───────┼──────────────────────────────────────────────────────────────────────────────────────
   1   │ [
   2   │   {
   3   │     "name": "Alice",
   4   │     "age": 25
   5   │   },
   6   │   {
   7   │     "name": "Bob",
   8   │     "age": 30
   9   │   }
  10   │ ]
───────┴───────────────────────────────────────────────────────────────────────────────────

As you can see, without needing any external tools, Nushell was able to read, filter, select, sort, and then re-serialize JSON data using a clear and concise pipeline. This demonstrates its power in handling structured data natively, making common data manipulation tasks within the shell significantly more streamlined and readable compared to traditional approaches.

In the filter.nu example:

# filter.nu
open users.json           # Read JSON file into structured data
| where age > 21         # Filter users older than 21
| select name age        # Select only name and age columns
| sort-by age            # Sort by age
| to json                # Convert back to JSON
| save filtered_users.json # Save result to a new file

✔️ Summary of above Command (Click to Expand)

open users.json: Produces a Nushell table representing the data.
| where age > 21: Receives the table, filters rows based on the age column, and outputs a new, filtered table.
| select name age: Receives the filtered table, selects only the name and age columns, and outputs a table with fewer columns.
| sort-by age: Receives the table, sorts the rows based on the age column, and outputs a sorted table.
| to json: Receives the sorted table and converts it back into JSON text.
| save filtered_users.json: Receives the JSON text and saves it to a file.

So, while the concept of piping is the same, the nature of the data flowing through the Nushell pipeline is richer and more structured, enabling more powerful and direct data manipulation.
While Nushell’s strengths, like its structured data pipelines, make it a game-changer for many tasks, it’s not without its challenges, especially when integrated with NixOS’s Bash-centric ecosystem. Let’s explore some of the limitations you might encounter when adopting Nushell as your default shell.

The Bad

While the project is still maturing, the active community and ongoing improvements are promising. Don’t get too discouraged by the following, there would be a bad section for any shell imo.
There are many similarities so it can be easy to forget that some Bash (and POSIX in general) style constructs just won’t work in Nushell. Considering that NixOS seems to have been designed for bash, even Zsh isn’t fully compatable you may want to think twice before you choose Nushell as your default.
The documentation is incomplete and written by devs for devs imo, it is quite a bit different from anything else I’ve seen so there is a bit of a learning curve. Nushell is generally still considered to be in a stage where it might not be the most seamless or trouble-free experience as a daily driver default shell for most users, especially on a system like NixOS known for its unique approach.
The any-nix-shell project doesn’t include Nushell as with many others because of it’s lack of maturity.
The following addition comes from Joey_McKur’s sugggestion, on mentioning the job command as one of the biggest criticisms against Nu because it doesn’t support background tasks. I should also note that Nushell’s team is aware of these criticisms and actively working on improving job control.

Limited Feature Set Compared to Traditional Job Control:

Lack of Full POSIX Job Control: Nushell’s job control doesn’t yet fully implement all the features and signals defined by POSIX job control (e.g., more nuanced signal handling, stopped jobs). While it covers the basics, users accustomed to advanced Bash job control might find it lacking.
Foregrounding Behavior: There have been criticisms about how foregrounding jobs interacts with the terminal and potential issues with signal propagation.

Output Handling Challenges:

Interleaved Output: Managing the output of multiple backgrounded jobs can sometimes be messy, with output from different jobs potentially interleaving in the terminal. While Nushell tries to handle this, it’s not always as clean as desired.
Redirection Complexity: Redirecting the input and output of backgrounded jobs can be less straightforward than in Bash, sometimes requiring more explicit handling.

Integration with Pipelines:

Backgrounding Pipelines: Backgrounding complex pipelines with multiple stages can sometimes lead to unexpected behavior or difficulties in managing the entire pipeline as a single job.

Error Reporting:

Difficult to Track Errors in Background Jobs: Identifying and debugging errors in backgrounded jobs can be less direct than with foreground processes, and the job command’s output might not always provide sufficient information for troubleshooting.
Many of Nushell’s challenges stem from its departure from traditional shell conventions, particularly those of Bash, which NixOS heavily relies on. To better understand these differences and how they impact your workflow, let’s compare Nushell’s static, structured approach to Bash’s dynamic, text-based model.

Key Differences Between Nushell & Bash

Feature	Bash (Dynamic)	Nushell (Static)
Code Execution	Line-by-line	Whole script parsed first
Error Detection	Runtime errors only	Catches errors before running
Support for `eval`	✅ Allowed	❌ Not supported
Custom Parsing	Limited	Built-in semantic analysis
IDE Features	Basic syntax highlighting	Advanced integration, linting, and formatting

&& doesn’t work use ; instead.
> is used as the greater-than operator for comparisons:

"hello" | save output.txt

is equivalent to the following in bash:

echo "hello" > output.txt

If you notice above the nushell command doesn’t require an echo prefix, this is because Nushell has Implicit Return:

"Hello, World" == (echo "Hello, World")
# => true

The above example shows that the string, "Hello, World" is equivalent to the output value from echo "Hello, World"
Every Command Returns a Value:

let p = 7
print $p  # 7
$p * 6    # 42

Understanding these differences highlights why Nushell feels so distinct from Bash, but it’s the shell’s advanced features and integrations that truly make it shine. Let’s dive into some of the beautiful and powerful tools and custom commands that elevate Nushell for NixOS users.

The Beautiful and Powerful

Ctrl+t List Commands with carapace and fzf:
Carapace Carapace-Bin Install:

The folling is showing tab completion, I typed hx fl<TAB>:

Carapace man example:

Custom Nushell Commands

Most of the following scripts come from the nu_scripts repo

The following command allows you to choose which input to update interactively with fzf.

✔️ Click to See Command

# nix.nu
# upgrade system packages
# `nix-upgrade` or `nix-upgrade -i`
def nix-upgrade [
  flake_path: string = "/home/jr/flake", # path that contains a flake.nix
  --interactive (-i) # select packages to upgrade interactively
]: nothing -> nothing {
  let working_path = $flake_path | path expand
  if not ($working_path | path exists) {
    echo "path does not exist: $working_path"
    exit 1
  }
  let pwd = $env.PWD
  cd $working_path
  if $interactive {
    let selections = nix flake metadata . --json
    | from json
    | get locks.nodes
    | columns
    | str join "\n"
    | fzf --multi --tmux center,20%
    | lines
    # Debug: Print selections to verify
    print $"Selections: ($selections)"
    # Check if selections is empty
    if ($selections | is-empty) {
      print "No selections made."
      cd $pwd
      return
    }
    # Use spread operator to pass list items as separate arguments
    nix flake update ...$selections
  } else {
    nix flake update
  }
  cd $pwd
  nh os switch $working_path
}

Usage:

nix-upgrade
# or for individual packages
nix-upgrade -i

The ns command is designed to search for Nix packages using nix search and present the results in a cleaner format, specifically removing the architecture and operating system prefix that nix search often includes.

✔️ Click To Expand

def ns [
    term: string # Search target.
] {

    let info = (
        sysctl -n kernel.arch kernel.ostype
        | lines
        | {arch: ($in.0|str downcase), ostype: ($in.1|str downcase)}
    )

    nix search --json nixpkgs $term
        | from json
        | transpose package description
        | flatten
        | select package description version
        | update package {|row| $row.package | str replace $"legacyPackages.($info.arch)-($info.ostype)." ""}
}

Usage:

ns fzf<ENTER>

nufetch command:

✔️ Click To Expand

# `nufetch` `(nufetch).packages`
def nufetch [] {
{
"kernel": $nu.os-info.kernel_version,
"nu": $env.NU_VERSION,
"packages": (ls /etc/profiles/per-user | select name | prepend [[name];
["/run/current-system/sw"]] | each { insert "number" (nix path-info --recursive
 ($in | get name) | lines | length) | insert "size" ( nix path-info -S
 ($in | get name) | parse -r '\s(.*)' | get capture0.0 | into filesize) | update
 "name" ($in | get name | parse -r '.*/(.*)' | get capture0.0 | if $in == "sw"
 {"system"} else {$in}) | rename "environment"}),
"uptime": (sys host).uptime
}
}

duf command, I have mine aliased to df:

ps command:

nix-list-system command lists all installed packages:

# list all installed packages
def nix-list-system []: nothing -> list<string> {
  ^nix-store -q --references /run/current-system/sw
  | lines
  | filter { not ($in | str ends-with 'man') }
  | each { $in | str replace -r '^[^-]*-' '' }
  | sort
}

Usage:

nix-list-system

These custom Nushell commands showcase its flexibility, but sometimes you need to work around Nushell’s limitations, like compatability with certain NixOS tools. This is where just and justfiles come in, simplifying complex workflows and bridging gaps in Nushell’s functionality.

Using Just and Justfiles

The following is my justfile that I keep right next to my flake.nix it simplifies some commands and makes things work that weren’t working with nushell for my case, you’ll have to change it to match your configuration. It’s not perfect but works for my use case, take whats useful and leave the rest.
You’ll first need to install just to make use of justfiles.

# nix shell nixpkgs#just nixpkgs#nushell
set shell := ["nu", "-c"]
flake_path := "/home/jr/flake"
hostname := "magic"
home_manager_output := "jr@magic"

utils_nu := absolute_path("utils.nu")

default:
    @just --list
# Rebuild
[group('nix')]
fr:
    nh os switch --hostname {{hostname}} {{flake_path}}

# Flake Update
[group('nix')]
fu:
    nh os switch  --hostname {{hostname}} --update {{flake_path}}

# Update specific input
# Usage: just upp nixpkgs
[group('nix')]
upp input:
    nix flake update {{input}}
# Test
[group('nix')]
ft:
    nh os test --hostname {{hostname}} {{flake_path}}
# Collect Garbage
[group('nix')]
ncg:
    nix-collect-garbage --delete-old ; sudo nix-collect-garbage -d ; sudo /run/current-system/bin/switch-to-configuration boot

[group('nix')]
cleanup:
    nh clean all

To list available commands type, (you must be in the same directory as the justfile): just

So just fmt will run nix fmt.
A lot of the .nu files came from this repo by BlindFS:
- modern-dot-files he uses Nix Darwin so there are a few changes for NixOS. I found this through this_week_in_nu.
- my-nu-config If you use this, you’ll need to change the first line of fzf.nu to the location of your config. You’ll also need to change the constants at the top of config.nu. These are my old dotfiles, I have recently updated and made sure this config is up to date with recent nushell changes. Also, change the let flake_path = ($env.HOME | path join "flake") to your flake path.
- The examples use this starship configAylur-dotfiles The logic on the bottom enables starship for Nushell, Zsh, and Bash!
- If you wan’t to use my config you’ll have to enable the experimental-feature pipe-operators in the same place you enable flakes and nix-command.
There are still situations where I need to switch to zsh or bash to get something to work i.e. nix-shell and a few others.
From custom commands to justfile integrations, Nushell offers a wealth of tools to enhance your NixOS experience, even if occasional workarounds are needed. To dive deeper into Nushell and tailor it to your needs, here are some valuable resources to explore, from official documentation to community-driven configurations.

Resources

✔️ Click to Expand Resources

Nushell-Book
Nushell-Cookbook
nu_scripts some of the custom commands came from here.
nushell sample-config
awesome-nu repo
nu showcase-repo
discord You can find custom commands, configurations, etc here.

Intro to Derivations

2025-11-29T00:00:00+00:00

Chapter 7

✔️ Click to Expand Table of Contents

Introduction to Nix Derivations

Nix’s build instructions, known as derivations, are defined using the Nix Language. These derivations can describe anything from individual software packages to complete system configurations. The Nix package manager then deterministically “realizes” (builds) these derivations, ensuring consistency because they rely solely on a predefined set of inputs.

Most things in NixOS are built around derivations. Your NixOS system is described by such a single system derivation. When you want to apply a new configuration, nixos-rebuild handles the process:

It first builds this derivation:

nix-build '<nixpkgs/nixos>' -A system

Then, once the build is complete, it switches to that new system:

result/bin/switch-to-configuration

After the build, nixos-rebuild updates a crucial symbolic link: /run/current-system This symlink always points to the active, running version of your system in the Nix store. In essence, the /run/current-system path is the currently active system derivation. This design choice gives NixOS its powerful atomic upgrade and rollback capabilities: changing your system involves building a new system derivation and updating this symlink to point to the latest version.

 ls -lsah /run/current-system
 0 lrwxrwxrwx 1 root root 85 May 23 12:11 /run/current-system -> /nix/store/
 cy2c0kxpjrl7ajlg9v3zh898mhj4dyjv-nixos-system-magic-25.11.20250520.2795c50

The -> indicates a symlink and it’s pointing to a store path which is the result of a derivation being built (the system closure)
For beginners, the analogy of a cooking recipe is helpful:
- Ingredients (Dependencies): What other software or libraries are needed.
- Steps (Build Instructions): The commands to compile, configure, and install.
- Final Dish (Output): The resulting package or resource.

A Nix derivation encapsulates all this information, telling Nix what inputs to use, how to build it, and what the final output should be.

Nix derivations run in pure, isolated environments, meaning they cannot access the internet during the build phase. This ensures that builds are reproducible – they don’t depend on external sources that might change over time.

There are Fixed-output-derivations that allow fetching resources during the build process by explicitly specifying the expected hash upfront. Just keep this in mind that normal derivations don’t have network access.

Creating Derivations in Nix

The primary way to define packages in Nix is through the mkDerivation function, which is part of the standard environment (stdenv). While a lower-level derivation function exists for advanced use cases, mkDerivation simplifies the process by automatically managing dependencies and the build environment.

mkDerivation (and derivation) takes a set of attributes as its argument. At a minimum, you’ll often encounter these essential attributes:

name: A human-readable identifier for the derivation (e.g., “foo”, “hello.txt”). This helps you and Nix refer to the package.
system: Specifies the target architecture for the build (e.g., builtins.currentSystem for your current machine).
builder: Defines the program that will execute the build instructions (e.g., bash).

How do we pass these required attributes to the derivation function?

Functions in Nix often take a single argument which is an attribute set. For derivation and mkDerivation, this takes the form functionName { attribute1 = value1; attribute2 = value2; ... }, where the {} encloses the set of attributes being passed as the function’s argument.

Remember that derivation and mkDerivation take a set (i.e. {}) of attributes as its first argument. So, in order to pass the required attributes you would do something like this:

nix-repl> pkgs = import <nixpkgs> {}

nix-repl> d = derivation {
            name = "mydrv";
            builder = "${pkgs.bash}/bin/bash";
            args = [
              "-c" # Tells bash to execute the following string as a command
              ''
                # Explicitly set PATH to include coreutils bin directory
                export PATH="${pkgs.coreutils}/bin:$PATH"
                mkdir $out
              ''
            ];
            system = builtins.currentSystem;
          }

nix-repl> :b d

When I was starting out, seeing the above written in the following format made it clearer in my mental map that we were passing these attributes as arguments but both accomplish the same thing.

d = derivation { name = "myname"; builder = "${coreutils}/bin/true"; system = builtins.currentSystem; }

When you write pkgs = import <nixpkgs> {};, you are importing the Nixpkgs default.nix file, which resolves to a function. Calling that function by passing it an empty attribute set {} as its argument. The function then evaluates and returns the entire pkgs attribute set. To specify a different system for example, you could do something like:

pkgsForAarch64 = import <nixpkgs> { system = "aarch64-linux"; };

So when you see:

import <nixpkgs> { overlays = []; config = {}; }

Instead, these empty sets explicitly override any global or implicit overlays/configurations that Nix might otherwise pick up from environment variables (like NIXPKGS_CONFIG), default locations (like ~/.config/nixpkgs/config.nix or ~/.config/nixpkgs/overlays), or other mechanisms.
This is to prevent accidental partial application from other parts of your configuration and is saying “Do not pass any custom configuration options for this particular import”
derivation is a pre-made, built-in function in the Nix language. Here, we are passing it an attribute set as argument with the three required attributes. (name, builder, system, and we added an extra argument args.)

The Hello World Derivation

For this example, first create a hello directory and add the Hello tarball to said directory.

Now lets create the classic Hello derivation:

# hello.nix
let
  pkgs = import <nixpkgs> { };
in
derivation {
  name = "hello";
  builder = "${pkgs.bash}/bin/bash";
  args = [ ./hello_builder.sh ];
  inherit (pkgs)
    gnutar
    gzip
    gnumake
    gcc
    coreutils
    gawk
    gnused
    gnugrep
    ;
  bintools = pkgs.binutils.bintools;
  src = ./hello-2.12.1.tar.gz;
  system = builtins.currentSystem;
}

As you can see, this isn’t the only required file but is a recipe outlining how to build the hello package. The tar.gz package can be found here You would just place the tarball in the same directory as the derivation along with the following hello_builder.sh:

# hello_builder.sh
export PATH="$gnutar/bin:$gcc/bin:$gnumake/bin:$coreutils/bin:$gawk/bin:$gzip/bin:$gnugrep/bin:$gnused/bin:$bintools/bin"
tar -xzf $src
cd hello-2.12.1
./configure --prefix=$out
make
make install

And build it with:

nix-build hello.nix

Finally execute it with:

./result/bin/hello
Hello, world!

Simple Rust Derivation

Create a simple.rs with the following contents:

fn main() {
  println!("Simple Rust!")
}

And a rust_builder.sh like this (this is our builder script):

# rust_builder.sh
# Set up the PATH to include rustc coreutils and gcc
export PATH="$rustc/bin:$coreutils/bin:$gcc/bin"

# IMPORTANT: Create the $out directory BEFORE rustc tries to write to it
mkdir -p "$out"

# Compile the Rust source code and place the executable inside $out
rustc -o "$out/simple_rust" "$src"

Now we’ll enter the nix repl and build it:

❯ nix repl
Nix 2.28.3
Type :? for help.

nix-repl> :l <nixpkgs>
added 3950 variables.

# Define the variables for rustc, coreutils, bash, AND gcc from the loaded nixpkgs
nix-repl> rustc = pkgs.rustc

nix-repl> coreutils = pkgs.coreutils

nix-repl> bash = pkgs.bash

nix-repl> gcc = pkgs.gcc

# Now define the derivation
nix-repl> simple_rust_program = derivation {
            name = "simple-rust-program";
            builder = "${bash}/bin/bash";
            args = [ ./rust_builder.sh ];
            rustc = rustc;
            coreutils = coreutils;
            gcc = gcc;
            src = ./simple.rs;
            system = builtins.currentSystem;
          }

nix-repl> :b simple_rust_program
This derivation produced the following outputs:
out -> /nix/store/fmyqr2d3ph0lpnxd0xppwvwyhv3iyb7y-simple-rust-program

nix-store -r /nix/store/fmyqr2d3ph0lpnxd0xppwvwyhv3iyb7y-simple-rust-program

warning: you did not specify '--add-root'; the result might be removed by the garbage collector
/nix/store/fmyqr2d3ph0lpnxd0xppwvwyhv3iyb7y-simple-rust-program

This simple Rust example, built with a direct derivation call, illustrates:

How Nix explicitly manages every single tool in your build environment (bash, rustc, gcc, coreutils).
The strict isolation of Nix builds, where nothing is implicitly available.
The deterministic mapping of inputs to unique output paths in the Nix store.
The above example shows the fundamental structure of a Nix derivation, how it’s defined within the nix-repl.
.drv files are intermediate files that describe how to build a derivation; it’s the bare minimum information.

When Derivations are Built

Nix doesn’t build derivations during the evaluation of your Nix expressions. Instead, it processes your code in two main phases (and why you need to use :b simple_rust_program or nix-store -r to actually build or realize it):

Evaluation/Instantiate Phase: This is when Nix parses and interprets your .nix expression. The result is a precise derivation description (often represented as a .drv file on disk), and the unique “out paths” where the final built products will go are calculated. No actual code is compiled or executed yet. Achieved with nix-instantiate
Realize/Build Phase: Only after a derivation has been fully described does Nix actually execute its build instructions. It first ensures all the derivation’s inputs (dependencies) are built, then runs the builder script in an isolated environment, and places the resulting products into their designated “out paths” in the Nix store. Achieved with nix-store -r

Referring to other derivations

The way that we can refer to other packages/derivations is to use the outPath.

The outPath describes the location of the files of that derivation. Nix can then convert the derivation set into a string:

nix repl
nix-repl> :l <nixpkgs>
nix-repl> fzf
«derivation /nix/store/vw1zag9q4xvf10z24j1qybji7wfsz78v-fzf-0.62.0.drv»
nix-repl> fzf.outPath
"/nix/store/z3ayhjslz72ldiwrv3mn5n7rs96p2g8a-fzf-0.62.0"
nix-repl> builtins.toString fzf
"/nix/store/z3ayhjslz72ldiwrv3mn5n7rs96p2g8a-fzf-0.62.0"

As long as there is an outPath attribute, Nix will do the “set to string conversion”.

Produce a development shell from a derivation

Building on the concept of a derivation as a recipe, let’s create our first practical derivation. This example shows how to define a temporary development environment (a shell) using stdenv.mkDerivation, which is the primary function for defining packages in Nix.

# my-shell.nix
# We use a `let` expression to bring `pkgs` and `stdenv` into scope.
# This is a recommended practice over `with import <nixpkgs> {}`
# for clarity and to avoid potential name collisions.
let
  pkgs = import <nixpkgs> {};
  stdenv = pkgs.stdenv; # Access stdenv from the imported nixpkgs
in

# Make a new "derivation" that represents our shell
stdenv.mkDerivation {
  name = "my-environment";

  # The packages in the `buildInputs` list will be added to the PATH in our shell
  buildInputs = [
    # cowsay is an arbitrary package
    # see https://nixos.org/nixos/packages.html to search for more
    pkgs.cowsay
    pkgs.fortune
  ];
}

Usage

nix-shell my-shell.nix
fortune | cowsay
 _________________________________________
/ "Lines that are parallel meet at        \
| Infinity!" Euclid repeatedly, heatedly, |
| urged.                                  |
|                                         |
| Until he died, and so reached that      |
| vicinity: in it he found that the       |
| damned things diverged.                 |
|                                         |
\ -- Piet Hein                            /
 -----------------------------------------
        \   ^__^
         \  (oo)\_______
            (__)\       )\/\
                ||----w |
                ||     ||

To exit type: exit

This Nix expression defines a temporary development shell. Let’s break it down:

pkgs = import <nixpkgs> {};: Standard way to get access to all the packages and helper functions (i.e. nixpkgs.lib)
stdenv = pkgs.stdenv;: stdenv provides us mkDerivation and is from the nixpkgs collection.
stdenv.mkDerivation { ... };: This is the core function for creating packages.
- stdenv provides a set of common build tools and conventions.
mkDerivation takes an attribute set (a collection of key-value pairs) as its argument.
name = "my-environment";: This gives your derivation a human-readable name.
buildInputs = [ pkgs.cowsay ];: This is a list of dependencies that will be available in the build environment of this derivation (or in the PATH if you enter the shell created by this derivation). pkgs.cowsay refers to the cowsay package from the imported pkgs collection.

The command nix-instantiate --eval my-shell.nix evaluates the Nix expression in the file. It does not build the derivation. Instead, it returns the Nix value that the expression evaluates to.

nix-instantiate --eval my-shell.nix

This value is a structured data type that encapsulates all the attributes (like name, system, buildInputs, etc.) required to build the derivation. Your output shows this detailed internal representation of the derivation’s “recipe” as understood by Nix. This is useful for debugging and inspecting the derivation’s definition.

Our Second Derivation: Understanding the Builder

Understanding the Builder (Click to Expand)

To understand how derivations work, let’s create a very basic example using a bash script as our builder.

Why a Builder Script?

The builder attribute in a derivation tells Nix how to perform the build steps. A simple and common way to define these steps is with a bash script.

The Challenge with Shebangs in Nix

In typical Unix-like systems, you might start a bash script with a shebang (#!/bin/bash or #!/usr/bin/env bash) to tell the system how to execute it. However, in Nix derivations, we generally avoid this.
Reason: Nix builds happen in an isolated environment where the exact path to common tools like bash isn’t known beforehand (it resides within the Nix store). Hardcoding a path or relying on the system’s PATH would break Nix’s stateless property.

The Importance of Statelessness in Nix

Stateful Systems (Traditional): When you install software traditionally, it often modifies the core system environment directly. This can lead to dependency conflicts and makes rollbacks difficult.
Stateless Systems (Nix): Nix takes a different approach. When installing a package, it creates a unique, immutable directory in the Nix store. This means:
- No Conflicts: Different versions of the same package can coexist without interfering with each other.
- Reliable Rollback: You can easily switch back to previous versions without affecting system-wide files.
- Reproducibility: Builds are more likely to produce the same result across different machines if they are “pure” (don’t rely on external system state).

The Isolated Nix Build Environment: A Quick Overview

When Nix executes a builder script, it sets up a highly controlled and pristine environment to ensure reproducibility and isolation. Here’s what happens:

Fresh Start: Nix creates a temporary, empty directory for the build and makes it the current working directory.
Clean Environment: It completely clears the environment variables from your shell.
Controlled Inputs: Nix then populates the environment with only the variables essential for the build, such as:
- $NIX_BUILD_TOP: The path to the temporary build directory.
- $PATH: Carefully set to include only the explicit buildInputs you’ve specified, preventing reliance on arbitrary system tools.
- $HOME: Set to /homeless-shelter to prevent programs from reading user-specific configuration files.
- Variables for each declared output ($out, etc.), indicating where the final results should be placed in the Nix store.
Execution & Logging: The builder script is run with its specified arguments. All its output (stdout/stderr) is captured in a log.
Clean Up & Registration: If successful, the temporary directory is removed. Nix then scans the build outputs for references to other store paths, ensuring all dependencies are correctly tracked for future use and garbage collection. Finally, it normalizes file permissions and timestamps in the output for consistent hashing.

This meticulous setup ensures that your builds are independent of the machine they run on and always produce the same result, given the same inputs.

Our builder Script

For our first derivation, we’ll create a simple builder.sh file in the current directory:

# builder.sh
declare -xp
echo foo > $out

The command declare -xp lists exported variables (it’s a bash builtin function).
Nix needs to know where the final built product (the “cake” in our earlier analogy) should be placed. So, during the derivation process, Nix calculates a unique output path within the Nix store. This path is then made available to our builder script as an environment variable named $out. The .drv file, which is the recipe, contains instructions for the builder, including setting up this $out variable. Our builder script will then put the result of its work (in this case, the “foo” file) into this specific $out directory.
As mentioned earlier we need to find the nix store path to the bash executable, common way to do this is to load Nixpkgs into the repl and check:

nix-repl> :l <nixpkgs>
Added 3950 variables.
nix-repl> "${bash}"
"/nix/store/ihmkc7z2wqk3bbipfnlh0yjrlfkkgnv6-bash-4.2-p45"

So, with this little trick we are able to refer to bin/bash and create our derivation:

nix-repl> d = derivation { name = "foo"; builder = "${bash}/bin/bash";
 args = [ ./builder.sh ]; system = builtins.currentSystem; }
nix-repl> :b d
[1 built, 0.0 MiB DL]

this derivation produced the following outputs:
  out -> /nix/store/gczb4qrag22harvv693wwnflqy7lx5pb-foo

The contents of the resulting store path (/nix/store/...-foo) now contain the file foo, as intended. We have successfully built a derivation!
Derivations are the primitive that Nix uses to define packages. “Package” is a loosely defined term, but a derivation is simply the result of calling builtins.derivation.

Our Last Derivation

Create a new directory and a hello.nix with the following contents:

# hello.nix
{
  stdenv,
  fetchzip,
}:

stdenv.mkDerivation {
  pname = "hello";
  version = "2.12.1";

  src = fetchzip {
    url = "https://ftp.gnu.org/gnu/hello/hello-2.12.1.tar.gz";
    sha256 = "";
  };
}

Save this file to hello.nix and run nix-build to observe the build failure:

Click to expand output:

$ nix-build hello.nix
~error: cannot evaluate a function that has an argument without a value ('stdenv')
~       Nix attempted to evaluate a function as a top level expression; in
~       this case it must have its arguments supplied either by default
~       values, or passed explicitly with '--arg' or '--argstr'. See
~       https://nix.dev/manual/nix/stable/language/constructs.html#functions.
~
~       at /home/nix-user/hello.nix:3:3:
~
~            2| {
~            3|   stdenv,
~             |   ^
~            4|   fetchzip,

Problem: The expression in hello.nix is a function, which only produces it’s intended output if it is passed the correct arguments.(i.e. stdenv is available from nixpkgs so we need to import nixpkgs before we can use stdenv):

The recommended way to do this is to create a default.nix file in the same directory as the hello.nix with the following contents:

# default.nix
let
  nixpkgs = fetchTarball "https://github.com/NixOS/nixpkgs/tarball/nixos-24.05";
  pkgs = import nixpkgs { config = {}; overlays = []; };
in
{
  hello = pkgs.callPackage ./hello.nix { };
}

This allows you to run nix-build -A hello to realize the derivation in hello.nix, similar to the current convention used in Nixpkgs:

Click to expand Output:

nix-build -A hello
~error: hash mismatch in fixed-output derivation '/nix/store/pd2kiyfa0c06giparlhd1k31bvllypbb-source.drv':
~         specified: sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=
~            got:    sha256-1kJjhtlsAkpNB7f6tZEs+dbKd8z7KoNHyDHEJ0tmhnc=
~error: 1 dependencies of derivation '/nix/store/b4mjwlv73nmiqgkdabsdjc4zq9gnma1l-hello-2.12.1.drv' failed to build

Another way to do this is with nix-prefetch-url It is a utility to calculate the sha beforehand.

nix-prefetch-url https://ftp.gnu.org/gnu/hello/hello-2.12.1.tar.gz
path is '/nix/store/pa10z4ngm0g83kx9mssrqzz30s84vq7k-hello-2.12.1.tar.gz'
086vqwk2wl8zfs47sq2xpjc9k066ilmb8z6dn0q6ymwjzlm196cd

When you use nix-prefetch-url, you get a Base32 hash when nix needs SRI format.

Run the following command to convert from Base32 to SRI:

nix hash to-sri --type sha256 086vqwk2wl8zfs47sq2xpjc9k066ilmb8z6dn0q6ymwjzlm196cd
sha256-jZkUKv2SV28wsM18tCqNxoCZmLxdYH2Idh9RLibH2yA=

This actually fetched a different sha than the Nix compiler returned in the example where we replace the empty sha with the one Nix gives us. The difference was that fetchzip automatically extracts archives before computing the hash and slight differences in the metadata cause different results. I had to switch from fetchzip to fetchurl to get the correct results.
- Extracted archives can differ in timestamps, permissions, or compression details, causing different hash values.
- A simple takeaway is to use fetchurl when you need an exact match, and fetchzip when working with extracted contents.
- fetchurl
- fetchurl returns a fixed-output derivation(FOD): A derivation where a cryptographic hash of the output is determined in advance using the outputHash attribute, and where the builder executable has access to the network.

Lastly replace the empty sha256 placeholder with the returned value from the last command:

# hello.nix
{
  stdenv,
  fetchzip,
}:

stdenv.mkDerivation {
  pname = "hello";
  version = "2.12.1";

  src = fetchzip {
    url = "https://ftp.gnu.org/gnu/hello/hello-2.12.1.tar.gz";
    sha256 = "sha256-1kJjhtlsAkpNB7f6tZEs+dbKd8z7KoNHyDHEJ0tmhnc=";
  };
}

Run nix-build -A hello again and you’ll see the derivation successfully builds.

Best Practices

Reproducible source paths: If we built the following derivation in /home/myuser/myproject then the store path of src will be /nix/store/<hash>-myproject causing the build to no longer be reproducible:

let pkgs = import <nixpkgs> {}; in

pkgs.stdenv.mkDerivation {
  name = "foo";
  src = ./.;
}

❗ TIP: Use builtins.path with the name attribute set to something fixed. This will derive the symbolic name of the store path from the name instead of the working directory:
let pkgs = import <nixpkgs> {}; in

pkgs.stdenv.mkDerivation {
  name = "foo";
  src = builtins.path { path = ./.; name = "myproject"; };
}

Conclusion

In this chapter, we’ve laid the groundwork for understanding Nix derivations, the fundamental recipes that define how software and other artifacts are built within the Nix ecosystem. We’ve explored their key components – inputs, builder, build phases, and outputs – and how they contribute to Nix’s core principles of reproducibility and isolated environments. Derivations are the workhorses behind the packages and tools we use daily in Nix.

As you’ve learned, derivations offer a powerful and principled approach to software management. However, the way we organize and manage these derivations, along with other Nix expressions and dependencies, has evolved over time. Traditionally, Nix projects often relied on patterns involving default.nix files, channel subscriptions, and manual dependency management.

A more recent and increasingly popular approach to structuring Nix projects and managing dependencies is through Nix Flakes. Flakes introduce a standardized project structure, explicit input tracking, and a more robust way to ensure reproducible builds across different environments.

In our next chapter, Comparing Flakes and Traditional Nix, we will directly compare and contrast these two approaches. We’ll examine the strengths and weaknesses of traditional Nix practices in contrast to the benefits and features offered by Nix Flakes. This comparison will help you understand the motivations behind Flakes and when you might choose one approach over the other for your Nix projects.

As you can see below, there is a ton of information on derivations freely available.

Links To Articles about Derivations

Click To Expand Resources

Flake Inputs

2025-11-28T00:00:00+00:00

Nix Flake Inputs

✔️ Click to Expand Table of Contents

The attribute inputs specifies the dependencies of a flake, as an attrset mapping input names to flake references.

If a repository provides a flake.nix you can include it as an input in your flake.nix.

For example, I like yazi as my file explorer and have been using helix as my editor. To be able to get yazi to work with helix I needed the latest versions of both yazi and helix. One way to get the latest versions was to add their flakes as inputs to my flake:

{
	inputs = {
		nixpkgs.url = "github:NixOS/nixpkgs/nixos-24.11";
		home-manager = {
			url = "github:nix-community/home-manager/release-24.11";
			inputs.nixpkgs.follows = "nixpkgs";
		};
    helix = {
      url = "github:helix-editor/helix";
      inputs.nixpkgs.follows = "nixpkgs";
    };
		yazi.url = "github:sxyazi/yazi";
	};
	outputs = { nixpkgs, home-manager, ... } @ inputs: {
	# ... snip ... #

Now to use this input, I would reference these inputs in both my yazi and helix modules:

# yazi.nix
{ pkgs, config, inputs, ... }: {
	programs.yazi = {
		enable = true;
		package = inputs.yazi.packages.${pkgs.system}.default;
	};
}

# helix.nix
{ pkgs, config, inputs, ... }: {
	programs.helix = {
		enable = true;
		package = inputs.helix.packages.${pkgs.system}.helix;
	};
}

Understanding .default vs. Named Outputs (e.g., .helix) from the Source

The difference between inputs.yazi.packages.${pkgs.system}.default and inputs.helix.packages.${pkgs.system}.helix comes down to how the respective upstream flakes define their outputs. You can always inspect a flake’s flake.nix or use nix flake show <flake-reference> to understand its structure.

Helix `flake.nix`

Let’s look at the relevant section of Helix’s flake.nix click the eye to see the full flake:

~ {
~   description = "A post-modern text editor.";
~
~   inputs = {
~     nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
~     rust-overlay = {
~       url = "github:oxalica/rust-overlay";
~       inputs.nixpkgs.follows = "nixpkgs";
~     };
~   };
~
~   outputs = {
~     self,
~     nixpkgs,
~     rust-overlay,
~     ...
~   }: let
~     inherit (nixpkgs) lib;
~     systems = [
~       "x86_64-linux"
~       "aarch64-linux"
~       "x86_64-darwin"
~       "aarch64-darwin"
~     ];
~     eachSystem = lib.genAttrs systems;
~     pkgsFor = eachSystem (system:
~       import nixpkgs {
~         localSystem.system = system;
~         overlays = [(import rust-overlay) self.overlays.helix];
~       });
~     gitRev = self.rev or self.dirtyRev or null;
   in {
     packages = eachSystem (system: {
       inherit (pkgsFor.${system}) helix;
       /*
       The default Helix build. Uses the latest stable Rust toolchain, and unstable
       nixpkgs.

       The build inputs can be overridden with the following:

       packages.${system}.default.override { rustPlatform = newPlatform; };

       Overriding a derivation attribute can be done as well:

       packages.${system}.default.overrideAttrs { buildType = "debug"; };
       */
      default = self.packages.${system}.helix;
    });
~    checks =
~      lib.mapAttrs (system: pkgs: let
~        # Get Helix's MSRV toolchain to build with by default.
~        msrvToolchain = pkgs.pkgsBuildHost.rust-bin.fromRustupToolchainFile ./rust-toolchain.toml;
~        msrvPlatform = pkgs.makeRustPlatform {
~          cargo = msrvToolchain;
~          rustc = msrvToolchain;
~        };
~      in {
~        helix = self.packages.${system}.helix.override {
~          rustPlatform = msrvPlatform;
~        };
~      })
~      pkgsFor;
~
~    # Devshell behavior is preserved.
~    devShells =
~      lib.mapAttrs (system: pkgs: {
~        default = let
~          commonRustFlagsEnv = "-C link-arg=-fuse-ld=lld -C target-cpu=native --cfg tokio_unstable";
~          platformRustFlagsEnv = lib.optionalString pkgs.stdenv.isLinux "-Clink-arg=-Wl,--no-rosegment";
~        in
~          pkgs.mkShell {
~            inputsFrom = [self.checks.${system}.helix];
~            nativeBuildInputs = with pkgs;
~              [
~                lld
~                cargo-flamegraph
~                rust-bin.nightly.latest.rust-analyzer
~              ]
~              ++ (lib.optional (stdenv.isx86_64 && stdenv.isLinux) cargo-tarpaulin)
~              ++ (lib.optional stdenv.isLinux lldb)
~              ++ (lib.optional stdenv.isDarwin darwin.apple_sdk.frameworks.CoreFoundation);
~            shellHook = ''
~              export RUST_BACKTRACE="1"
~              export RUSTFLAGS="''${RUSTFLAGS:-""} ${commonRustFlagsEnv} ${platformRustFlagsEnv}"
~            '';
~          };
~      })
~      pkgsFor;
~
~    overlays = {
~      helix = final: prev: {
~        helix = final.callPackage ./default.nix {inherit gitRev;};
~      };
~
~      default = self.overlays.helix;
~    };
~  };
~  nixConfig = {
~    extra-substituters = ["https://helix.cachix.org"];
~    extra-trusted-public-keys = ["helix.cachix.org-1:ejp9KQpR1FBI2onstMQ34yogDm4OgU2ru6lIwPvuCVs="];
~  };
~}

Dissecting inherit (pkgsFor.${system}) helix;

Imagine the Nix evaluation process for Helix flake.nix in the outputs section:

packages = eachSystem (system: { ... }); Part iterates through each system (like x86_64-linux). For each system, it’s creating an attribute set that will become self.packages.${system}.
Inside the eachSystem function, for a specific system (e.g. x86_64-linux): The code is building an attribute set that will ultimately be assigned to self.packages.x86_64-linux.
When you write inherit (sourceAttrset) attributeName;, it’s equivalent to writing attributeName = sourceAttrset.attributeName;.

So, inherit (pkgsFor.${system}) helix; is equivalent to:

helix = pkgsFor.${system}.helix;

Therefore, because of inherit (pkgsFor.${system}) helix;, the helix attribute is explicitly defined under packages.${system}``. This is why you access it as inputs.helix.packages.${pkgs.system}.helix;`.

Yazi `flake.nix`

Now this is yazi’s flake.nix, yazi’s documentation tells you to use .default but lets examine the flake and see why:

~{
~  inputs = {
~    nixpkgs.url = "github:NixOS/nixpkgs/nixpkgs-unstable";
~    flake-utils.url = "github:numtide/flake-utils";
~    rust-overlay = {
~      url = "github:oxalica/rust-overlay";
~      inputs.nixpkgs.follows = "nixpkgs";
~    };
~  };
~
~  outputs =
~    {
~      self,
~      nixpkgs,
~      rust-overlay,
~      flake-utils,
~      ...
~    }:
~    flake-utils.lib.eachDefaultSystem (
~      system:
~      let
~        pkgs = import nixpkgs {
~          inherit system;
~          overlays = [ rust-overlay.overlays.default ];
~        };
~        toolchain = pkgs.rust-bin.stable.latest.default;
~        rustPlatform = pkgs.makeRustPlatform {
~          cargo = toolchain;
~          rustc = toolchain;
~        };
~
~        rev = self.shortRev or self.dirtyShortRev or "dirty";
~        date = self.lastModifiedDate or self.lastModified or "19700101";
~        version =
~          (builtins.fromTOML (builtins.readFile ./yazi-fm/Cargo.toml)).package.version
~          + "pre${builtins.substring 0 8 date}_${rev}";
~      in
      {
        packages = {
          yazi-unwrapped = pkgs.callPackage ./nix/yazi-unwrapped.nix {
            inherit
              version
              rev
              date
              rustPlatform
              ;
          };
          yazi = pkgs.callPackage ./nix/yazi.nix { inherit (self.packages.${system}) yazi-unwrapped; };
          default = self.packages.${system}.yazi;
        };

~        devShells = {
~          default = pkgs.callPackage ./nix/shell.nix { };
~        };
~
~        formatter = pkgs.nixfmt-rfc-style;
~      }
~    )
~    // {
~      overlays = {
~        default = self.overlays.yazi;
~        yazi = _: prev: { inherit (self.packages.${prev.stdenv.system}) yazi yazi-unwrapped; };
~      };
~    };
~}

In this case using inputs.yazi.packages.${pkgs.system}.yazi would also work

yazi = pkgs.callPackage ./nix/yazi.nix { inherit (self.packages.${system}) yazi-unwrapped; }; This line defines the yazi variable (or, more precisely, creates an attribute named yazi within the packages.${system} set). It assigns to this yazi attribute the result of calling the Nix expression in ./nix/yazi.nix with yazi-unwrapped as an argument. This yazi attribute represents the actual, runnable Yazi package.
default = self.packages.${system}.yazi; This line then aliases the yazi package. It creates another attribute named default within the same packages.${system} set and points it directly to the yazi attribute that was just defined.
So, when you access inputs.yazi.packages.${pkgs.system}.default, you’re effectively following the alias to the yazi package.
The choice to use .default is primarily for convenience and adherence to a common flake convention, making the flake easier for users to consume without needing to dive into its internal structure.

Flake outputs

2025-11-28T00:00:00+00:00

Nix Flake Outputs

✔️ Click to Expand Table of Contents

Flake outputs are what the flake produces when built. Flakes can have multiple outputs simultaneously such as:

Packages: Self-contained bundles that are built using derivations and provide either some kind of software or dependencies of software.
NixOS modules
Nix development environments
Nix templates
The outputs top-level attribute is actually a function that takes an attribute set of inputs and returns an attribute set that is essentially a recipe for building the flake.

Output Schema

Once the inputs are resolved, they’re passed to the outputs attribute. This outputs attribute is, in fact, a function, as indicated by the : colon (or the lambda syntax) that follows its definition. This function takes the resolved inputs (and self, the flake’s directory in the store) as arguments, and its return value dictates the outputs of the flake, following this schema:

{ self, nixpkgs, ... }@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 = ""; };
}

The first line { self, nixpkgs, ... }@ inputs: defines the functions parameters: It’s important to understand that within the scope of the outputs function nixpkgs is available at the top-level because we explicitly passed it as an argument but for individual modules outside this flake the scope is lost, and you need to use inputs.nixpkgs (or equivalent)

It explicitly names the self attribute, making it directly accessible. The variadic ... ellipses part of the function signature is what allows all your flake inputs to be brought into the function’s scope without having to list each one explicitly.
It destructures all other attributes (your defined inputs) into the functions scope.
It gives you a convenient single variable, inputs, that refers to the entire attribute set passed to the outputs function. This allows you to access inputs either individually (e.g. nixpkgs) or through the inputs variable (e.g. inputs.nixpkgs).

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

As you can see, the majority of the outputs within the outputs schema expect a derivation. This means that for packages, applications, formatters, checks, and development shells, you’ll be defining a Nix derivation—a set of instructions that tells Nix how to build a particular software component. This is central to Nix’s declarative nature.

The command nix flake show, takes a flake URI and prints all the outputs of the flake as a nice tree structure, mapping attribute paths to the types of values.

  ~/players/third  3s
❯ nix flake show
path:/home/jr/players/third?lastModified=1748272555&narHash=sha256-oNzkC6X9hA0MpOBmJSZ89w4znXxv4Q5EkFhp0ewehY0%3D
├───nixosConfigurations
│   └───testing: NixOS configuration
└───nixosModules
    └───default: NixOS module

To show you the structure of this little flake project:

  ~/players
❯ tree
 .
├──  first
│   ├──  flake.lock
│   ├──  flake.nix
│   └──  result -> /nix/store/701vyaanmqchd2nnaq71y65v8ws11zx0-nixos-system-nixos-24.11.20250523.f09dede
├──  second
│   ├──  flake.lock
│   └──  flake.nix
└──  third
    ├──  flake.lock
    ├──  flake.nix
    └──  result -> /nix/store/mlszr5ws3xaly8m4q9jslgs31w6w76y2-nixos-system-nixos-24.11.20250523.f09dede

Simple Example providing an output

# flake.nix
{
  outputs = { self }: {
    bada = "bing";
  };
}

You can then evaluate this specific output using nix eval:

nix eval .#bada
"bing"

Outputs understood by Nix

While the attribute set that outputs returns may contain arbitrary attributes, meaning any valid Nix value. Some of the standard outputs are understood by various nix utilities. packages is one of these:

# flake.nix
{
  inputs = {
    nixpkgs.url = "github:nixos/nixpkgs";
  };

  outputs = { self, nixpkgs }: {
    # this is the re-exporting part!
    packages.x86_64-linux.hello = nixpkgs.legacyPackages.x86_64-linux.hello;
  };
}

Re-exporting happens when you take the value of hello in its standard derivation format, exactly as nixpkgs produces it and assign it to an attribute in your own flake’s outputs.
- packages.x86_64-linux.hello(your flake’s output path) = nixpkgs.legacyPackages.x86_64-linux.hello(the source from the nixpkgs flake’s output)
- We’re saying, My flakes hello package is exactly the same as the hello package found inside the nixpkgs input flake.
- It’s important to understand that within the scope of the outputs function (i.e. within your flake), nixpkgs is available at the top-level (i.e. the = nixpkgs part) because we explicitly passed it as an argument but for individual modules outside of this flake the scope is lost, and inputs.nixpkgs is needed.

The following command builds the reexported package:

nix build .#hello

or run it with:

nix run .#hello

You might notice x86_64-linux appearing in the package path, and there’s a good reason for it. Flakes are designed to provide hermetic evaluation, meaning their outputs should be identical regardless of the environment where they’re built. A key factor in any build system is the platform (which combines the architecture and operating system, like x86_64-linux or aarch64-darwin).

Because of Nix’s commitment to reproducibility across different systems, any flake output that involves building software packages must explicitly specify the platform. The standard approach is to structure these outputs as an attribute set where the names are platforms, and the values are the outputs specific to that platform. For the packages output, each platform-specific value is itself an attribute set containing the various packages built for that particular system.

Exporting Functions

This example outputs a sayGoodbye function, via the lib attribute, that takes a name for its input and outputs a string saying Goodbye very nicely to the person with that name:

{
  outputs = { self }: {
    lib = {
      sayGoodbye = name: "Goodbye F*** Off, ${name}!";
    };
  };
}

You could then specify this flake as an input to another flake and use sayGoodbye however you’d like.

Or load it into the nix repl like so:

nix repl
nix-repl> :lf .
nix-repl> lib.sayGoodbye
«lambda sayGoodbye @ /nix/store/665rwfvkwdx6kwvk9ldijp2a6jvcgv1n-source/flake.nix:4:20»
nix-repl> lib.sayGoodbye "Jr"
"Goodbye F*** Off, Jr!"

As you can see, specifying lib.sayGoodbye without any arguments returns a function. (a lambda function)

Simplifying Multi-Platform Outputs with flake-utils

Manually repeating these platform definitions for every output (packages, devShells, checks, etc.) can quickly become verbose. This is where the flake-utils helper flake comes in handy. It provides utilities to reduce boilerplate when defining outputs for multiple systems.

A commonly used function is flake-utils.lib.eachDefaultSystem, which automatically generates outputs for common platforms (like x86_64-linux, aarch64-linux, x86_64-darwin, aarch64-darwin). This transforms your outputs definition from manually listing each system to a more concise structure:

Example using flake-utils

{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    flake-utils.url = "github:numtide/flake-utils"; # Don't forget to add flake-utils to inputs!
  };

  outputs = {
    self,
    nixpkgs,
    flake-utils,
    ...
  }:
    flake-utils.lib.eachDefaultSystem (
      system: let
        pkgs = import nixpkgs {inherit system;};
      in {
        packages.hello = pkgs.hello; # Now directly defines 'hello' for the current 'system' # packages.default = self.packages.${system}.hello; # Optional default alias
        devShells.default = pkgs.mkShell {
          packages = [pkgs.hello];
        };
      }
    );
}

This flake-utils pattern is particularly useful for defining consistent development environments across platforms, which can then be activated simply by running nix develop in the flake’s directory.

Adding Formatter, Checks, and Devshell Outputs

This is a minimal flake for demonstration with a hardcoded system, for more portability:

{
  description = "NixOS configuration";

  inputs = {
    nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
    home-manager.url = "github:nix-community/home-manager";
    home-manager.inputs.nixpkgs.follows = "nixpkgs";
    treefmt-nix.url = "github:numtide/treefmt-nix";
   };

  outputs = inputs@{ nixpkgs, home-manager, treefmt-nix, ... }: let

    system = "x86_64-linux";
    host = "your-hostname-goes-here";
      # Define pkgs with allowUnfree
    pkgs = import inputs.nixpkgs {
      inherit system;
      config.allowUnfree = true;
    };

        # Formatter configuration
    treefmtEval = treefmt-nix.lib.evalModule pkgs ./lib/treefmt.nix;

in {

    formatter.${system} = treefmtEval.config.build.wrapper;

    # Style check for CI
    checks.${system}.style = treefmtEval.config.build.check self;

    # Development shell
    devShells.${system}.default = import ./lib/dev-shell.nix {
      inherit inputs;
    };


    nixosConfigurations = {
      hostname = nixpkgs.lib.nixosSystem {
        system = "x86_64-linux";
        modules = [
          ./configuration.nix
          home-manager.nixosModules.home-manager
          {
            home-manager.useGlobalPkgs = true;
            home-manager.useUserPackages = true;
            home-manager.users.jdoe = ./home.nix;

            # Optionally, use home-manager.extraSpecialArgs to pass
            # arguments to home.nix
          }
        ];
      };
    };
  };
}

And in lib/treefmt.nix:

# treefmt.nix
{
  projectRootFile = "flake.nix";
  programs = {
    alejandra.enable = true;
    deadnix.enable = true;
    # rustfmt.enable = true;
    # shellcheck.enable = true;
    # prettier.enable = true;
    statix.enable = true;
    keep-sorted.enable = true;
    # nixfmt = {
    #   enable = true;
    #   # strict = true;
    # };
  };
  settings = {
    global.excludes = [
      "LICENSE"
      "README.md"
      ".adr-dir"
      "nu_scripts"
      # unsupported extensions
      "*.{gif,png,svg,tape,mts,lock,mod,sum,toml,env,envrc,gitignore,sql,conf,pem,*.so.2,key,pub,py,narHash}"
      "data-mesher/test/networks/*"
      "nss-datamesher/test/dns.json"
      "*.age"
      "*.jpg"
      "*.nu"
      "*.png"
      ".jj/*"
      "Cargo.lock"
      "flake.lock"
      "hive/moonrise/borg-key-backup"
      "justfile"
    ];
    formatter = {
      deadnix = {
        priority = 1;
      };
      statix = {
        priority = 2;
      };
      alejandra = {
        priority = 3;
      };
    };
  };
}

Now we have a few commands available to us in our flake directory:

nix fmt: Will format your whole configuration consistently
nix flake check: While this command was already available, it is now tied to treefmt’s check which will check the style of your syntax and provide suggestions.

And this is lib/dev-shell.nix:

{
  inputs,
  system ? "x86_64-linux",
}: let
  # Instantiate nixpkgs with the given system and allow unfree packages
  pkgs = import inputs.nixpkgs {
    inherit system;
    config.allowUnfree = true;
    overlays = [
      # Add overlays if needed, e.g., inputs.neovim-nightly-overlay.overlays.default
    ];
  };
in
  pkgs.mkShell {
    name = "nixos-dev";
    packages = with pkgs; [
      # Nix tools
      nixfmt-rfc-style # Formatter
      deadnix # Dead code detection
      nixd # Nix language server
      nil # Alternative Nix language server
      nh # Nix helper
      nix-diff # Compare Nix derivations
      nix-tree # Visualize Nix dependencies

      # Code editing
      helix # Your editor

      # General utilities
      git
      ripgrep
      jq
      tree
    ];

    shellHook = ''
      echo "Welcome to the NixOS development shell!"
      echo "System: ${system}"
      echo "Tools available: nixfmt, deadnix, nixd, nil, nh, nix-diff, nix-tree, helix, git, ripgrep, jq, tree"
    '';
  }

Now you can run nix develop in the flake directory and if successfull, you’ll see the echo commands above and you will have all the tools available in your environment without having to explicitly install them.

Flake outputs

2025-11-28T00:00:00+00:00

Nix Flake Examples

✔️ Click to Expand Table of Contents

This chapter provides practical examples to illustrate the concepts discussed in “Nix Flakes Explained.”

Example showing the extensibility of Flakes

NixOS modules and configurations offer us a powerful and composable way to define and share system configurations. Imagine we have several independent “players,” each with their own unique set of configurations or modules. How do we combine these individual contributions into a single, cohesive system without directly altering each player’s original flake?

This example demonstrates how flakes can extend and compose each other, allowing you to layer configurations on top of existing ones. This is particularly useful when you want to:

Build upon a base configuration without modifying its source.
Combine features from multiple independent flakes into a single system.
Create specialized versions of an existing configuration.

Let’s simulate this by creating a players directory with three sub-directories: first, second, and third. Each of these will contain its own flake.nix.

mkdir players
cd players
mkdir first
mkdir second
mkdir third
cd first

Now create a flake.nix with the following contents:

# flake.nix
{
  inputs = {
    nixpkgs.url = "github:nixos/nixpkgs/nixos-24.11";
  };

  outputs = {
    self,
    nixpkgs,
  }: {
    nixosModules.default = {
      config,
      pkgs,
      lib,
      ...
    }: {
      # Create a file `/etc/first-file`
      environment.etc.first-file.text = "Hello player # 1!";
      boot.initrd.includeDefaultModules = false;
      documentation.man.enable = false;
      boot.loader.grub.enable = false;
      fileSystems."/".device = "/dev/null";
      system.stateVersion = "24.11";
    };
    nixosConfigurations.testing = nixpkgs.lib.nixosSystem {
      system = "x86_64-linux";
      modules = [
        self.nixosModules.default
      ];
    };
  };
}

This demonstrates using self to reference this flake from within its own outputs. This is the main use for self with flakes. Without self, I wouldn’t have a direct way to refer to the nixosModules.default that’s defined within the same flake.

Now in the players/second directory create this flake.nix:

# flake.nix
{
  inputs = {
    nixpkgs.url = "github:nixos/nixpkgs/nixos-24.11";
  };

  outputs = {
    self,
    nixpkgs,
  }: {
    nixosModules.default = {
      config,
      pkgs,
      lib,
      ...
    }: {
      # Create a file `/etc/second-file`
      environment.etc.second-file.text = "Hello player # 2!";
    };
  };
}

nixosModules.default is a module which is a function that, when called by the NixOS module system, returns an attribute set representing a piece of system configuration.
- Within that attribute set, it specifies that the file /etc/second-file should exist with “Hello player # 2!” as its content.

And finally in players/third create another flake.nix:

# flake.nix
{
  inputs = {
    first.url = "/home/jr/players/first";
    nixpkgs.follows = "first/nixpkgs";
    second = {
      url = "/home/jr/players/second";
      inputs.nixpkgs.follows = "first/nixpkgs";
    };
  };

  outputs = {
    self,
    nixpkgs,
    first,
    second,
  }:
    first.outputs
    // {
      nixosConfigurations.testing = first.nixosConfigurations.testing.extendModules {
        modules = [
          second.nixosModules.default
        ];
      };
    };
}

You’ll have to change the locations to where you placed your players directory in the inputs above.

In your third directory inspect it with:

  ~/players/third
❯ nix flake show
path:/home/jr/players/third?lastModified=1748271697&narHash=sha256-oNzkC6X9hA0MpOBmJSZ89w4znXxv4Q5EkFhp0ewehY0%3D
├───nixosConfigurations
│   └───testing: NixOS configuration
└───nixosModules
    └───default: NixOS module

and build it with:

nix build .#nixosConfigurations.testing.config.system.build.toplevel

cat result/etc/first-file
Hello player # 1!
cat result/etc/second-file
Hello player # 2!

Understanding the Extension

As you saw in the flake.nix for the third player, we leveraged two key flake features to combine and extend the previous configurations:

Attribute Set Union (// operator):

outputs = { ..., first, second, ... }:
first.outputs // { # ... your extensions here ...
};

The // (attribute set union) operator allows us to take all the outputs from first.outputs (which includes its nixosConfigurations and nixosModules) and then overlay or add to them on the right-hand side. This means our third flake will inherit all the outputs from first, but we can then modify or add new ones without changing the first flake itself.

config.extendModules:

    nixosConfigurations.testing = first.nixosConfigurations.testing.extendModules {
      modules = [
        second.nixosModules.default
      ];
    };

This is the core of the extension. We’re taking the testing NixOS configuration defined in the first flake (first.nixosConfigurations.testing) and then calling its extendModules function. This function allows us to inject additional NixOS modules into an already defined system configuration. In this case, we’re adding the default module from the second flake (second.nixosModules.default).

By combining these techniques, the third flake successfully creates a NixOS configuration that includes both the settings from first (like /etc/first-file and the base system options) and the settings from second (like /etc/second-file), all without directly altering the first or second flakes. This demonstrates the incredible power of flake extensibility for building complex, modular, and composable systems.

Nix Pull Requests

2025-11-27T00:00:00+00:00

Chapter 11

✔️ Click to Expand Table of Contents

Nix Pull Requests

Pull requests communicate changes to a branch in a repository. Once a pull request is opened, you can review changes with collaborators and add follow-up commits.

A pull request is a proposal to merge a set of changes from one branch into another. In a pull request, collaborators can review and discuss the proposed set of changes before they integrate the changes into the main codebase.
Pull requests display the differences, or diffs, between the content in the source branch and the content in the target branch.

graph LR
    A[Your Local Repository] --> B(Feature Branch);
    B --> C{GitHub Repository};
    C -- "Open Pull Request" --> D[Pull Request on GitHub];
    D -- "Review & Discussion" --> D;
    D -- "Merge" --> E(Main Branch on GitHub);
    E --> F[Nixpkgs Users];

Explanation of the Diagram:

✔️ Click to see Explanation

A[Your Local Repository]: This represents the copy of the Nixpkgs repo on your computer where you make changes.
B (Feature Branch): You create a dedicated branch (e.g.my-pack-update) to isolate your changes.
C {GitHub Repository}: This is the central online repo for Nixpkgs on Github. You push your feature branch to this repo.
C – “Open Pull Request” – D [Pull Request on Github]: You initiate a pull request from your feature branch to the main branch (usually master or main) through the GitHub interface.
D [Pull Request on GitHub]: This is where collaborators can see your proposed changes, discuss them, and provide feedback.
D – “Review & Discussion” –> D: The pull request facilitates communication and potential revisions based on the review.
D – “Merge” –> E (Main Branch on GitHub): Once the changes are approved, they are merged into the main branch of the Nixpkgs repository.
E (Main Branch on GitHub): The main branch now contains the integrated changes.
E –> F [Nixpkgs Users]): Eventually, these changes become available to all Nixpkgs users through updates to their Nix installations.

Flakes often rely on having access to the full history of the Git repository to correctly determine dependencies, identify specific revisions of inputs, and evaluate the flake. Not in all situations will a shallow clone work and this is one of them.

If you have any changes to your local copy of Nixpkgs make sure to stash them before the following:

git stash -u

This command saves your uncommited changes (including staged files) temporarily. You can restore them later with git stash pop

Step 1 Clone Nixpkgs Locally

If you don’t have Nixpkgs locally, you’ll need to clone it:

git clone https://github.com/NixOS/nixpkgs.git

Step 2 Find a Relevant Pull Request

To find specifig commits and releases:

status.nixos.org provides the latest tested commits for each release - use when pinning to specific commits. List of active release channels - use when tracking latest channel versions.

The complete list of channels is available at nixos.org/channels

To find a relevant PR you can go to:

Nixpkgs Pull Requests
The following example actually uses the Nix Pull Requests the process is the same, but that is an important distinction.
In the Filters enter stack trace for this example.
The pull request I chose was 8623

Step 3 Add the Remote Repository (if necessary)

If the pull request is from a different repository than your local clone (as in the case of the nix PR while working in a nixpkgs clone), you need to add that repository as a remote. It’s common to name the main Nixpkgs remote origin and other related repositories like nix as upstream.

Assuming you are in your nixpkgs clone and want to test a PR from the nix repository:

git remote add upstream https://github.com/NixOS/nix.git

Step 4 Fetch the Pull Request Changes

Fetch the Pull Request Information:

git fetch upstream refs/pull/8623/head:pr-8623

This command fetches the branch named head from the pull request 8623 in the upstream remote and creates a local branch named pr-8623 that tracks it.

Output:

✔️ Output (Click to Enlarge)

remote: Enumerating objects: 104651, done.
remote: Counting objects: 100% (45/45), done.
remote: Compressing objects: 100% (27/27), done.
remote: Total 104651 (delta 33), reused 20 (delta 18), pack-reused 104606 (from 1)
Receiving objects: 100% (104651/104651), 61.64 MiB | 12.56 MiB/s, done.
Resolving deltas: 100% (74755/74755), done.
From https://github.com/NixOS/nix
 * [new ref]             refs/pull/8623/head -> pr-8623
 * [new tag]             1.0                 -> 1.0
 * [new tag]             1.1                 -> 1.1
 * [new tag]             1.10                -> 1.10
 * [new tag]             1.11                -> 1.11
 * [new tag]             1.11.1              -> 1.11.1
 * [new tag]             1.2                 -> 1.2
 * [new tag]             1.3                 -> 1.3
 * [new tag]             1.4                 -> 1.4
 * [new tag]             1.5                 -> 1.5
 * [new tag]             1.5.1               -> 1.5.1
 * [new tag]             1.5.2               -> 1.5.2
 * [new tag]             1.5.3               -> 1.5.3
 * [new tag]             1.6                 -> 1.6
 * [new tag]             1.6.1               -> 1.6.1
 * [new tag]             1.7                 -> 1.7
 * [new tag]             1.8                 -> 1.8
 * [new tag]             1.9                 -> 1.9
 * [new tag]             2.0                 -> 2.0
 * [new tag]             2.2                 -> 2.2

Step 5 Checkout the Local Branch:

git checkout pr-8623

Or with the gh cli:

gh pr checkout 8623

Build and Test the Changes

Now we want to see if the code changes introduced by the pull request actually build correctly within the Nix ecosystem.

nix build

Output:

✔️ Output (Click to Enlarge)

error: builder for '/nix/store/rk86daqgf6a9v6pdx6vcc5b580lr9f09-nix-2.20.0pre20240115_20b4959.drv' failed with exit code 2;
   last 25 log lines:
   >
   >         _NIX_TEST_ACCEPT=1 make tests/functional/lang.sh.test
   >
   >     to regenerate the files containing the expected output,
   >     and then view the git diff to decide whether a change is
   >     good/intentional or bad/unintentional.
   >     If the diff contains arbitrary or impure information,
   >     please improve the normalization that the test applies to the output.
   > make: *** [mk/lib.mk:90: tests/functional/lang.sh.test] Error 1
   > make: *** Waiting for unfinished jobs....
   > ran test tests/functional/selfref-gc.sh... [PASS]
   > ran test tests/functional/store-info.sh... [PASS]
   > ran test tests/functional/suggestions.sh... [PASS]
   > ran test tests/functional/path-from-hash-part.sh... [PASS]
   > ran test tests/functional/gc-auto.sh... [PASS]
   > ran test tests/functional/path-info.sh... [PASS]
   > ran test tests/functional/flakes/show.sh... [PASS]
   > ran test tests/functional/fetchClosure.sh... [PASS]
   > ran test tests/functional/completions.sh... [PASS]
   > ran test tests/functional/build.sh... [PASS]
   > ran test tests/functional/impure-derivations.sh... [PASS]
   > ran test tests/functional/build-delete.sh... [PASS]
   > ran test tests/functional/build-remote-trustless-should-fail-0.sh... [PASS]
   > ran test tests/functional/build-remote-trustless-should-pass-2.sh... [PASS]
   > ran test tests/functional/nix-profile.sh... [PASS]
   For full logs, run:
     nix log /nix/store/rk86daqgf6a9v6pdx6vcc5b580lr9f09-nix-2.20.0pre20240115_20b4959.drv

nix build (Part of the Nix Unified CLI):
- Declarative: when used within a Nix flake (flake.nix), nix build is a bit more declarative. It understands the outputs defined in your flake.
- Clearer Output Paths: nix build typically places build outputs in the ./result directory by default (similar to nix-build’s result symlink)
- Better Error Reporting: It gives more informative error messages.
- Future Direction

Benefits of using nix build:

Flake Integration: nix build naturally understands the flake’s outputs.
Development Shells: When you are in a nix develop shell, nix build is the more idiomatic way to build packages defined in your dev environment.
Consistency: Using the unified CLI promotes a more consistent workflow.

Next Steps

As you can see this build failed, as for why the build failed, the key part of the error message is:

make: *** [mk/lib.mk:90: tests/functional/lang.sh.test] Error 1

This suggests that one of the functional tests (lang.sh.test) failed. This happens when the expected output of the test doesn’t match the actual output.

This can heppen when:

The test expectations are outdated due to changes in the codebase.
The test captures environment-specific or transient outputs that are not properly normalized.
The test includes impure or non-deterministic information, making it hard to verify.

To address this, _NIX_TEST_ACCEPT=1 is used as an override mechanism that tells the test framework: > “Accept whatever output is generated as the new expected result.”

The message advises running:

_NIX_TEST_ACCEPT=1 make tests/functional/lang.sh.test

This will regenerate the expected output files, allowing you to inspect what changed with git diff:

git diff tests/functional/lang.sh.test

Verifies if Changes are Intentional: If the difference is reasonable and expected (due to a legitimate update in the logic), you can commit these changes to update the test suit. If not, you have to refine the test normalization process further.

If the changes seem valid, commit them:

git add tests/functional/lang.sh.test
git commit -m "Update expected test output for lang.sh.test"

Running the following will provide the full logs:

nix log /nix/store/rk86daqgf6a9v6pdx6vcc5b580lr9f09-nix-2.20.0pre20240115_20b4959.drv

Conclusion

Testing Nixpkgs pull requests is a vital part of contributing to a healthy and reliable Nix ecosystem. By following these steps, you can help ensure that changes are well-vetted before being merged, ultimately benefiting all Nix users. Your efforts in testing contribute significantly to the quality and stability of Nixpkgs.

Unencrypted BTRFS Impermanence with Flakes

2025-11-24T00:00:00+00:00

Unencrypted BTRFS Impermanence with Flakes

✔️ Click to Expand Table of Contents

Figure 1: Impermanence Logo: Image of the Impermanence logo. Sourced from the

Impermanence repo

This guide is for an unencrypted setup, there are a few links at the end for encrypted setups. This guide follows the previous minimal install guide but you should be able to adjust it carefully to meet your needs.

This section details how to set up impermanence on your NixOS system using BTRFS subvolumes. With impermanence, your operating system’s root filesystem will reset to a pristine state on each reboot, while designated directories and files remain persistent. This provides a highly reliable and rollback-friendly system.

In NixOS, “state” is any data or condition of the system that isn’t defined in your declarative configuration. The impermanence approach aims to make this state temporary (ephemeral) or easily resettable, so your system always matches your configuration and can recover from unwanted changes or corruption.

Impermanence: The Concept and Its BTRFS Implementation

In a traditional Linux system, most of this state is stored on the disk and persists indefinitely unless manually deleted or modified. However, this can lead to configuration drift, where the system accumulates changes (e.g., log files, temporary files, or unintended configuration tweaks) that make it harder to reproduce or maintain.

Impermanence, in the context of operating systems, refers to a setup where the majority of the system’s root filesystem (/) is reset to a pristine state on every reboot. This means any changes made to the system (e.g., installing new packages, modifying system files outside of configuration management, creating temporary files) are discarded upon shutdown or reboot.

What Does Impermanence Do?

Impermanence is a NixOS approach that makes the system stateless (or nearly stateless) by wiping the root filesystem (/) on each boot, ensuring a clean, predictable starting point. Only explicitly designated data (persistent state) is preserved across reboots, typically stored in specific locations like the /nix/persist subvolume. This is possible because NixOS can boot with only the /boot, and /nix directories. This achieves:

Clean Root Filesystem:

The root subvolume is deleted and recreated on each boot, erasing transient state (e.g., temporary files, runtime data).
This ensures the system starts fresh, reducing clutter and making it behave closer to a declarative system defined by your NixOS configuration.

Selective Persistence:

Critical state (e.g., user files, logs, system configuration) is preserved in designated persistent subvolumes (e.g., /nix/persist, /var/log, /var/lib) or files.
You control exactly what state persists by configuring environment.persistence."/nix/persist" or other mechanisms.
❗ The understanding around persisting /var/lib/nixos seems to be evolving. See,The importance of persisting /var/lib/nixos See also necessary system state

Reproducibility and Security:

By wiping transient state, impermanence prevents unintended changes from accumulating, making the system more reproducible.
It enhances security by ensuring sensitive temporary data (e.g., /tmp, runtime credentials) is erased on reboot.

Getting Started

Add impermanence to your flake.nix. You will change the hostname in the flake to match your networking.hostName.

# flake.nix
{
  description = "NixOS configuration";

  inputs = {
    nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
    disko.url = "github:nix-community/disko/latest";
    disko.inputs.nixpkgs.follows = "nixpkgs";
    impermanence.url = "github:nix-community/impermanence";
  };

  outputs = inputs@{ nixpkgs, ... }: {
    nixosConfigurations = {
      hostname = nixpkgs.lib.nixosSystem {
        system = "x86_64-linux";
        modules = [
          ./configuration.nix
          inputs.disko.nixosModules.disko
          inputs.impermanence.nixosModules.impermanence
        ];
      };
    };
  };
}

Discover where your root subvolume is located with findmnt:

Before configuring impermanence, it’s crucial to know the device path and subvolume path of your main BTRFS partition where the root filesystem (/) is located. This information is needed for the mount command within the impermanence script.

findmnt /
TARGET   SOURCE         FSTYPE OPTIONS
/        /dev/disk/by-partlabel/disk-main-root[/root]
                        btrfs  rw,noatime,compress=zstd:3,ssd,discard=async,space_cache=v2,subvolid=275,sub

From the SOURCE column, note the full path, including the device (e.g., /dev/disk/by-partlabel/disk-main-root) and the subvolume in brackets (e.g., [/root]). You will use the device path in the next step

/dev/disk/by-partlabel/disk-main-root is a symlink to the actual device path (e.g. /dev/nvme0n1p2), but using the partlabel is generally more robust for scripts.

Create an impermanence.nix:

Now, create a new file named impermanence.nix in your configuration directory (i.e. your flake directory). This file will contain all the specific settings for your impermanent setup, including BTRFS subvolume management and persistent data locations. Since this file is right next to your configuration.nix, you’ll just add an imports = [ ./impermanence.nix ] to your configuration.nix apply it to your configuration.

{lib, ...}: {
  #  Reset root subvolume on boot
  boot.initrd.postResumeCommands = lib.mkAfter ''
    mkdir /btrfs_tmp
      mount /dev/disk/by-partlabel/disk-main-root /btrfs_tmp # CONFIRM THIS IS CORRECT FROM findmnt
      if [[ -e /btrfs_tmp/root ]]; then
        mkdir -p /btrfs_tmp/old_roots
        timestamp=$(date --date="@$(stat -c %Y /btrfs_tmp/root)" "+%Y-%m-%-d_%H:%M:%S")
        mv /btrfs_tmp/root "/btrfs_tmp/old_roots/$timestamp"
      fi

      delete_subvolume_recursively() {
        IFS=$'\n'
        for i in $(btrfs subvolume list -o "$1" | cut -f 9- -d ' '); do
          delete_subvolume_recursively "/btrfs_tmp/$i"
        done
        btrfs subvolume delete "$1"
      }

      for i in $(find /btrfs_tmp/old_roots/ -maxdepth 1 -mtime +30); do
        delete_subvolume_recursively "$i"
      done

      btrfs subvolume create /btrfs_tmp/root
      umount /btrfs_tmp
  '';

  # Use /persist as the persistence root, matching Disko's mountpoint
  environment.persistence."/nix/persist" = {
    hideMounts = true;
    directories = [
      "/etc" # System configuration (Keep this here for persistence via bind-mount)
      "/var/spool" # Mail queues, cron jobs
      "/srv" # Web server data, etc.
      "/root"
    ];
    files = [
    ];
  };
}

With btrfs subvolumes since each directory is its own subvolume, when the root is wiped on reboot the subvolumes are untouched.

Applying Your Impermanence Configuration

Once you have completed all the steps and created or modified the necessary files (flake.nix, impermanence.nix), you need to apply these changes to your NixOS system.

Navigate to your NixOS configuration directory (where your flake.nix is located).

cd /path/to/your/flake

Rebuild and Switch: Execute the nixos-rebuild switch command. This command will:

Evaluate your flake.nix and the modules it imports (including your new impermanence.nix).
Build a new NixOS system closure based on your updated configuration.
Activate the new system configuration, making it the current running system.

❗ NOTE: On the first rebuild after setting up impermanence, you may find that you’re not in the password database or cannot log in/sudo. This occurs because the initial state of your new ephemeral root filesystem, including /etc (where user passwords are stored), is fresh. It has to do with the timing of when environment.persistence takes effect during the first boot.

To avoid this password issue, before your first nixos-rebuild switch for impermanence, run:
sudo mkdir -p /nix/persist/etc # Ensure the target directory exists
sudo cp -a /etc/* /nix/persist/etc
This copies your current /etc directory contents (including existing user passwords) into your persistent >>storage.

Crucially: You must also ensure that /etc is explicitly included in your environment.persistence."/nix/persist".directories list in your impermanence.nix like we did above, (or main configuration). This configures >NixOS to persistently bind-mount /nix/persist/etc over /etc on every subsequent boot. Once these steps are done and you reboot, your user passwords should function correctly, and future rebuilds will > not present this problem.

sudo nixos-rebuild switch --flake .#hostname # Replace 'hostname' with your actual system hostname

Perform an Impermanence Test (Before Reboot):

Before you reboot, create a temporary directory and file in a non-persistent location. Since you haven’t explicitly added /imperm_test to your environment.persistence."/nix/persist" directories, this file should not survive a reboot.

mkdir /imperm_test
echo "This should be Gone after Reboot" | sudo tee /imperm_test/testfile
ls -l /imperm_test/testfile # Verify the file exists
cat /imperm_test/testfile # Verify content

Reboot Your System: For the impermanence setup to take full effect and for your root filesystem to be reset for the first time, you must reboot your machine.

sudo reboot

Verify Impermanence (After Reboot):

After the system has rebooted, check if the test directory and file still exist:

ls -l /imperm_test/testfile

You should see an output like ls: cannot access '/imperm_test/testfile': No such file or directory. This confirms that the /imperm_test directory and its contents were indeed ephemeral and were removed during the reboot process, indicating your impermanence setup is working correctly!

Your system should now come up with a fresh root filesystem, and only the data specified in your environment.persistence."/nix/persist" configuration will be persistent.

Recovery with nixos-enter and chroot

This is if you followed the minimal_install guide, it will need to be changed for a different disk layout.

Chroot is an operation that changes the apparent root directory for the current running process and their children. A program that is run in such a modified environment cannot access files and commands outside that environmental directory tree. This modified environment is called a chroot jail. –NixOS wiki

nixos-enter allows you to access a NixOS installation from a NixOS rescue system. To use, setup /mnt as described in the installation manual

🛠️ Recovery: Chroot into Your NixOS Btrfs+Impermanence System

Take note of your layout from commands like:

sudo fdisk -l
lsblk
sudo btrfs subvol list /

Also inspect your disk-config.nix to ensure you refer to the correct subvol= names.

If you need to repair your system (e.g., forgot root password, fix a broken config, etc.), follow these steps to chroot into your NixOS install:

Boot a Live ISO

Boot from a NixOS (or any recent Linux) live USB.

Open a terminal and become root:

sudo -i

Identify Your Devices

Your main disk is /dev/nvme0n1

EFI partition: /dev/nvme0n1p1 (mounted at /boot)
Root partition: /dev/nvme0n1p2 (Btrfs, with subvolumes)

Mount the Btrfs Root Subvolume

First, mount the Btrfs partition somewhere temporary (not as / yet):

mount -o subvol=root,compress=zstd,noatime /dev/nvme0n1p2 /mnt

Mount Other Subvolumes

Now mount your other subvolumes as defined in your disko.nix:

# Mount Other Subvolumes
# (Ensure /mnt directories are created for each *mountpoint*)

# Home
mkdir -p /mnt/home
mount -o subvol=home,compress=zstd,noatime /dev/nvme0n1p2 /mnt/home

# IMPORTANT: No separate mount for /mnt/home/user, as it's a nested subvolume
# and handled by the /home mount.

# Nix store
mkdir -p /mnt/nix
mount -o subvol=nix,compress=zstd,noatime /dev/nvme0n1p2 /mnt/nix

# Nix persist
mkdir -p /mnt/nix/persist
# CRITICAL: Based our disko.nix, the subvolume name is 'persist', not 'nix/persist'
mount -o subvol=persist,compress=zstd,noatime /dev/nvme0n1p2 /mnt/nix/persist

# /var/log
mkdir -p /mnt/var/log
mount -o subvol=log,compress=zstd,noatime /dev/nvme0n1p2 /mnt/var/log

# /var/lib
mkdir -p /mnt/var/lib
# Confirmed: The subvolume named 'lib' is mounted to /var/lib
mount -o subvol=lib,compress=zstd,noatime /dev/nvme0n1p2 /mnt/var/lib

Note: If you get “subvolume not found,” check the subvolume names with btrfs subvol list /mnt.

Mount the EFI Partition

mkdir -p /mnt/boot mount /dev/nvme0n1p1 /mnt/boot

(Optional) Mount Virtual Filesystems

mount --bind /dev /mnt/dev mount --bind /proc /mnt/proc mount --bind /sys
/mnt/sys mount --bind /run /mnt/run

Chroot

chroot /mnt /run/current-system/sw/bin/bash

or, if using a non-NixOS live system:

nixos-enter

(You may need to install nixos-enter with nix-shell -p nixos-enter.) 8. You’re In!

You can now run nixos-rebuild, reset passwords, or fix configs as needed. 🔎

📓 Notes

Adjust compress=zstd,noatime if your config uses different mount options.
For impermanence, make sure to mount all persistent subvolumes you need.
If you use swap, you may want to enable it too (e.g., swapon /dev/zram0 if relevant).

You can now recover, repair, or maintain your NixOS system as needed!

Related Material

Nix Lang

2025-11-22T00:00:00+00:00

Nix Language

✔️ Click to Expand Table of Contents

Nix Expression Language Syntax Overview

The Nix language is designed for conveniently creating and composing derivations precise descriptions of how contents of files are used to derive new files. –Nix Reference Manual

Nix is often described as “JSON with functions.” It’s a declarative language where you define outcomes, not step-by-step instructions. Instead of writing sequential code, you create expressions that describe data structures, functions, and dependencies. These expressions are evaluated lazily, meaning Nix computes values only when needed, making it efficient for managing large systems.

You can plug most of the following into the nix repl I’m showing it in a single code block here for brevity:

# Comments Look Like This!

# Strings
"This is a string"          # String literal

''
one
two                        # multi-line String
three
''

("foo" + "bar")           # => "foobar"

"foo" != "bar"   # Inequality test  # => true

!false      # => true

("Home dir is ${builtins.getEnv "HOME"}")  # String Interpolation
# => "Home dir is /home/jr"

"3 6 ${builtins.toString 9}"
# => "3 6 9"

"goodbye ${ { d = "world";}.d}"
# => "goodbye world"

# Booleans

(false && true)    # AND         # => false

(true || false)    # OR         # => true

(if 6 < 9 then "yay" else "nay")  # => "yay"

null      # Null Value

679       # Integer

(6 + 7 + 9) # => 22   # Addition

(9 - 3  - 2) # => 4   # Subtraction

(6 / 3)  # => 2       # Division
6.79      # Floating Point

/etc/nixos      # Absolute Path

../modules/nixos/boot.nix    # relative

# Let expressions

(let a = "2"; in                   # Let expressions are a way to create variables
a + a + builtins.toString "4")
# => "224"

(let first = "firstname"; in
"lastname " first)
# => "lastname firstname"

# Lists

[ 1 2 "three" "bar" "baz" ]   # lists are whitespace separated

builtins.elemAt [ 1 2 3 4 5 ] 3
# => 4

builtins.length [ 1 2 3 4 ]
# => 4

# Attrsets

{ first = "Jim"; last = "Bo"; }.last # Attribute selection
# => "Bo"

{ a = 1; b = 3; } // { c = 4; b = 2; }   # Attribute Set merging
# => { a = 1; b = 2; c = 4; }               # Right Side takes precedence

builtins.listToAttrs [ { name = "Jr"; value = "Jr Juniorville"; } {name = "$"; value = "JR"; } { name = "jr"; value = "jr
ville"; }]
# => { "$" = "JR"; Jr = "Jr Juniorville"; jr = "jrville"; }

# Control Flow

if 2 * 2 == 4
then "yes!"
else "no!"
# => "yes!"

assert 2 * 2
== 4; "yes!"
# => "yes!"

with builtins;
head [ 5 6 7 ]
# => 5

# or

builtins.head[ 5 6 7 ]

inherit pkgs     # pkgs = pkgs;
src;             # src = src;

Understanding Laziness

Nix expressions are evaluated lazily, meaning Nix computes values only when needed. This is a powerful feature that makes Nix efficient for managing large systems, as it avoids unnecessary computations.

For example, observe how a is never evaluated in the following nix-repl session:

nix-repl> let a = builtins.div 4 0; b = 6; in b
6

Since a isn’t used in the final result, there’s no division by zero error.

Strings and String Interpolation

Strings: Strings are enclosed in double quotes (") or two single quotes ('').

nix-repl> "stringDaddy"
"stringDaddy"
nix-repl> ''
  This is a
  multi-line
  string
''
"This is a\nmulti-line\nstring.\n"

string interpolation. is a language feature where a string, path, or attribute name can contain an expressions enclosed in ${ }. This construct is called an interpolated string, and the expression inside is an interpolated expression.

Rather than writing:

let path = "/usr/local"; in "--prefix=${path}"

This evaluates to "--prefix=/usr/local". Interpolated expressions must evaluate to a string, path, or an attribute set with an outPath or __toString attribute.

Attribute Sets

Attribute sets are all over Nix code and deserve their own section, they are name-value pairs wrapped in curly braces, where the names must be unique:

{
  string = "hello";
  int = 8;
}

Attribute names usually don’t need quotes.

You can access attributes using dot notation:

let person = { name = "Alice"; age = 30; }; in person.name
"Alice"

You will sometimes see attribute sets with rec prepended. This allows access to attributes within the set:

rec {
  x = y;
  y = 123;
}.x

Output: 123

rec {
  one = 1;
  two = one + 1;
  three = two + 1;
}

Output:

 {
  one = 1;
  three = 3;
  two = 2;
 }

# This would fail:
{
  one = 1;
  two = one + 1;  # Error: undefined variable 'one'
  three = two + 1;
}

Recursive sets introduce the danger of infinite recursion For example:

rec {
  x = y;
  y = x;
}.x

Will crash with an infinite recursion encountered error message.

The attribute set update operator merges two attribute sets.

Example:

{ a = 1; b = 2; } // { b = 3; c = 4; }

Output:

{ a = 1; b = 3; c = 4; }

However, names on the right take precedence, and updates are shallow.

Example:

{ a = { b = 1; }; } // { a = { c = 3; }; }

Output:

{ a = { c = 3; }; }

Above, key b was completely removed, because the whole a value was replaced.

Inheriting Attributes

Click to see Output:

let x = 123; in
{
  inherit x;
  y = 456;
}

is equivalent to

let x = 123; in
{
  x = x;
  y = 456;
}

which are both equivalent to

{
  x = 123;
  y = 456;
}

❗: This works because x is added to the lexical scope by the let construct.

Now that we understand attribute sets lets move on to functions, a powerful feature of the Nix language that gives you the ability to reuse and share logical pieces of code.

Functions(lambdas):

Functions in Nix help you build reusable components and are the the building blocks of Nix. In the next chapter we’ll go even further into Nix functions and how to use them but I will touch on them here.

Nix functions have this form:

pattern: body

The following is a function that expects an integer and returns it increased by 1:

x: x + 1   # lambda function, not bound to a variable

The pattern tells us what the argument of the function has to look like, and binds variables in the body to (parts of) the argument.

(x: x + 5) 200
205

They are all lambdas (i.e. anonymous functions without names) until we assign them to a variable like the following example.

Functions are defined using this syntax, where x and y are attributes passed into the function:

{
  my_function = x: y: x + y;
}

The code below calls a function called my_function with the parameters 2 and 3, and assigns its output to the my_value field:

{
  my_value = my_function 2 3;
}
my_value
5

The body of the function automatically returns the result of the function. Functions are called by spaces between it and its parameters. No commas are needed to separate parameters.

The following is a function that expects an attribute set with required attributes a and b and concatenates them:

{ a, b }: a + b

Default Values in Functions:

Functions in Nix can define default values for their arguments. This allows for more flexible function calls where some arguments are optional.

{ x, y ? "foo", z ? "bar" }: z + y + x

Specifies a function that only requires an attribute named x, but optionally accepts y and z.

@-patterns in functions:

An @-pattern provides a means of referring to the whole value being matched by the function’s argument pattern, in addition to destructuring it. This is especially useful when you want to access attributes that are not explicitly destructured in the pattern:

args@{ x, y, z, ... }: z + y + x + args.a
# or
{ x, y, z, ... } @ args: z + y + x + args.a

Here, args is bound to the argument as passed, which is further matched against the pattern { x, y, z, ... }. The @-pattern makes mainly sense with an ellipsis(...) as you can access attribute names as a, using args.a, which was given as an additional attribute to the function.
We will expand on Functions in This Chapter

If, Let, and With Expressions

Nix is a pure expression language, meaning every construct evaluates to a value — there are no statements. Because of this, if expressions in Nix work differently than in imperative languages, where conditional logic often relies on statements (if, elsif, etc.).

If expressions in Nix:

Since everything in Nix is an expression, an if expression must always produce a value:

nix-repl> a = 6
nix-repl> b = 10
nix-repl> if a > b then "yes" else "no"
"no"

Here, "no" is the result because a(6) is not greater than b(10). Notice that there’s no separate conditional statement – the entire construct evaluates to a value.

Another example, integrating built-in functions:

{
  key = if builtins.pathExists ./path then "YES" else "NO!";
}

If ./path exists it will evaluate to the value "YES" or else it will evaluate to "NO!".

Thus, the final result of the expression would be:

{ key = "YES"; }
# or
{ key = "NO!"; }

Since Nix does not have statements, Nix’s if statements behave more like ternary operators (condition ? value_if_true : value_if_false) in other languages.

Let expressions:

Let expressions in Nix is primarily a mechanism for local variable binding and scoping. It allows you to define named values that are only accessible within the in block of the let expression. This is useful for keeping code clean and avoiding repitition.

For example:

let
  a = "foo";
  b = "fighter";
in a + b
"foofighter"

Here, a and b are defined inside the let block, and their values are used in the in expression. Since everything in Nix is an expression, a + b evaluates to "foofighter"

Using Let Expressions Inside Attribute Sets

Let expressions are commonly used when defining attribute sets (Click for output):

let
  appName = "nix-app";
  version = "1.0";
in {
  name = appName;
  fullName = appName + "-" + version;
}
~{
~  name = "nix-app";
~  fullName = "nix-app-1.0";
~}

This allows you to reuse values within an attribute set, making the code more modular and preventing duplication.

Let Expressions in Function Arguments

You can also use let expressions within function arguments to define intermediate values before returning an output:

{ pkgs, lib }:
let
  someVar = "hello";
  otherVar = "world";
in
{ inherit pkgs lib someVar otherVar; }

Result:

{
  pkgs = <value>;
  lib = <value>;
  someVar = "hello";
  otherVar = "world";
}

Here, inherit brings pkgs and lib into the resulting attribute set, alongside the locally defined variables someVar and otherVar.

Key Takeaways:

Let expressions allow local variable bindings that are only visible inside the in block. They also help avoid repitition and improve readability.
Commonly used inside attribute sets or function arguments.
Their scope is limited to the expression in which they are declared.

With expressions:

A with expression in Nix is primarily used to simplify access to attributes within an attribute set. Instead of repeatedly referring to a long attribute path, with temporarily brings the attributes into scope, allowing direct access without prefixing them.

Basic Example: Reducing Attribute Path Usage

Consider the following expressions:

nix-repl> longName = { a = 3; b = 4; }
nix-repl> longName.a + longName.b
7

Here, we must explicitly reference longName.a and longName.b. Using a with expression simplifies this:

nix-repl> with longName; a + b
7

Now, within the scope of the with expression, a and b are accessible without prefixing them with longName.

Practical Use Case: Working with pkgs

One of the most common uses of with that you’ll see is when dealing with packages from nixpkgs is writing the following:

{ pkgs }:
with pkgs; {
  myPackages = [ vim git neofetch ];
}

Instead of writing this:

{ pkgs }:
{
  myPackages = [ pkgs.vim pkgs.git pkgs.neofetch ];
}

Tip: Overusing with lib; or with pkgs; can reduce clarity, it may be fine for smaller modules where the scope is limited. For larger configurations, explicit references (pkgs.something) often make dependencies clearer and prevent ambiguity.

Nix Language Quirks

with gets less priority than let. This can be confusing, especially if you like to write with pkgs;:

nix-repl> pkgs = { x = 2; }

nix-repl> with pkgs; x
2

nix-repl> with pkgs; let x = 4; in x
4

This shows us that the let binding overrides the with binding.

let x = 4; in with pkgs; x
4

Still returns 4, but the reasoning is different. The with expression doesn’t define new bindings; it simply makes attributes from pkgs available as unqualified names. However, because let x = 4 is outside the with, it already extablished x = 4, so when with pkgs; x is evaluated inside, x still refers to the outer let binding, not the one from pkgs.

Default values aren’t bound in @-patterns

In the following example, calling a function that binds a default value "baz" to the attribute b of an argument using an alias (@) pattern, with an empty attribute set as argument, results in the alias variable inputs being bound to the original empty attribute set instead of including the default value:

(inputs@(b ? "baz"): inputs) {}

Output:

{}

This happens because the alias inputs@ binds to the argument as passed, before the default value for b is applied.

The syntax requires curly brackets around the attribute set pattern for correctness, so the fixed syntax would be:

(inputs@{b ? "baz"}: inputs) {}

However, even with this fix, the inputs alias still refers to the original argument without defaults applied. So the quirk persists, showing how default values in @-patterns do not propagate into the aliased variable.

Destructuring function arguments:

nix-repl> f = { x ? 2, y ? 4 }: x + y

nix-repl> f { }
6

The function f takes an attribute set with default values (x = 2, y = 4)

When called with {} (an empty set), it falls back to the default values (2 + 4 -> 6)

Using @args to capture the entire input set:

The @args syntax allows us to retain access to the full attribute set, even after destructuring:

nix-repl> f = { x ? 1, y ? 2, ... }@args: with args; x + y + z

nix-repl> f { z = 3; }
6

The { x ? 1, y ? 2, ... } syntax means x and y have defaults, while ... allows additional attributes.

@args binds the entire attribute set (args) so that we can access z, which wouldn’t be destructured by default.

When calling f { z = 3; }, we pass an extra attribute (z = 3), making x + y + z → 1 + 2 + 3 = 6.

Imports and namespaces

There is a keyword import, but it’s equivalent in other languages is eval. It can be used for namespacing too:

let
  pkgs = import <nixpkgs> {};
  lib = import <nixpkgs/lib>;
in
  pkgs.runCommand (lib.strings.removePrefix "....

consider using import here as using qualified import ... in Haskell or import ... in Python.

Another way of importing is with import ...;, which corresponds to Python from ... import *.

But because of not very great IDE support in Nix, with import ...; is discouraged. Rather use inherit, especially if you are targeting source code for Nix newcomers:

let
  lib = import <nixpkgs/lib>;
  inherit (lib.strings)
    removePrefix removeSuffix
  ;
  inherit (lib.lists)
    isList init drop
  ;
in
  removePrefix ...

inherit has higher priority than with, and conflicts with let

nix-repl> let pkgs = { x = 1; }; x = 2; x = 3; inherit (pkgs) x; in x
error: attribute ‘x’ at (string):1:31 already defined at (string):1:24

This makes it a sane citizen of Nix lanugage… except it has a twin, called { inherit ...; }. They DON’T do the same - let inherit ... adds let-bindings, and { inherit ...; } adds attributes to a record. –https://nixos.wiki/wiki/Nix_Language_Quirks

Only attribute names can be interpolated, not Nix code:

nix-repl> let ${"y"} = 4; in y
4

nix-repl> with { ${"y"} = 4; }; y
4

let y = 1; x = ${y}; in x
error: syntax error, unexpected DOLLAR_CURLY

Conclusion

let bindings introduce new local values and override anything from with.
with doesn’t create bindings - it only makes attributes available within its scope.
The order matters: If let x = 4 is outside with, then x = 4 already exists before with runs, so with pkgs; x resolves to 4, not the value from pkgs.

Resources

✔️ Resources (Click to Expand)

A few resources to help get you started with the Nix Language, I have actually grown to love the language. I find it fairly simple but powerful!

builtins.head[ 5 6 7 ]

Nix Package Manager

2025-11-22T00:00:00+00:00

Nix Package Manager

Click to Expand Table of Contents

Nix Package Manager

Nix is a purely functional package manager. This means that it treats packages like values in purely functional programming languages – they are built by functions that don’t have side-effects, and they never change after they have been built.

Nix stores packages in the Nix store, usually the directory /nix/store, where each package has its own unique subdirectory such as:

/nix/store/y53c0lamag5wpx7vsiv7wmnjdgq97yd6-yazi-25.5.14pre20250526_74a8ea9

You can use the Nix on most Linux distributions and Mac OS also has good support for Nix. It should work on most platforms that support POSIX threads and have a C++11 compiler.

When I install Nix on a distro like Arch Linux I usually use the Zero to Nix installer as it automates several steps, such as enabling flakes by default:

curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install

If you have concerns about the “curl to Bash” approach you could examine the installation script here then download and run it:

curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix > nix-installer.sh
chmod +x nix-installer.sh
./nix-installer.sh install

I got the above commands from zero-to-nix

The main difference between using the nix package manager on another distribution and NixOS is that NixOS uses Nix not just for package management but also to manage the system configuration (e.g., to build config files in /etc).

Home Manager is a Nix-powered tool for reproducible management of the contents of the users’ home directories. This includes programs, configuration files, environment variables, and arbitrary files. Home manager uses the same module system as NixOS.

Now that we’ve discussed some of the basics of the Nix package manager, lets see how it is used to build and manage software in NixOS.

Channels

Nix packages are distributed through Nix channels; mechanisms for distributing Nix expressions and the associated binary caches for them. Channels are what determine which versions your packages have. (i.e. stable or unstable). A channel is a name for the latest “verified” git commits in Nixpkgs. Each channel represents a different policy for what “verified” means. Whenever a new commit in Nixpkgs passes the verification process, the respective channel is updated to point to that new commit.

While channels provide a convenient way to get the latest stable or unstable packages, they introduce a challenge for strict reproducibility. Because a channel like nixos-unstable is constantly updated, fetching packages from it today might give you a different set of package versions than fetching from it tomorrow, even if your configuration remains unchanged. This “rolling release” nature at a global level can make it harder to share and reproduce exact development environments or system configurations across different machines or at different points in time.

Channels vs. Flakes Enhancing Reproducibility

Before the introduction of Nix Flakes, channels were the primary mechanism for sourcing Nixpkgs. While functional, they posed a challenge for exact reproducibility because they point to a moving target (the latest commit on a branch). This meant that a nix-build command run yesterday might produce a different result than one run today, simply because the channel updated.

Nix Flakes were introduced to address this. Flakes bring a built-in, standardized way to define the exact inputs to a Nix build, including the precise Git revision of Nixpkgs or any other dependency.

Here’s a quick comparison:

Feature	Nix Channels (traditional)	Nix Flakes (modern approach)
Input Source	Global system configuration (`nix-channel --update`)	Explicitly defined in `flake.nix` (e.g., `github:NixOS/nixpkgs/nixos-23.11`)
Reproducibility	“Rolling release”; less reproducible across time/machines	Highly reproducible due to locked inputs (`flake.lock`)
Dependency Mgmt.	Implicitly managed by global channel	Explicitly declared and version-locked within `flake.nix`
Sharing	Relies on users having same channel version	Self-contained; `flake.lock` ensures everyone gets same inputs
Learning Curve	Simpler initial setup, but tricky reproducibility debugging	Higher initial learning curve, but simplifies reproducibility

The ability of Flakes to “lock” the exact version of all dependencies in a flake.lock file is a game-changer for collaboration and long-term reproducibility, ensuring that your Nix configuration builds the same way, every time, everywhere.

Nixpkgs

Nixpkgs is the largest repository of Nix packages and NixOS modules.

For NixOS users, nixos-unstable channel branch is the rolling release, where the packages are tested and must pass integration tests.

For standalone Nix users, nixpkgs-unstable channel branch is the rolling release, where packages pass only basic build tests and are upgraded often.

For Flakes, as mentioned above they don’t use channels so nixpkgs will be listed as an input to your flake. (e.g., inputs.nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";) When using flakes you can actually disable channels and actually recommended to avoid conflicts between traditional channel-based workflows and the flake system.

Updates

The mechanism for updating your Nix environment differs fundamentally between channels and flakes, directly impacting reproducibility and control.

Updating with Channels (Traditional Approach)

With channels, updates are a global operation that pulls the latest state of a specific branch.

How it works: You typically use nix-channel --update to fetch the latest commit from the channels you’ve subscribed to. For instance, sudo nix-channel --update nixos (for NixOS) or nix-channel --update nixpkgs (for nix-env on other Linux distributions).

Implication: This command updates your local system’s understanding of what “nixos” or “nixpkgs-unstable” means. From that point on, any nixos-rebuild switch, nix-env -iA, or nix-build commands that implicitly or explicitly refer to nixpkgs will use this newly updated version.

Reproducibility Challenge: The update itself is not recorded in your configuration files. If you share your configuration.nix with someone, they might run nix-channel --update on a different day and get a different set of package versions because the channel has moved. This makes it challenging to guarantee that two users building the “same” configuration will get identical results. You’re effectively relying on the implicit, globally managed state of your channels.

Updating with Flakes (Modern Approach)

Flakes, by contrast, use a more explicit and localized update mechanism tied to your flake.lock file.

How it works: When you define a flake.nix, you specify the exact URL (e.g., a Git repository with a specific branch or tag) for each input. When you first use a flake, Nix resolves these URLs to a precise Git commit hash and records this hash, along with a content hash, in a flake.lock file.

To update your flake inputs, you run nix flake update.

Implication: This command goes to each input’s specified URL (e.g., github:NixOS/nixpkgs/nixos-unstable) and fetches the latest commit for that input. It then updates your flake.lock file with the new, precise Git commit hash and content hash for that input. Your flake.nix itself doesn’t change, but the flake.lock file now points to newer versions of your dependencies.

Reproducibility Advantage: The flake.lock file acts as a manifest of your exact dependency versions.

Sharing: When you share your flake (the flake.nix and flake.lock files), anyone using it will fetch precisely the same Git commit hashes recorded in the flake.lock, guaranteeing identical inputs and thus, identical builds (assuming the same system architecture).

Updating Selectively: You can update individual inputs within your flake by specifying them: nix flake update nixpkgs. This provides fine-grained control over which parts of your dependency graph you want to advance.

Rolling Back: Because the flake.lock explicitly records the versions, you can easily revert to a previous state by checking out an older flake.lock from your version control system.

In essence: Channels involve a global “pull” of the latest branch state, making reproducibility harder to guarantee across time and machines. Flakes, however, explicitly pin all inputs in flake.lock, and updates involve explicitly refreshing these pins, providing strong reproducibility and version control out of the box.

Managing software with Nix

Derivation Overview

In Nix, the process of managing software starts with package definitions. These are files written in the Nix language that describe how a particular piece of software should be built. These package definitions, when processed by Nix, are translated into derivations.

At its core, a derivation in Nix is a blueprint or a recipe that describes how to build a specific software package or any other kind of file or directory. It’s a declarative specification of:

Inputs: What existing files or other derivations are needed as dependencies.
Build Steps: The commands that need to be executed to produce the desired output.
Environment: The specific environment (e.g., build tools, environment variables) required for the build process.
Outputs: The resulting files or directories that the derivation produces.

Think of a package definition as the initial instructions, and the derivation as the detailed, low-level plan that Nix uses to actually perform the build.

Again, a derivation is like a blueprint that describes how to build a specific software package or any other kind of file or directory.

Key Characteristics of Derivations:

Declarative: You describe the desired outcome and the inputs, not the exact sequence of imperative steps. Nix figures out the necessary steps based on the builder and args.
Reproducible: Given the same inputs and build instructions, a derivation will always produce the same output. This is a cornerstone of Nix’s reproducibility.
Tracked by Nix: Nix keeps track of all derivations and their outputs in the Nix store. This allows for efficient management of dependencies and ensures that different packages don’t interfere with each other.
Content-Addressed: The output of a derivation is stored in the Nix store under a unique path that is derived from the hash of all its inputs and build instructions. This means that if anything changes in the derivation, the output will have a different path.

Here’s a simple Nix derivation that creates a file named hello in the Nix store containing the text “Hello, World!”:

✔️ Hello World Derivation Example (Click to expand):

{pkgs ? import <nixpkgs> {}}:
pkgs.stdenv.mkDerivation {
  name = "hello-world";

  dontUnpack = true;

  # No need for src = null; when dontUnpack = true;
  # src = null;

  buildPhase = ''
     # Create a shell script that prints "Hello, World!"
    echo '#!${pkgs.bash}/bin/bash' > hello-output-file # Shebang line
    echo 'echo "Hello, World!"' >> hello-output-file # The command to execute
    chmod +x hello-output-file # Make it executable
  '';

  installPhase = ''
    mkdir -p $out/bin
    cp hello-output-file $out/bin/hello # Copy the file from build directory to $out/bin
  '';

  meta = {
    description = "A simple Hello World program built with Nix";
    homepage = null;
    license = pkgs.lib.licenses.unfree; # licenses.mit is often used as well
    maintainers = [];
  };
}

And a default.nix with the following contents:

{ pkgs ? import <nixpkgs> {} }:

import ./hello.nix { pkgs = pkgs; }

{ pkgs ? import <nixpkgs> {} }: This is a function that takes an optional argument pkgs. We need Nixpkgs to access standard build environments like stdenv.
pkgs.stdenv.mkDerivation { ... }: This calls the mkDerivation function from the standard environment (stdenv). mkDerivation is the most common way to define software packages in Nix.
name = "hello-world";: Human-readable name of the derivation
The rest are the build phases and package metadata.

To use the above derivation, save it as a .nix file (e.g. hello.nix). Then build the derivation using,:

nix-build
this derivation will be built:
  /nix/store/9mc855ijjdy3r6rdvrbs90cg2gf2q160-hello-world.drv
building '/nix/store/9mc855ijjdy3r6rdvrbs90cg2gf2q160-hello-world.drv'...
Running phase: patchPhase
Running phase: updateAutotoolsGnuConfigScriptsPhase
Running phase: configurePhase
no configure script, doing nothing
Running phase: buildPhase
Running phase: installPhase
Running phase: fixupPhase
shrinking RPATHs of ELF executables and libraries in /nix/store/2ydxh5pd9a6djv7npaqi9rm6gmz2f73b-hello-world
checking for references to /build/ in /nix/store/2ydxh5pd9a6djv7npaqi9rm6gmz2f73b-hello-world...
patching script interpreter paths in /nix/store/2ydxh5pd9a6djv7npaqi9rm6gmz2f73b-hello-world
stripping (with command strip and flags -S -p) in  /nix/store/2ydxh5pd9a6djv7npaqi9rm6gmz2f73b-hello-world/bin
/nix/store/2ydxh5pd9a6djv7npaqi9rm6gmz2f73b-hello-world

Nix will execute the buildPhase and installPhase
After a successful build, the output will be in the Nix store. You can find the exact path by looking at the output of the nix build command (it will be something like /nix/store/your-hash-hello-world).

Run the “installed” program:

./result/bin/hello

This will execute the hello file from the Nix store and print "Hello, World!".

Nix Paths

2025-11-22T00:00:00+00:00

Nix Paths

✔️ Click to Expand Table of Contents

The following examples are done with a local nixpkgs clone located at ~/src/nixpkgs

Paths in Nix always need a / in them and always expand to absolute paths relative to your current directory.

nix repl
nix-repl> ./.
/home/jr/src/nixpkgs
nix-repl> ./. + "/lib"
/home/jr/src/nixpkgs/lib

Nix does path normalization every time you append strings, so if you just add a slash / its not actually there:

nix-repl> ./.
/home/jr/src/nixpkgs
nix-repl> ./. + "/"
/home/jr/src/nixpkgs
nix-repl> ./. + "/" + "lib"
/home/jr/src/nixpkgslib
nix-repl> "${./.}/lib"
# using ${./.} causes a store copy
copying '/homr/jr/src/nixpkgs' to the store
"/nix/store/3z9fzx8z03wslxvri5syv3jnnhn5fkbd-nixpkgs/lib"
nix-repl> "${toString ./.}/lib"
# using toString avoids making a store copy
"/home/jr/src/nixpkgs/lib"
nix-repl> ./lib/..             # nix removes all `..` to avoid redundant path resolutions
/home/jr/src/nixpkgs
nix-repl> :q

realpath ./lib/..
/home/jr/src/nixpkgs
ln -s pkgs/applications lib-symlink
realpath ./lib-symlink/..
/home/jr/src/nixpkgs/pkgs
nix repl
nix-repl> ./lib-symlink/..   # Nix doesn't read this file at all like realpath did
/home/jr/src/nixpkgs
nix-repl> builtins.readDir ./. # listing of all entries in current dir and their types
{
  ".devcontainer" = "directory";
  ".editorconfig" = "regular";
  ".git" = "directory";
  ".git-blame-ignore-revs" = "regular";
  ".gitattributes" = "regular";
  ".github" = "directory";
  ".gitignore" = "regular";
  ".mailmap" = "regular";
  ".mergify.yml" = "regular";
  ".version" = "symlink";
  "CONTRIBUTING.md" = "regular";
  COPYING = "regular";
  "README.md" = "regular";
  ci = "directory";
  "default.nix" = "regular";
  doc = "directory";
  "flake.nix" = "regular";
  lib = "directory";
  maintainers = "directory";
  nixos = "directory";
  pkgs = "directory";
  "shell.nix" = "regular";
}
nix-repl> builtins.readFile ./default.nix
"let\n  requiredVersion = import ./lib/minver.nix;\nin\n\nif !builtins ? nixVersion
 || builtins.compareVersions requiredVersion builtins.nixVersion == 1 then\n\n  abort
 ''\n\n    This version of Nixpkgs requires Nix >= \${requiredVersion}, please
 upgrade:\n\n    - If you are running NixOS, `nixos-rebuild' can be used to upgrade
 your system.\n\n    - Alternatively, with Nix > 2.0 `nix upgrade-nix' can be used
 to imperatively\n      upgrade Nix. You may use `nix-env --version' to check which
 version you have.\n\n    - If you installed Nix using the install script (https://nixos.org/nix/install),\n
  it is safe to upgrade by running it again:\n\n          curl -L https://nixos.org/nix/install | sh\n\n
For more information, please see the NixOS release notes at\n    https://nixos.org/nixos/manual
 or locally at\n    \${toString ./nixos/doc/manual/release-notes}.\n\n    If you need further help,
 see https://nixos.org/nixos/support.html\n  ''\n\nelse\n\n  import ./pkgs/top-level/impure.nix\n"
nix-repl> :l <nixpkgs/lib>
nix-repl> importJSON ./pkgs/development/python-modules/notebook/missing-hashes.json # Return the nix value for JSON
{
  "@nx/nx-darwin-arm64@npm:16.10.0" = "aabcc8499602b98c9fc3b768fe46dfd4e1b818caa84b740bd4f73a2e4528c719b979ecb1c10a0d793a1fead83073a08bc86417588046aa3e587e80af880bffd3";
  "@nx/nx-darwin-x64@npm:16.10.0" = "9dd20f45f646d05306f23f5abb7ade69dcb962e23a013101e93365847722079656d30a19c735fdcfa5c4e0fdf08691f9d621073c58aef2861c26741ff4638375";
  "@nx/nx-freebsd-x64@npm:16.10.0" = "35b93aabe3b3274d53157a6fc10fec7e341e75e6818e96cfbc89c3d5b955d225ca80a173630b6aa43c448c6b53b23f06a2699a25c0c8bc71396ee20a023d035f";
  "@nx/nx-linux-arm-gnueabihf@npm:16.10.0" = "697b9fa4c70f84d3ea8fe32d47635864f2e40b0ceeb1484126598c61851a2ec34b56bb3eeb9654c37d9b14e81ce85a36ac38946b4b90ca403c57fe448be51ccb";
  "@nx/nx-linux-arm64-gnu@npm:16.10.0" = "001e71fedfc763a4dedd6c5901b66a4a790d388673fb74675235e19bb8fe031ff3755568ed867513dd003f873901fabda31a7d5628b39095535cb9f6d1dc7191";
  "@nx/nx-linux-arm64-musl@npm:16.10.0" = "58e3b71571bdadd2b0ddd24ea6e30cd795e706ada69f685403412c518fba1a2011ac8c2ac46145eab14649aa5a78e0cedcdb4d327ccb3b6ec12e055171f3840b";
  "@nx/nx-linux-x64-gnu@npm:16.10.0" = "97729a7efb27301a67ebf34739784114528ddb54047e63ca110a985eaa0763c5b1ea7c623ead1a2266d07107951be81e82ffa0a30e6e4d97506659303f2c8c78";
  "@nx/nx-linux-x64-musl@npm:16.10.0" = "442bdbd5e61324a850e4e7bd6f54204108580299d3c7c4ebcec324da9a63e23f48d797a87593400fc32af78a3a03a3c104bfb360f107fe732e6a6c289863853a";
  "@nx/nx-win32-arm64-msvc@npm:16.10.0" = "b5c74184ebfc70294e85f8e309f81c3d40b5cf99068891e613f3bef5ddb946bef7c9942d9e6c7688e22006d45d786342359af3b4fc87aadf369afcda55c73187";
  "@nx/nx-win32-x64-msvc@npm:16.10.0" = "c5b174ebd7a5916246088e17d3761804b88f010b6b3f930034fa49af00da33b6d1352728c733024f736e4c2287def75bafdc3d60d8738bd24b67e9a4f11763f8";
}
nix-repl> builtins.toJSON  # serialize
«primop toJSON»
nix-repl> builtins.fromTOML
«primop fromTOML»
nix-repl> builtins.toXML

For more serialization formats see nixpkgs/lib/generators.nix as well as in nixpkgs/pkgs/pkgs-lib/formats/ we can see them with the nix repl as follows:

cd ~/src/nixpkgs
nix repl
nix-repl> :l .
nix-repl> lib.generators.toYAML {} { a = 10; }
"{\"a\":10}"
nix-repl> lib.generators.toYAML {} { a.b.c = 10; }
"{\"a\":{\"b\":{\"c\":10}}}"
nix-repl> builtins.trace (lib.generators.toYAML {} { a.b.c = 10; }) null
trace: {"a":{"b":{"c":10}}}
null
nix-repl> yamlFormat = pkgs.formats.yaml {}

nix-repl> yamlFormat
{
  generate = «lambda generate @ /home/jr/src/nixpkgs/pkgs/pkgs-lib/formats.nix:111:9»;
  type = { ... };
}

We can see that it provides a generate function that we can use. generate doesn’t just generate a string anymore because if we want to lift the restriction at evaluation time we can’t return the formatted form at evaluation time anymore. We need a name to return a derivation continued below:

yamlFormat.generate "name" { a.b.c = 10; }
«derivation /nix/store/xakajb2rzbmqqkjbh08bxwqdf0xqvjly-name.drv»
nix-repl> :b yamlFormat.generate "name" { a.b.c = 10; }
This derivation produced the following outputs:
out -> /nix/store/y4c5029k6w3l0qmdw7cq396zrdy5x8yj-name
nix-repl> :q

Let’s cat the result to see if it’s formatted correctly as YAML:

cat /nix/store/y4c5029k6w3l0qmdw7cq396zrdy5x8yj-name
───────┬───────────────────────────────────────────────────────────────
       │ File: /nix/store/y4c5029k6w3l0qmdw7cq396zrdy5x8yj-name
───────┼──────────────────────────────────────────────────────────────
   1   │ a:
   2   │   b:
   3   │     c: 10
───────┴───────────────────────────────────────────────────────────

Looks good. There is also a type:

nix repl
nix-repl> :l .
nix-repl> yamlFormat = pkgs.format.yaml {}
nix-repl> yamlFormat.type
{
  _type = "option-type";
  check = «lambda check @ /home/jr/src/nixpkgs/lib/types.nix:1029:19»;
  deprecationMessage = null;
  description = "YAML value";
  descriptionClass = "conjunction";
  emptyValue = { ... };
  functor = { ... };
  getSubModules = null;
  getSubOptions = «lambda @ /home/jr/src/nixpkgs/lib/types.nix:214:25»;
  merge = «lambda merge @ /home/jr/src/nixpkgs/lib/types.nix:1031:13»;
  name = "nullOr";
  nestedTypes = { ... };
  substSubModules = «lambda substSubModules @ /home/jr/src/nixpkgs/lib/types.nix:1046:29»;
  typeMerge = «lambda defaultTypeMerge @ /home/jr/src/nixpkgs/lib/types.nix:115:10»;
}
nix-repl> lib.modules.mergeDefinitions [] yamlFormat.type [ { value = null; } ]
{
  defsFinal = [ ... ];
  defsFinal' = { ... };
  isDefined = true;
  mergedValue = null;
  optionalValue = { ... };
}
nix-repl> (lib.modules.mergeDefinitions [] yamlFormat.type [ { value = null; } ]).mergedValue
null
nix-repl> :p (lib.modules.mergeDefinitions [] yamlFormat.type [ { value = { a.b.c = 10; }; } ]).mergedValue
{
  a = {
    b = { c = 10; };
  };
}
nix-repl> :p (lib.modules.mergeDefinitions [] yamlFormat.type [ { value = { a.b.c = 10; }; } { value = { a.b.d = 20; }; } ]).mergedValue
{
  a = {
    b = {
      c = 10;
      d = 20;
    };
  };
}

lib can’t access any packages, it is entirely at evaluation time. It can’t access any formatters or things like that. If we lift that restriction as is done in pkgs.formats we can make it look much nicer.

cd ~/src/nixpkgs
nix-build -A hello
warning: Nix search path entry '/nix/var/nix/profiles/per-user/root/channels' does not exist, ignoring
this path will be fetched (0.06 MiB download, 0.26 MiB unpacked):
  /nix/store/29mhfr5g4dsv07d80b7n4bgs45syk3wl-hello-2.12.2
copying path '/nix/store/29mhfr5g4dsv07d80b7n4bgs45syk3wl-hello-2.12.2' from 'https://cache.nixos.org'...
/nix/store/29mhfr5g4dsv07d80b7n4bgs45syk3wl-hello-2.12.2

Say we rely on this store path in a derivation:

nix-repl> thePath = "/nix/store/29mhfr5g4dsv07d80b7n4bgs45syk3wl-hello-2.12.2"
nix-repl> thePath + "/bin/hello"
"/nix/store/29mhfr5g4dsv07d80b7n4bgs45syk3wl-hello-2.12.2/bin/hello"

hx ~/src/nixpkgs/test2.nix

# test2.nix
with import ./. {};

runCommand "test" {
    nativeBuildInputs = [
        hello
    ];
}''
  hello > $out
''

Try building it:

nix-build test2.nix && cat result
warning: Nix search path entry '/nix/var/nix/profiles/per-user/root/channels' does not exist, ignoring
/nix/store/m55p4vpb8s7s28s20vs89i467kxbrdac-test
Hello, world!

Now if we try it with the store path:

# test2.nix
with import ./. {};

runCommand "test" {
}''
  /nix/store/29mhfr5g4dsv07d80b7n4bgs45syk3wl-hello-2.12.2/bin/hello > $out
''

This doesn’t work

nix-build test2.nix
last 1 log lines:
> /build/.attr-0l2nkwhif96f51f4amnlf414lhl4rv9vh8iffyp431v6s28gsr90: line 1: /nix/store/29mhfr5g4dsv07d80b7n4bgs45syk3wl-hello-2.12.2/bin/hello: No such file or directory
For full logs, run:
nix log /nix/store/58zcp9xwgf1sirmzf9sh61j8gz9lkw34-test.drv
nix-instantiate test2.nix
/nix/store/58zcp9xwgf1sirmzf9sh61j8gz9lkw34-test.drv
nix derivation show /nix/store/58zcp9xwgf1sirmzf9sh61j8gz9lkw34-test.drv | jq
{
  "/nix/store/58zcp9xwgf1sirmzf9sh61j8gz9lkw34-test.drv": {
    "args": [
      "-e",
      "/nix/store/vj1c3wf9c11a0qs6p3ymfvrnsdgsdcbq-source-stdenv.sh",
      "/nix/store/shkw4qm9qcw5sc5n1k5jznc83ny02r39-default-builder.sh"
    ],
    "builder": "/nix/store/xy4jjgw87sbgwylm5kn047d9gkbhsr9x-bash-5.2p37/bin/bash",
    "env": {
      "__structuredAttrs": "",
      "buildCommand": "/nix/store/29mhfr5g4dsv07d80b7n4bgs45syk3wl-hello-2.12.2/bin/hello > $out\n",
      "buildInputs": "",
      "builder": "/nix/store/xy4jjgw87sbgwylm5kn047d9gkbhsr9x-bash-5.2p37/bin/bash",
      "cmakeFlags": "",
      "configureFlags": "",
      "depsBuildBuild": "",
      "depsBuildBuildPropagated": "",
      "depsBuildTarget": "",
      "depsBuildTargetPropagated": "",
      "depsHostHost": "",
      "depsHostHostPropagated": "",
      "depsTargetTarget": "",
      "depsTargetTargetPropagated": "",
      "doCheck": "",
      "doInstallCheck": "",
      "enableParallelBuilding": "1",
      "enableParallelChecking": "1",
      "enableParallelInstalling": "1",
      "mesonFlags": "",
      "name": "test",
      "nativeBuildInputs": "",
      "out": "/nix/store/ljrkx5midby3j7p4g96d74jrq8f9rpya-test",
      "outputs": "out",
      "passAsFile": "buildCommand",
      "patches": "",
      "propagatedBuildInputs": "",
      "propagatedNativeBuildInputs": "",
      "stdenv": "/nix/store/aq801xbgs98nxx3lckrym06qfvl8mfsf-stdenv-linux",
      "strictDeps": "",
      "system": "x86_64-linux"
    },
    "inputDrvs": {
      "/nix/store/bmncp7arkdhrl6nkyg0g420935x792gl-stdenv-linux.drv": {
        "dynamicOutputs": {},
        "outputs": [
          "out"
        ]
      },
      "/nix/store/rfkzz952hz2d58d90mscxvk87v5wa5bz-bash-5.2p37.drv": {
        "dynamicOutputs": {},
        "outputs": [
          "out"
        ]
      }
    },
    "inputSrcs": [
      "/nix/store/shkw4qm9qcw5sc5n1k5jznc83ny02r39-default-builder.sh",
      "/nix/store/vj1c3wf9c11a0qs6p3ymfvrnsdgsdcbq-source-stdenv.sh"
    ],
    "name": "test",
    "outputs": {
      "out": {
        "path": "/nix/store/ljrkx5midby3j7p4g96d74jrq8f9rpya-test"
      }
    },
    "system": "x86_64-linux"
  }
}

You see the "inputDrvs", they are the derivations that we depend on and it doesn’t know about the hello.drv. In Nix for the builder sandbox it creates a sandbox that only contains the derivations that you depend on which ensures that you can’t depend on any derivation that you haven’t explicitly decalred.

Nix does have builtins.storePath that allows you to do this, otherwise it’s kind of an anti pattern.

# test2.nix
# test2.nix
# test2.nix
with import ./. {};
  runCommand "test" {
  } ''
    ${builtins.storePath "/nix/store/29mhfr5g4dsv07d80b7n4bgs45syk3wl-hello-2.12.2"}/bin/hello > $out
  ''

builtins.storePath: Turns a store path into the thing that it represents in the store.

nix-build test2.nix && cat result
/nix/store/x48741w0k9hgqywzv6wc7rk90r1y75js-test
Hello, world!

To demonstrate what builtins.storePath does:

nix-repl> builtins.storePath "/nix/store/29mhfr5g4dsv07d80b7n4bgs45syk3wl-hello-2.12.2/bin/hello"
"/nix/store/29mhfr5g4dsv07d80b7n4bgs45syk3wl-hello-2.12.2/bin/hello"
nix-repl> builtins.getContext "/nix/store/29mhfr5g4dsv07d80b7n4bgs45syk3wl-hello-2.12.2"
{ }
nix-repl> builtins.getContext (builtins.storePath "/nix/store/29mhfr5g4dsv07d80b7n4bgs45syk3wl-hello-2.12.2")
{
  "/nix/store/29mhfr5g4dsv07d80b7n4bgs45syk3wl-hello-2.12.2" = { ... };
}
nix-repl> :p builtins.getContext (builtins.storePath "/nix/store/29mhfr5g4dsv07d80b7n4bgs45syk3wl-hello-2.12.2")
{
  "/nix/store/29mhfr5g4dsv07d80b7n4bgs45syk3wl-hello-2.12.2" = { path = true; };
}

nix-repl> :l .
warning: Nix search path entry '/nix/var/nix/profiles/per-user/root/channels' does not exist, ignoring
Added 24878 variables.

nix-repl> hello.outPath
# this is the output path of the hello derivation
"/nix/store/29mhfr5g4dsv07d80b7n4bgs45syk3wl-hello-2.12.2"
nix-repl> :p builtins.getContext hello.outPath
# we see that this is a `.drv`, this is because derivations can have multiple outputs
{
  "/nix/store/ljxsxdy1syy03b9kfnnh8x7zsk21fdcq-hello-2.12.2.drv" = {
    outputs = [ "out" ];
  };
}
# for example
nix-repl> openssl.outputs
[
  "bin"
  "dev"
  "out"
  "man"
  "doc"
  "debug"
]
nix-repl> openssl.all
# a list of all the derivations
[
  «derivation /nix/store/rw3y8k94ib37dc86n0wivr551wyzxgsk-openssl-3.4.1.drv»
  «derivation /nix/store/rw3y8k94ib37dc86n0wivr551wyzxgsk-openssl-3.4.1.drv»
  «derivation /nix/store/rw3y8k94ib37dc86n0wivr551wyzxgsk-openssl-3.4.1.drv»
  «derivation /nix/store/rw3y8k94ib37dc86n0wivr551wyzxgsk-openssl-3.4.1.drv»
  «derivation /nix/store/rw3y8k94ib37dc86n0wivr551wyzxgsk-openssl-3.4.1.drv»
  «derivation /nix/store/rw3y8k94ib37dc86n0wivr551wyzxgsk-openssl-3.4.1.drv»
]
nix-repl> lib.concatStringsSep " " openssl.all
"/nix/store/rjzx8v679rwd6dsb6s08iy3j2rrax72s-openssl-3.4.1-bin /nix/store/kcgqglb4iax0zh5jlrxmjdik93wlgsrq-openssl-3.4.1-dev /nix/store/8pviily4fgsl02ijm65binz236717wfs-openssl-3.4.1 /nix/store/1l5b31cnswnbcdcac9rzs9xixnc2n9r5-openssl-3.4.1-man /nix/store/9fz5qmj0z70cbzy7mapml0sbi8z6ap0a-openssl-3.4.1-doc /nix/store/yk2g2gfcj2fy1ffyi1g91q7jmp4h8pxa-openssl-3.4.1-debug"
nix-repl> :p builtins.getContext (builtins.unsafeDiscardOutputDependency (lib.concatStringsSep " " openssl.all))
{
  "/nix/store/rw3y8k94ib37dc86n0wivr551wyzxgsk-openssl-3.4.1.drv" = {
    outputs = [
      "bin"
      "debug"
      "dev"
      "doc"
      "man"
      "out"
    ];
  };
}
nix-repl> :p builtins.getContext openssl.drvPath
{
  "/nix/store/rw3y8k94ib37dc86n0wivr551wyzxgsk-openssl-3.4.1.drv" = { allOutputs = true; };
}
# useful if you need to create a derivation that copies this derivation to another machine
# remote builders usually take care of this but you may need it occasionally
nix-repl> :p builtins.getContext (builtins.unsafeDiscardOutputDependency openssl.drvPath)
{
  "/nix/store/rw3y8k94ib37dc86n0wivr551wyzxgsk-openssl-3.4.1.drv" = { path = true; };
}

Relying on paths outside of the nix store is generally not recommended because of garbage collection and it’s considered unsafe.

Practical Nix Functions

2025-11-22T00:00:00+00:00

Practical Nix Functions

✔️ If you want to follow along with this example you'll have to place the following in your project directory. Section is collapsed to focus on functions:

graphviz
hello
autotools.nix:

# autotools.nix
pkgs: attrs:
with pkgs; let
  defaultAttrs = {
    builder = "${bash}/bin/bash";
    args = [./builder.sh];
    setup = ./setup.sh;
    baseInputs = [gnutar gzip gnumake gcc binutils-unwrapped coreutils gawk gnused gnugrep patchelf findutils];
    buildInputs = [];
    system = builtins.currentSystem;
  };
in
  derivation (defaultAttrs // attrs)

setup.sh:

# setup.sh (This is a library of functions setting up the environment, not directly executable)
unset PATH
for p in $baseInputs $buildInputs; do
  if [ -d $p/bin ]; then
    export PATH="$p/bin${PATH:+:}$PATH"
  fi
  if [ -d $p/lib/pkgconfig ]; then
    export PKG_CONFIG_PATH="$p/lib/pkgconfig${PKG_CONFIG_PATH:+:}$PKG_CONFIG_PATH"
  fi
done

function unpackPhase() {
  tar -xzf $src

  for d in *; do
    if [ -d "$d" ]; then
      cd "$d"
      break
    fi
  done
}

function configurePhase() {
  ./configure --prefix=$out
}

function buildPhase() {
  make
}

function installPhase() {
  make install
}

function fixupPhase() {
  find $out -type f -exec patchelf --shrink-rpath '{}' \; -exec strip '{}' \; 2>/dev/null
}

function genericBuild() {
  unpackPhase
  configurePhase
  buildPhase
  installPhase
  fixupPhase
}

And finally builder.sh:

# builder.sh (This is the actual builder script specified in the derivation and
# what `nix-build` expects)
set -e
source $setup
genericBuild

This is another example from the Nix-Pill series shown in another way to show some powerful aspects of functions.

If you have a default.nix like this:

# default.nix
{
  hello = import ./hello.nix;
  graphviz = import ./graphviz.nix;
}

It expects the files that it imports to look like this:

# graphviz.nix
let
  pkgs = import <nixpkgs> { };
  mkDerivation = import ./autotools.nix pkgs;
in
mkDerivation {
  name = "graphviz";
  src = ./graphviz-2.49.3.tar.gz;
}

And hello.nix:

# hello.nix
let
  pkgs = import <nixpkgs> { };
  mkDerivation = import ./autotools.nix pkgs;
in
mkDerivation {
  name = "hello";
  src = ./hello-2.12.1.tar.gz;
}

You would build these with:

nix-build -A hello
nix-build -A graphviz

As you can see both derivations are dependendent on nixpkgs which they both import directly. To centralize our dependencies and avoid redundant imports, we’ll refactor our individual package definitions (hello.nix, graphviz.nix) into functions. Our default.nix will then be responsible for setting up the common inputs (like pkgs and mkDerivation) and passing them as arguments when it imports and calls these package functions.

Here is what our default.nix will look like:

let
  pkgs = import <nixpkgs> { };
  mkDerivation = import ./autotools.nix pkgs;
in
with pkgs;
{
  hello = import ./hello.nix { inherit mkDerivation; };
  graphviz = import ./graphviz.nix {
    inherit
      mkDerivation
      lib
      gd
      pkg-config
      ;
  };
  graphvizCore = import ./graphviz.nix {
    inherit
      mkDerivation
      lib
      gd
      pkg-config
      ;
    gdSupport = false;
  };
}

We define some local variables in the let expression and pass them around.

The whole expression in the above default.nix returns an attribute set with the keys hello, graphviz, and graphvizCore

We import hello.nix and graphviz.nix, which both return a function. We call the functions, passing them a set of inputs with the inherit construct.

Let’s change hello.nix into a function to match what the default.nix now expects.

# hello.nix
{mkDerivation}:
mkDerivation {
  name = "hello";
  src = ./hello-2.12.1.tar.gz;
}

Now our graphviz attribute expects graphviz.nix to be a function that takes the arguments listed in the above default.nix, here’s what graphviz.nix will look like as a function:

# graphviz.nix
{
  mkDerivation,
  lib,
  gdSupport ? true,
  gd,
  pkg-config,
}:
mkDerivation {
  name = "graphviz";
  src = ./graphviz-2.49.3.tar.gz;
  buildInputs =
    if gdSupport
    then [
      pkg-config
      (lib.getLib gd)
      (lib.getDev gd)
    ]
    else [];
}

We factorized the import of nixpkgs and mkDerivation, and also added a variant of graphviz with gd support disabled. The result is that both hello.nix and graphviz.nix are independent of the repository and customizable by passing specific inputs.

Now, we can build the package with gd support disabled with the graphvizCore attribute:

nix-build -A graphvizCore
# or we can still build the package that now defaults to gd support
nix-build -A graphviz

This example showed us how to turn expressions into functions. We saw how functions are passed around and shared between Nix expressions and derivations.

Overlays

2025-11-22T00:00:00+00:00

Extending Flakes with Custom Packages using Overlays

✔️ Click to Expand Table of Contents

–pokego repo

Overlays are Nix functions that accept two arguments, final and prev and return a set of packages. Overlays are similar to packageOverrides as a way to customize Nixpkgs, packageOverrides acts as an overlay with only the prev argument. Therefore, packageOverrides is appropriate for basic use, but overlays are more powerful and easier to distribute.

Example:

final: prev: {
  firefox = prev.firefox.overrideAttrs (old: {
    buildInputs = (old.buildInputs or []) ++ [ prev.vlc ];
    env.FIREFOX_DISABLE_GMP_UPDATER = "1";
  });
}

To see the original derivation, run nix edit -f "<nixpkgs>" firefox.

This modifies Firefox by:

Adding vlc to buildInputs, useful if a package requires additional dependencies.
Setting an environment variable (FIREFOX_DISABLE_GMP_UPDATER=1) to disable automatic updates of the Gecko Media Plugin.

It is very common to use overlays in Nix to install packages that aren’t available in the standard Nixpkgs repository.

Overlays are one of the primary and recommended ways to extend and customize your Nix environment. It’s important to remember that Nix overlays are made to allow you to modify or extend the package set provided by Nixpkgs (or other Nix sources) without directly altering the original package definitions. This is crucial for maintaining reproducibility and avoiding conflicts. Overlays are essentially functions that take the previous package set and allow you to add, modify, or remove packages.

To better understand the structure of my flake.nix it may be helpful to first read This blog post first.

Adding the overlays output to your Flake

I’ll show the process of adding the pokego package that is not in Nixpkgs:

In my flake.nix I have a custom inputs variable within my let block of my flake like so just showing the necessary parts for brevity:

# flake.nix
  outputs = my-inputs @ {
    self,
    nixpkgs,
    treefmt-nix,
    ...
  }: let
    system = "x86_64-linux";
    host = "magic";
    userVars = {
      username = "jr";
      gitUsername = "saylesss88";
      editor = "hx";
      term = "ghostty";
      keys = "us";
      browser = "firefox";
      flake = builtins.getEnv "HOME" + "/flake";
    };

    inputs =
      my-inputs
      // {
        pkgs = import inputs.nixpkgs {
          inherit system;
        };
        lib = {
          overlays = import ./lib/overlay.nix;
          nixOsModules = import ./nixos;
          homeModules = import ./home;
          inherit system;
        };
      };
      # ... snip ...

Why I Created inputs.lib in My flake.nix. In the above example, you’ll notice a lib attribute defined within the main let block.
- This might seem a bit unusual at first, as inputs are typically defined at the top level of a flake. However, this structure provides a powerful way to organize and reuse common Nix functions and configurations across my flake.
- By bundling my custom logic and modules into inputs.lib, I can pass inputs (which now includes my custom lib) as a specialArgs to other modules. This provides a clean way for all modules to access these shared resources. For example, in configuration.nix, inputs.lib.overlays directly references my custom overlay set.
- My inputs.lib is my own project-specific library, designed to hold functions and attribute sets relevant to my flake’s custom configurations. While nixpkgs.lib is globally available, my custom lib contains my unique additions.

While defining inputs within the let block to achieve this structure is a personal preference and works well for my setup, the core benefit is the creation of a dedicated, centralized lib attribute that encapsulates my flake’s reusable Nix code, leading to a more organized and maintainable configuration.

The Actual Overlay

In the overlay.nix I have this helper function and the defined package:

# overlay.nix
_final: prev: let
  # Helper function to import a package
  callPackage = prev.lib.callPackageWith (prev // packages);

  # Define all packages
  packages = {
    # Additional packages
    pokego = callPackage ./pac_defs/pokego.nix {};
  };
in
  packages

_final: prev:: This is the function definition of the overlay.

_final: This argument represents the final, merged package set after all overlays have been applied. It’s often unused within a single overlay, hence the _ prefix (a Nix convention for unused variables).
prev: This is the crucial argument. It represents the package set before this overlay is applied. This allows you to refer to existing packages and functions from Nixpkgs.

let ... in packages: This introduces a let expression, which defines local variables within the scope of this overlay function. The in packages part means that the overlay function will ultimately return the packages attribute set defined within the let block.
callPackage = prev.lib.callPackageWith (prev // packages): This line defines a helper function called callPackage.

prev.lib.callPackageWith Is a function provided by Nixpkgs’ lib. callPackageWith is like prev.lib.callPackage, but allows the passing of additional arguments that will then be passed to the package definition.
(prev // packages): This is an attribute set merge operation. It takes the prev package set (Nixpkgs before this overlay) and merges it with the packages attribute set defined later in this overlay.
By using callPackageWith with this merged attribute set, the callPackage function defined here is set up to correctly import package definitions, ensuring they have access to both the original Nixpkgs and any other packages defined within this overlay.

packages = { ... };: This defines an attribute set named packages. This set will contain all the new or modified packages introduced by this overlay.
pokego = callPackages ./pac_defs/pokego.nix { };: This is the core of how the pokego package is added.

pokego =: This defines a new attribute named pokego within the packages attribute set. This name will be used to refer to the pokego package later.
callPackage ./pac_defs/pokego.nix {}: This calls the callPackage helper function defined earlier.
./pac_defs/pokego.nix: This is the path to another Nix file(pokego.nix) that contains the actual package definition for pokego. This file would define how to fetch, build, and install the pokego software
{}: This is an empty attribute set passed as additional arguments to the pokego.nix package definition. If pokego.nix expected any specific parameters (like versions or dependencies), you would provide them here. Since it’s empty, it implies pokego.nix either has no required arguments or uses default values.

in packages: As mentioned earlier, the overlay function returns the packages attribute set. When this overlay is applied, the packages defined within this packages set (including pokego) will be added to the overall Nix package set.

The pokego Package definition

The following is the ./pac_defs/pokego.nix:

# pokego.nix
{
  lib,
  buildGoModule,
  fetchFromGitHub,
}:
buildGoModule rec {
  pname = "pokego";
  version = "0.3.0";

  src = fetchFromGitHub {
    owner = "rubiin";
    repo = "pokego";
    rev = "v${version}";
    hash = "sha256-cFpEi8wBdCzAl9dputoCwy8LeGyK3UF2vyylft7/1wY=";
  };

  vendorHash = "sha256-7SoKHH+tDJKhUQDoVwAzVZXoPuKNJEHDEyQ77BPEDQ0=";

  # Install shell completions
  postInstall = ''
    install -Dm644 completions/pokego.bash "$out/share/bash-completion/completions/pokego"
    install -Dm644 completions/pokego.fish "$out/share/fish/vendor_completions.d/pokego.fish"
    install -Dm644 completions/pokego.zsh "$out/share/zsh/site-functions/_pokego"
  '';

  meta = with lib; {
    description = "Command-line tool that lets you display Pokémon sprites in color directly in your terminal";
    homepage = "https://github.com/rubiin/pokego";
    license = licenses.gpl3Only;
    maintainers = with maintainers; [
      rubiin
      jameskim0987
      vinibispo
    ];
    mainProgram = "pokego";
    platforms = platforms.all;
  };
}

Adding the overlay to your configuration

There are a few places you could choose to put the following, I choose to use my configuration.nix because of my setup:

# configuration.nix
nixpkgs.overlays = [inputs.lib.overlays]

Installing Pokego

If you are managing your entire system configuration with NixOS, you would typically add pokego to your environment.systemPackages.

# configuration.nix
environment.systemPackages = with pkgs; [
  pokego
]

If you prefer home-manager you can install pokego with home-manager also:

# home.nix
home.packages = [
  pkgs.pokego
]

Another Overlay Example

{
  inputs = {
    nixpkgs.url = "https://flakehub.com/NixOS/nixpkgs/*.tar.gz";

    nix.url = "https://flakehub.com/f/NixOS/nix/2.17.0.tar.gz";
  };

  outputs = { self, nixpkgs, nix }:

    let
      system = "aarch64-darwin";
      pkgs = import nixpkgs {
        inherit system;
        overlays = [
          nix.overlays.default
        ];
      };
    in
    {
     # `pkgs` is nixpkgs for the system, with nix's overlay applied
    };
}

Normally, pkgs = import nixpkgs { }`` imports Nixpkgs with default settings. However, the example above customizes this import by passing arguments: pkgs = import nixpkgs { inherit system; overlays = [ nix.overlays.default];}. This makes the pkgs variable represent nixpkgs specifically for the aarch64-darwin` system, with the overlay from the nix flake applied.
Consequently, any packages built using this customized pkgs will now depend on or use the specific nix version (2.17.0) provided by the nix flake, instead of the version that comes with the fetched nixpkgs. This technique can be useful for ensuring a consistent environment or testing specific package versions.

Customizing Nixpkgs Imports and Overlays

While overlays are typically used to add or modify packages within a single nixpkgs instance, Nix’s lazy evaluation and flake inputs allow for even more powerful scenarios. You can have multiple versions of nixpkgs in a single flake, and they will only be evaluated when a package from that specific version is actually referenced. This complements overlays by giving you fine-grained control over which nixpkgs instance an overlay applies to, or which nixpkgs version a specific part of your project depends on.

Consider this example where we import nixpkgs with a specific overlay applied directly at the import site:

{
  inputs = {
    nixpkgs.url = "[https://flakehub.com/NixOS/nixpkgs/*.tar.gz](https://flakehub.com/NixOS/nixpkgs/*.tar.gz)"; # This will be the base nixpkgs

    nix.url = "[https://flakehub.com/f/NixOS/nix/2.17.0.tar.gz](https://flakehub.com/f/NixOS/nix/2.17.0.tar.gz)"; # This flake provides an overlay for a specific Nix version
  };

  outputs = { self, nixpkgs, nix }:

    let
      system = "aarch64-darwin";
      # Here, we import nixpkgs and apply the 'nix' flake's overlay.
      # This 'pkgs' variable now holds a customized Nix package set.
      # In this 'pkgs' set, the 'nix' package (and anything that depends on it)
      # will be version 2.17.0 as defined by the 'nix' flake's overlay.
      pkgs_with_custom_nix = import nixpkgs {
        inherit system;
        overlays = [
          nix.overlays.default # Apply the overlay from the 'nix' flake here
        ];
      };
    in
    {
      # We can then expose packages or devShells that use this customized `pkgs` set.
      devShells.${system}.default = pkgs_with_custom_nix.mkShell {
        packages = [
          pkgs_with_custom_nix.nix # This 'nix' package is now version 2.17.0 due to the overlay!
        ];
        shellHook = ''
          echo "Using Nix version: <span class="math-inline">\(nix \-\-version\)"
'';
};
# You can also make this customized package set available as a top-level overlay
# if other parts of your flake or configuration want to use it.
# overlays.custom-nix-version = final: prev: {
#   inherit (pkgs_with_custom_nix) nix; # Expose the specific nix package from our overlayed pkgs
# };
# You can also import multiple versions of nixpkgs and select packages from them:
# pkgs-2505 = import (inputs.nixpkgs-2505 or nixpkgs) { inherit system; }; # Example, assuming 2505 is an input
# packages.</span>{system}.my-tool-2505 = pkgs-2505.myTool; # Using a package from a specific stable version
    };
}

Normally, pkgs = import nixpkgs { } imports Nixpkgs with default settings. However, the example above customizes this import by passing arguments: pkgs = import nixpkgs { inherit system; overlays = [ nix.overlays.default];}. This makes the pkgs_with_custom_nix variable represent Nixpkgs specifically for the aarch64-darwin system, with the overlay from the nix flake applied at the time of import.

Consequently, any packages built using this customized pkgs_with_custom_nix will now depend on or use the specific Nix version (2.17.0) provided by the nix flake’s overlay, instead of the version that comes with the base nixpkgs input. This technique is highly useful for ensuring a consistent environment or testing specific package versions without affecting the entire system’s nixpkgs set.

Specialisations

2025-11-22T00:00:00+00:00

NixOS Specialisations For Multiple Profiles

✔️ Click to Expand Table of Contents

NixOS specialisations are a powerful feature that allow you to define alternative system configurations variations within a single NixOS setup. Each specialisation can modify or extend the base configuration, and NixOS will generate separate boot entries for each, letting you choose at boot time (or switch at runtime) which environment to use. This is ideal for testing, hardware-specific tweaks, or separating work and personal environments without maintaining multiple configuration files

How Specialisations Work

Specialisations are defined as attributes under the specialisation option in your configuration. Each key (e.g., niri-test) represents a named specialisation, and its configuration attribute contains the NixOS options to apply on top of the base system

By default, a specialisation inherits the parent configuration and applies its changes on top. You can also set inheritParentConfig = false; to create a completely separate configuration.

After running nixos-rebuild boot, your bootloader will present extra entries for each specialisation. Selecting one boots into the system with that specialisation’s settings applied

Runtime Switching: You can switch to a specialisation at runtime using activation scripts, e.g.:

nixos-rebuild switch --specialisation niri-test

/run/current-system/specialisation/niri-test/bin/switch-to-configuration switch

Note: Some changes (like kernel switches) require a reboot to take effect

Example: Let’s create a basic specialisation to try out the Niri Window Manager:

First we have to add the niri-flake as an input to our flake.nix and add the module to install it:

# flake.nix
inputs = {
     niri.url = "github:sodiboo/niri-flake";
};

# configuration.nix
{ pkgs, inputs, ... }: {
# ... snip ...
imports = [
    inputs.niri.nixosModules.niri
];

# This is the top-level overlay
  nixpkgs.overlays = [inputs.niri.overlays.niri];

# ... snip ...

  specialisation = {
    niri-test.configuration = {
      system.nixos.tags = ["niri"];

      # Add the Niri overlay for this specialisation
      nixpkgs.overlays = [inputs.niri.overlays.niri];

      # Enable Niri session
      programs.niri = {
        enable = true;
        package = pkgs.niri-unstable;
      };

      # Optionally, add a test user and greetd for login
      users.users.niri = {
        isNormalUser = true;
        extraGroups = ["networkmanager" "video" "wheel"];
        initialPassword = "test"; # for testing only!
        createHome = true;
      };

      services.greetd = {
        enable = true;
        settings = rec {
          initial_session = {
            command = lib.mkForce "${pkgs.niri}/bin/niri";
            user = lib.mkForce "niri";
          };
          default_session = initial_session;
        };
      };

      environment.etc."niri/config.kdl".text = ''
        binds {
          Mod+T { spawn "alacritty"; }
          Mod+D { spawn "fuzzel"; }
          Mod+Q { close-window; }
          Mod+Shift+Q { exit; }
        }
      '';
      environment.systemPackages = with pkgs; [
        alacritty
        waybar
        fuzzel
        mako
        firefox
      ];

      programs.firefox.enable = true;

      services.pipewire = {
        enable = true;
        alsa.enable = true;
        pulse.enable = true;
        # Optionally:
        jack.enable = true;
      };

      hardware.alsa.enablePersistence = true;

      networking.networkmanager.enable = true;
    };
  };
}

I chose to use the nightly version so it was required to add the overlay at the top-level as well as inside the specialisation block.

On my system it sped up build times to first run:

sudo nixos-rebuild switch --flake .
# And Then Run
sudo nixos-rebuild boot --flake .

What this does:

Creates a boot entry called niri-test with the Niri Wayland compositor, a test user, and a greetd login manager.
Installs a set of packages and enables PipeWire with ALSA, PulseAudio, and JACK support.
Provides a custom Niri configuration file for a few keybinds and enables NetworkManager.

Using Your Specialisation After Boot

Once you have rebooted and selected your specialisation from the boot menu, you can use your system as usual. If you want to add or remove programs, change settings, or update your environment within a specialisation, simply:

Edit your configuration: Add or remove packages (e.g., add ghostty to environment.systemPackages) or change any other options inside the relevant specialisation block in your NixOS configuration.
Apply changes with a rebuild: Run the standard NixOS rebuild command. If you are currently running the specialisation you want to update, use:

sudo nixos-rebuild switch

This will apply your changes to the current specialisation

If you want to build and activate a different specialisation from your current session, use:

sudo nixos-rebuild switch --specialisation name

Or, you can activate a specialisation directly with:

sudo /run/current-system/specialisation/<name>/bin/switch-to-configuration switch

Replace <name> with your specialisation’s name.

Reboot if needed: Most changes apply immediately, but some (like kernel or initrd changes) require a reboot for the specialisation to fully take effect

Tip:

Each specialisation can have its own set of installed programs. Only those listed in the environment.systemPackages (or enabled via modules) inside the specialisation block will be available when you boot into that context.

You manage and update your specialisation just like your main NixOS system no special commands or workflow are required beyond specifying the specialisation when rebuilding or switching.

Use Cases for Specialisations

Hardware Profiles: Enable/disable drivers or services for specific hardware (e.g., eGPU, WiFi, or SR-IOV setups)
Desktop Environments: Quickly switch between different desktop environments or compositors (e.g., GNOME, Plasma, Niri)
Testing: Safely try out unstable packages, new kernels, or experimental features without risking your main environment
User Separation: Create profiles for different users, each with their own settings, packages, and auto-login
Secure Environments: Combine with encrypted partitions for more secure, isolated setups

Securely Separated Contexts with NixOS Specialisations

I will just explain the concept here for completeness, if you want to implement this I recommend following:

Tweag Hard User Separation with NixOS

✔️ Click To Expand Section on Separate Contexts

If you use the same computer in different contexts such as for work and for your private life you may worry about the risks of mixing sensitive environments. For example, a cryptolocker received through a compromised work email could potentially encrypt your personal files, including irreplaceable family photos.

A common solution is to install two different operating systems and dual-boot between them, keeping work and personal data isolated. However, this approach means you have two systems to maintain, update, and configure, which can be a significant hassle.

NixOS offers a third alternative: With NixOS specialisations, you can manage two (or more) securely separated contexts within a single operating system. At boot time, you select which context you want to use work or personal. Each context can have its own encrypted root partition, user accounts, and configuration, but both share the same Nix store for packages. This means:

No duplicated packages: Both contexts use the same system-wide package store, saving space and simplifying updates.
Single system to maintain: You update and manage only one NixOS installation, not two.
Strong security boundaries: Each context can have its own encrypted root, so a compromise in one context (such as malware in your work environment) cannot access the data in the other context.
Flexible management: You can configure both contexts from either environment, making administration easier.

This approach combines the security of dual-booting with the convenience and efficiency of a single, unified system.

How It Works:

Encrypted Partitions: Each context (work and personal) has its own encrypted root partition. The shared /nix/store partition is also encrypted, but can be unlocked by either context.
Specialisations at Boot: NixOS generates multiple boot entries, one for each context. You simply choose your desired environment at boot time.
Separation of Data: Your work and personal home directories, settings, and documents remain isolated from each other, while still benefiting from shared system packages.

Benefits Over Traditional Dual-Boot

Only one system to update and configure.
No wasted disk space on duplicate packages.
Seamless switching between contexts with a reboot.
Consistent NixOS tooling and workflows in both environments.

What You Need

A physical or virtual machine supported by NixOS.
Willingness to erase the system disk during setup.
LVM (Logical Volume Manager) support: This setup requires using LVM for disk partitioning and management. LVM allows you to create multiple logical volumes on a single physical disk, making it possible to securely separate your work and personal environments while sharing a common Nix store. You will use LVM commands such as pvcreate, vgcreate, and lvcreate to prepare your disk layout

In summary: With NixOS specialisations and careful disk partitioning, you can achieve secure, convenient, and efficient context separation—no need to compromise between security and manageability.

Tips and Best Practices

Overriding Values: Use lib.mkDefault or lib.mkForce to make options overridable or forced in specialisations. I had to do it above because I have greetd setup for my main configuration as well.
Selective Configuration: If you want certain options only in the default (non-specialised) system, use:

config = lib.mkIf (config.specialisation != {}) { ... }

This condition checks if you’re in a specialisation.
Any settings inside this block will not be inherited by specialisations, keeping them exclusive to the main system.
Runtime Limitations: Not all changes (e.g., kernel or initrd) can be fully applied at runtime; a reboot is required for those.
Modularity: Specialisations work well with modular NixOS configs keep hardware, user, and service configs in separate files for easier management

References to Official Documentation and Community Resources

Comparing Flakes and Traditional Nix

2025-11-22T00:00:00+00:00

Chapter 8

✔️ Click to Expand Table of Contents

Comparing Flakes and Traditional Nix

This post is based on notes from Nix-Hour #4, comparing Traditional Nix and Flakes, focusing on achieving pure build results. See the YouTube video for the original content. This guide adapts the information for clarity and ease of understanding.

What is Purity in Nix? (click here)

A key benefit of Nix Flakes is their default enforcement of pure evaluation.
In Nix, an impure operation depends on something outside its explicit inputs. Examples include:
- User’s system configuration
- Environment variables
- Current time
Impurity leads to unpredictable builds that may differ across systems or time.

Building a Simple “hello” Package: Flakes vs. Traditional Nix

We’ll demonstrate building a basic “hello” package using both Flakes and Traditional Nix to highlight the differences in handling purity.

Using Nix Flakes

Building Hello with Flakes (click here)

Setup:
```
mkdir hello && cd hello/
```
Create flake.nix (Initial Impure Example):
```
# flake.nix
{
  outputs = { self, nixpkgs }: {
    myHello = (import nixpkgs {}).hello;
  };
}
```
- Note: Flakes don’t have access to builtins.currentSystem directly.
Impure Build (Fails):
```
nix build .#myHello
```
- This fails because Flakes enforce purity by default.
Force Impure Build:
```
nix build .#myHello --impure
```

Making the Flake Pure:

# flake.nix
{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs";
    flake-utils.url = "github:numtide/flake-utils";
  };

  outputs = { self, nixpkgs, flake-utils }:
    flake-utils.lib.eachDefaultSystem (system:
      let
        pkgs = nixpkgs.legacyPackages.${system};
      in {
        packages.myHello = pkgs.hello;
      }
    );
}

flake-utils simplifies making flakes system-agnostic and provides the system attribute.

Pure Build (Success):
```
nix build .#myHello
```

Using Traditional Nix

Building hello with Traditional Nix

Setup:
```
mkdir hello2 && cd hello2/
```

Create default.nix (Initial Impure Example):

# default.nix
{ myHello = (import <nixpkgs> { }).hello; }

Build (Impure):
```
nix-build -A myHello
```
Impurity Explained:
```
nix repl
nix-repl> <nixpkgs>
/nix/var/nix/profiles/per-user/root/channels/nixos
```
- <nixpkgs> depends on the user’s environment (Nixpkgs channel), making it impure. Even with channels disabled, it relies on a specific Nixpkgs version in the store.

Achieving Purity: Using fetchTarball

GitHub allows downloading repository snapshots at specific commits, crucial for reproducibility.
Get Nixpkgs Revision from flake.lock (from the Flake example):

# flake.lock
"nixpkgs": {
  "locked": {
    "lastModified": 1746372124,
    "narHash": "sha256-n7W8Y6bL7mgHYW1vkXKi9zi/sV4UZqcBovICQu0rdNU=",
    "owner": "NixOS",
    "repo": "nixpkgs",
    "rev": "f5cbfa4dbbe026c155cf5a9204f3e9121d3a5fe0",
    "type": "github"
  },

Modify default.nix for Purity:

# default.nix
let
  nixpkgs = fetchTarball {
    url = "[https://github.com/NixOS/nixpkgs/archive/f5cbfa4dbbe026c155cf5a9204f3e9121d3a5fe0.tar.gz](https://github.com/NixOS/nixpkgs/archive/f5cbfa4dbbe026c155cf5a9204f3e9121d3a5fe0.tar.gz)";
    sha256 = "0000000000000000000000000000000000000000000000000000"; # Placeholder
  };
in {
  myHello = (import nixpkgs {}).hello;
}

Replace <nixpkgs> with fetchTarball and a specific revision. A placeholder sha256 is used initially.

Build (Nix provides the correct sha256):
```
nix-build -A myHello
```
Verification: Both Flake and Traditional Nix builds now produce the same output path.
Remaining Impurities in Traditional Nix:
- Default arguments to import <nixpkgs> {} can introduce impurity:
  - overlays: ~/.config/nixpkgs/overlays (user-specific)
  - config: ~/.config/nixpkgs/config.nix (user-specific)
  - system: builtins.currentSystem (machine-specific)

Making Traditional Nix Fully Pure:

# default.nix
{system ? builtins.currentSystem}:
let
  nixpkgs = fetchTarball {
    url =
      "[https://github.com/NixOS/nixpkgs/archive/0243fb86a6f43e506b24b4c0533bd0b0de211c19.tar.gz](https://github.com/NixOS/nixpkgs/archive/0243fb86a6f43e506b24b4c0533bd0b0de211c19.tar.gz)";
    sha256 = "1qvdbvdza7hsqhra0yg7xs252pr1q70nyrsdj6570qv66vq0fjnh";
  };
in {
  myHello = (import nixpkgs {
    overlays = [];
    config = {};
    inherit system;
  }).hello;
}

Override impure defaults for overlays, config, and make system an argument.

Building with a Specific System:

nix-build -A myHello --argstr system x86_64-linux

Pure Evaluation Mode in Traditional Nix:

nix-instantiate --eval --pure-eval --expr 'fetchGit { url = ./.; rev = "b4fe677e255c6f89c9a6fdd3ddd9319b0982b1ad"; }'

Example of using --pure-eval.

nix-build --pure-eval --expr '(import (fetchGit { url = ./.; rev = "b4fe677e255c6f89c9a6fdd3ddd9319b0982b1ad"; }) { system = "x86_64-linux"; }).myHello'

Building with a specific revision and system.

Updating Nixpkgs

Updating Nixpkgs with Flakes

nix flake update

nix build .#myHello --override-input nixpkgs github:NixOS/nixpkgs/nixos-24.11

Updating Traditional Nix (using `niv`)

Updating with niv

nix-shell -p niv
niv init

# default.nix
{ system ? builtins.currentSystem,
  sources ? import nix/sources.nix,
  nixpkgs ? sources.nixpkgs,
  pkgs ? import nixpkgs {
    overlays = [ ];
    config = { };
    inherit system;
  }, }: {
  myHello = pkgs.hello;
}

And build it with:

nix-build -A myHello

niv update nixpkgs --branch=nixos-unstable
nix-build -A myHello

Adding Home-Manager with Flakes (click here)

# flake.nix
{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs";
    flake-utils.url = "github:numtide/flake-utils";
    home-manager.url = "github:nix-community/home-manager";
  };

  outputs = { self, nixpkgs, flake-utils, home-manager, ... }:
    flake-utils.lib.eachDefaultSystem (system:
      let pkgs = nixpkgs.legacyPackages.${system};
      in {
        packages.myHello = pkgs.hello;
        packages.x86_64-linux.homeManagerDocs =
          home-manager.packages.x86_64-linux.docs-html;
      });
}

nix flake update
nix flake show github:nix-community/home-manager

home-manager.inputs.follows = "nixpkgs";

Adding Home-Manager with Traditional Nix

Adding Home-Manager with Traditional Nix (click here)

```nix niv add nix-community/home-manager ```

nix repl
nix-repl> s = import ./nix/sources.nix
nix-repl> s.home-manager

{ system ? builtins.currentSystem, sources ? import nix/sources.nix
  , nixpkgs ? sources.nixpkgs, pkgs ? import nixpkgs {
    overlays = [ ];
    config = { };
    inherit system;
  }, }: {
  homeManagerDocs = (import sources.home-manager { pkgs = pkgs; }).docs;

  myHello = pkgs.hello;
}

nix-build -A homeManagerDocs

Conclusion

In this chapter, we’ve explored the key differences between traditional Nix and Nix Flakes, particularly focusing on how each approach handles purity, dependency management, and project structure. We’ve seen that while traditional Nix can achieve purity with careful configuration, Flakes enforce it by default, offering a more robust and standardized way to build reproducible environments. Flakes also streamline dependency management and provide a more structured project layout compared to the often ad-hoc nature of traditional Nix projects.

However, regardless of whether you’re working with Flakes or traditional Nix, understanding how to debug and trace issues within your Nix code is crucial. When things go wrong, you’ll need tools and techniques to inspect the evaluation process, identify the source of errors, and understand how your modules and derivations are being constructed.

In our next chapter, Debugging and Tracing Modules, we will delve into the world of Nix debugging. We’ll explore various techniques and tools that can help you understand the evaluation process, inspect the values of expressions, and trace the execution of your Nix code, enabling you to effectively troubleshoot and resolve issues in both Flake-based and traditional Nix projects.

My Chapter

2025-11-22T00:00:00+00:00

Installation Guides

This section provides detailed guides for installing NixOS. You’ll choose between an unencrypted or encrypted base setup. After your core installation, you can explore adding optional features like sops for encrypted secrets, lanzaboote for Secure Boot, or impermanence for a stateless system.

1. Unencrypted Disko Btrfs Subvol Installation

Guide: Minimal Btrfs-Subvol Install with Disko and Flakes
Best for:
- Users who want a straightforward and quick setup.
- Unencrypted Impermanence
- You can still add Lanzaboote and sops secrets after the install for a more secure system. To get the full benefits of Lanzaboote it is recommended to use full disk encryption.

2. Encrypted Disko Btrfs Subvol Installation

Encrypted Install Guide: Encrypted Install
Encrypted Impermanence
Important Considerations:
- Secure Boot with Lanzaboote For the full benefit of Secure Boot (with Lanzaboote), it’s highly recommended to have a second stage of protection, such as an encrypted disk.
- Adding Sops You can easily add sops (for managing encrypted secrets) to your configuration after the initial encrypted installation and reboot. This can simplify the initial setup process. However, always remember the core goal of using encrypted secrets: never commit unencrypted or even hashed sensitive data directly into your Git repository. With modern equipment brute force attacks are a real threat.

3. Post-Installation Security & Features

Once your base NixOS system is installed, consider these powerful additions:

sops-nix: For managing encrypted secrets directly within your NixOS configuration, ensuring sensitive data is never stored in plain text.
lanzaboote: For enabling Secure Boot, verifying the integrity of your boot chain (requires UEFI and custom keys).
impermanence: For setting up a stateless NixOS system, where the root filesystem reverts to a clean state on every reboot.

Unencrypted Install

2025-11-22T00:00:00+00:00

Minimal BTRFS-Subvol Install with Disko and Flakes

✔️ Click to Expand Table of Contents

Unencrypted Setups

Figure 1: BTRFS Logo: Image of the BTRFS logo. Sourced from the BTRFS repo BTRFS logo

Why I Chose BTRFS I chose BTRFS because I was already familiar with it from using it with Arch Linux and I found it to be very easy to use. From what I’ve read, there are licensing issues between the Linux Kernel and ZFS which means that ZFS is not part of the Linux Kernel; it’s maintained by the OpenZFS project and available as a separate kernel module. This can cause issues and make you think more about your filesystem than I personally want to at this point.

✔️ Click for BTRFS Subvolume Overview

A Btrfs subvolume is essentially a distinct section within a Btrfs filesystem that maintains its own set of files and directories, along with a separate inode numbering system. Unlike block-level partitions (such as LVM logical volumes), Btrfs subvolumes operate at the file level and are based on file extents.

Extents in Btrfs are contiguous blocks of data on disk that store the actual contents of files. When files are created or modified, Btrfs manages these extents efficiently, allowing features like deduplication and snapshots. Multiple subvolumes can reference the same extents, meaning that identical data is not duplicated on disk, which saves space and improves performance.

A snapshot in Btrfs is a special kind of subvolume that starts with the same content as another subvolume at the time the snapshot is taken. Snapshots are typically writable by default, so you can make changes in the snapshot without affecting the original subvolume. This is possible because Btrfs tracks changes at the extent level, only creating new extents when files are modified (a technique called copy-on-write).

Subvolumes in Btrfs behave much like regular directories from a user’s perspective, but they support additional operations such as renaming, moving, and nesting (placing subvolumes within other subvolumes). There are no restrictions on nesting, though it can affect how snapshots are created and managed. Each subvolume is assigned a unique and unchangeable numeric ID (subvolid or rootid).

You can access a Btrfs subvolume in two main ways:

As a normal directory within the filesystem.
By mounting it directly as if it were a separate filesystem, using the subvol or subvolid mount options. When mounted this way, you only see the contents of that subvolume, similar to how a bind mount works.

When a new Btrfs filesystem is created, it starts with a “top-level” subvolume (with an internal ID of 5). This subvolume is always present and cannot be deleted or replaced, and it is the default mount point unless changed with btrfs subvolume set-default.

Subvolumes can also have storage quotas set using Btrfs’s quota groups , but otherwise, they all draw from the same underlying storage pool. Thanks to features like deduplication and snapshots, subvolumes can share data efficiently at the extent level.While ZFS is a solid choice and offers some benefits over BTRFS, I recommend looking into it before making your own decision.

If you have a ton of RAM you could most likely skip the minimal install and just set your system up as needed or just use tmpfs as root

Getting Started with Disko

Disko allows you to declaratively partition and format your disks, and then mount them to your system. I recommend checking out the README as it is a disk destroyer if used incorrectly.

We will mainly be following the disko quickstart guide

Figure 2: Disko Logo: Image of the logo for Disko, the NixOS declarative disk partitioning tool. Sourced from the Disko project disko logo

Get the Nixos Minimal ISO Get it on a usb stick, I use Ventoy with Ventoy2Disk.sh. The following is the link to the Ventoy TarBall download, untar it with tar -xzf ventoy-1.1.05-linux.tar.gz, and make it executable with chmod +x Ventoy2Disk.sh, and finally execute it with sudo ./Ventoy2Disk.sh Follow the prompts to finish the install.

You’ll have to run it on for the USB drive you’re trying to use, you can do that by unplugging the USB stick and running lsblk, then plug it in again and run:

lsblk -f
NAME          FSTYPE      FSVER LABEL   UUID                                 FSAVAIL FSUSE% MOUNTPOINTS
sda
└─sda1        vfat        FAT32 MYUSB   46E8-9304
sdb           vfat        FAT12         F054-697D                               1.4M     0% /run/media/jr/F054-697D
nvme0n1
├─nvme0n1p1   vfat        FAT32         BCD8-8C51                               1.8G    12% /boot

sdb is a USB plugin for a mouse. sda is the USB stick that I want to target here:

sudo ./Ventoy2Disk.sh -i /dev/sda
# Or to force overwrite an existing Ventoy entry
sudo ./Ventoy2Disk.sh -I /dev/sda

The minimal installer uses wpa_supplicant instead of NetworkManager, to enable networking run the following:

sudo systemctl start wpa_supplicant
wpa_cli

> add_network
0

> set_network 0 ssid "myhomenetwork"
OK

> set_network 0 psk "mypassword"
OK

> enable_network 0
OK

To exit type quit, then check your connection with ping google.com.

Another option is to do the following, so either the above method or the below method after starting wpa_supplicant:

# Alternative for quick setup (less interactive, but often faster)
sudo wpa_passphrase "myhomenetwork" "mypassword" >> /etc/wpa_supplicant/wpa_supplicant-wlan0.conf
sudo systemctl restart wpa_supplicant@wlan0.service

Get your Disk Name with lsblk

The output should be something like:

NAME        MAJ:MIN RM   SIZE RO TYPE MOUNTPOINTS
nvme0n1     259:0    0   1,8T  0 disk

Copy the disk configuration to your machine. You can choose one from the examples directory.

Option A: (Simpler for new users) I also created a starter repo containing much of what’s needed. If you choose this option follow the README.md included with the repo.

cd ~
git clone https://github.com/saylesss88/my-flake.git

Make sure to change line 7 in disk-config.nix to what you got from step 3 device = “/dev/nvme0n1”;

Option B: (More flexible, more manual steps) Skip cloning the repo above and for the btrfs-subvolume default layout, run the following:

cd /tmp
curl https://raw.githubusercontent.com/nix-community/disko/refs/heads/master/example/btrfs-subvolumes.nix -o /tmp/disk-config.nix

Make Necessary changes, I set mine up for impermanence with the following:

nano /tmp/disk-config.nix

{
  disko.devices = {
    disk = {
      main = {
        type = "disk";
        device = "/dev/nvme0n1";
        content = {
          type = "gpt";
          partitions = {
            ESP = {
              priority = 1;
              name = "ESP";
              start = "1M";
              end = "512M";
              type = "EF00";
              content = {
                type = "filesystem";
                format = "vfat";
                mountpoint = "/boot";
                mountOptions = ["umask=0077"];
              };
            };
            root = {
              size = "100%";
              content = {
                type = "btrfs";
                extraArgs = ["-f"]; # Override existing partition
                # Subvolumes must set a mountpoint in order to be mounted,
                # unless their parent is mounted
                subvolumes = {
                  # Subvolume name is different from mountpoint
                  "/root" = {
                    mountpoint = "/";
                    mountOptions = ["subvol=root" "compress=zstd" "noatime"];
                  };
                  # Subvolume name is the same as the mountpoint
                  "/home" = {
                    mountOptions = ["subvol=home" "compress=zstd" "noatime"];
                    mountpoint = "/home";
                  };
                  # Sub(sub)volume doesn't need a mountpoint as its parent is mounted
                  "/home/user" = {};
                  # Parent is not mounted so the mountpoint must be set
                  "/nix" = {
                    mountOptions = [
                      "subvol=nix"
                      "compress=zstd"
                      "noatime"
                    ];
                    mountpoint = "/nix";
                  };
                  "/nix/persist" = {
                    mountpoint = "/nix/persist";
                    mountOptions = ["subvol=persist" "compress=zstd" "noatime"];
                  };
                  "/log" = {
                    mountpoint = "/var/log";
                    mountOptions = ["subvol=log" "compress=zstd" "noatime"];
                  };
                  "/lib" = {
                    mountpoint = "/var/lib";
                    mountOptions = ["subvol=lib" "compress=zstd" "noatime"];
                  };
                  # This subvolume will be created but not mounted
                  "/test" = {};
                };
              };
            };
          };
        };
      };
    };
  };
  fileSystems."/nix/persist".neededForBoot = true;
  fileSystems."/var/log".neededForBoot = true;
  fileSystems."/var/lib".neededForBoot = true;
}

For /tmp on RAM use something like the following. I’ve found that having disko manage swaps causes unnecessary issues. Using zram follows the ephemeral route:

{
  lib,
  config,
  ...
}: let
  cfg = config.custom.zram;
in {
  options.custom.zram = {
    enable = lib.mkEnableOption "Enable utils module";
  };

  config = lib.mkIf cfg.enable {
    zramSwap = {
      enable = true;
      # one of "lzo", "lz4", "zstd"
      algorithm = "zstd";
       priority = 5;
       memoryPercent = 50;
    };
  };
}

And in your configuration.nix you would add:

# configuration.nix
custom = {
    zram.enable = true;
};

After adding the above module, you can see it with:

swapon --show
NAME       TYPE      SIZE USED PRIO
/dev/zram0 partition 7.5G   0B    5

Run disko to partition, format and mount your disks. Warning this will wipe EVERYTHING on your disk. Disko doesn’t work with dual boot.

sudo nix --experimental-features "nix-command flakes" run github:nix-community/disko/latest -- --mode destroy,format,mount /tmp/disk-config.nix

Check it with the following:

mount | grep /mnt

The output for an nvme0n1 disk would be similar to the following:

#... snip ...
/dev/nvme0n1p2 on /mnt type btrfs (rw,noatime,compress=zstd:3,ssd,discard=async,space_cache=v2,subvolid=285,subvol=/root)
/dev/nvme0n1p2 on /mnt/persist type btrfs (rw,noatime,compress=zstd:3,ssd,discard=async,space_cache=v2,subvolid=261,subvol=/persist)
/dev/nvme0n1p2 on /mnt/etc type btrfs (rw,noatime,compress=zstd:3,ssd,discard=async,space_cache=v2,subvolid=261,subvol=/persist)
/dev/nvme0n1p2 on /mnt/nix type btrfs (rw,noatime,compress=zstd:3,ssd,discard=async,space_cache=v2,subvolid=260,subvol=/nix)
/dev/nvme0n1p2 on /mnt/var/lib type btrfs (rw,noatime,compress=zstd:3,ssd,discard=async,space_cache=v2,subvolid=258,subvol=/lib)
/dev/nvme0n1p2 on /mnt/var/log type btrfs (rw,noatime,compress=zstd:3,ssd,discard=async,space_cache=v2,subvolid=259,subvol=/log)
/dev/nvme0n1p2 on /mnt/nix/store type btrfs (ro,noatime,compress=zstd:3,ssd,discard=async,space_cache=v2,subvolid=260,subvol=/nix)
# ... snip ...

Generate necessary files, here we use –no-filesystems because disko handles the fileSystems attribute for us.

nixos-generate-config --no-filesystems --root /mnt

It may be helpful to add a couple things to your configuration.nix now, rebuild and then move on. Such as, your hostname, git, an editor of your choice. After your additions run sudo nixos-rebuild switch to apply the changes. If you do this, you can skip the nix-shell -p command coming up.

sudo mv /tmp/disk-config.nix /mnt/etc/nixos

Setting a Flake for your minimal Install

Create the flake in your home directory, then move it to /mnt/etc/nixos. This avoids needing to use sudo for every command while in the /mnt/etc/nixos directory.

cd ~
mkdir flake && cd flake
nix-shell -p git yazi helix
export NIX_CONFIG='experimental-features = nix-command flakes'
export EDITOR='hx'
hx flake.nix

You’ll change hostname = nixpkgs.lib.nixosSystem to your chosen hostname, (e.g. magic = nixpkgs.lib.nixosSystem). This will be the same as your networking.hostName = “magic”; in your configuration.nix that we will set up shortly.

# flake.nix
{
  description = "NixOS configuration";

  inputs = {
    nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
    disko.url = "github:nix-community/disko/latest";
    disko.inputs.nixpkgs.follows = "nixpkgs";
    # impermanence.url = "github:nix-community/impermanence";
  };

  outputs = inputs@{ nixpkgs, ... }: {
    nixosConfigurations = {
      # Change `my-hostname` to match `networking.hostName`
      my-hostname = nixpkgs.lib.nixosSystem {
        system = "x86_64-linux";
        modules = [
          ./configuration.nix
          inputs.disko.nixosModules.disko
          # inputs.impermanence.nixosModules.impermanence
        ];
      };
    };
  };
}

Move all the files into your flake:

cd /mnt/etc/nixos/
sudo mv disk-config.nix hardware-configuration.nix configuration.nix ~/flake

Edit configuration.nix with what is required, the following is required, I clone my original flake repo and move the pieces into place but it’s fairly easy to just type it all out:

Bootloader, (e.g., boot.loader.systemd-boot.enable = true;)
User, the example uses username change this to your chosen username. If you don’t set your hostname it will be nixos.
Networking, networking.networkmanager.enable = true;
hardware-configuration.nix & disk-config.nix for this setup
initialHashedPassword: Run mkpasswd --method=yescrypt, then enter your desired password. Example output,

mkpasswd --method=yescrypt > /tmp/pass.txt

You can check the quality with pwscore:

nix-shell -p libpwquality

pwscore
very-secure-password
100

read the hashed password into the file with :r /tmp/pass.txt and move it into place.

# configuration.nix
{
  config,
  lib,
  pkgs,
  inputs,
  ...
}: {
  imports = [
    # Include the results of the hardware scan.
    ./hardware-configuration.nix
    ./disk-config.nix
  ];

  networking.hostName = "my-hostname"; # This will match the `hostname` of your flake

  networking.networkmanager.enable = true;

  boot.loader.systemd-boot.enable = true; # (for UEFI systems only)
  # List packages installed in system profile.
  # You can use https://search.nixos.org/ to find more packages (and options).
  environment.systemPackages = with pkgs; [
    vim # Do not forget to add an editor to edit configuration.nix! The Nano editor is also installed by default.
    #   wget
    git
  ];

  time.timeZone = "America/New_York";

# Change `nixos` to your chosen username, change the group to match
  users.users.nixos = {
    isNormalUser = true;
    extraGroups = [ "wheel" "networkmanager" ]; # Add "wheel" for sudo access
    initialHashedPassword = "COPY_YOUR_MKPASSWD_OUTPUT_HERE"; # <-- This is where it goes!
    # home = "/home/nixos"; # Optional: Disko typically handles home subvolumes
  };
  # Create a matching group
  users.groups.nixos = {};

  console.keyMap = "us";

  nixpkgs.config.allowUnfree = true;

  system.stateVersion = "25.05";
}

Shred pass.txt:

shred /tmp/pass.txt
rm /tmp/pass.txt

Move the flake to /mnt/etc/nixos and run nixos-install:

sudo mv ~/flake /mnt/etc/nixos/
sudo nixos-install --flake /mnt/etc/nixos/flake .#hostname
# if the above command doesn't work try this:
sudo nixos-install --flake /mnt/etc/nixos/flake#hostname

You will be prompted to enter a new password if everything succeeds.

If everything checks out, reboot the system and you should be prompted to enter your user and password to login to a shell to get started.

The flake will be placed at /etc/nixos/flake, I choose to move it to my home directory. Since the file was first in /etc you’ll need to adjust the permissions with something like sudo chown nixos:nixos ~/flake. This is based off of the example above where we created both a nixos user and group.

You can check the layout of your btrfs system with:

sudo btrfs subvolume list /

You may notice some old_roots in the output, which are snapshots, which are likely created before system upgrades or reboots for rollback purposes. They can be deleted or rolled back as needed.

BTRFS Subvolumes

To continue following along and set up impermanence Click Here

Encrypted Install (BTRFS)

2025-11-22T00:00:00+00:00

Encrypted Setups

✔️ Click to Expand Table of Contents

NixOS supports file systems that are encrypted using LUKS (Linux Unified Key Setup). This guide walks you through an encrypted NixOS installation using Disko for disk management and Btrfs for subvolumes. It is designed for users who want full disk encryption and a modern filesystem layout. If you prefer an unencrypted setup, you can skip the LUKS and encryption steps, but this guide focuses on security and flexibility.

For Unencrypted layout Click Here

If you choose to set up impermanence, ensure it matches your install. Encrypted Setup with Encrypted Impermanence and Unencrypted Setup with Unencrypted Impermanence.

❗ NOTE: This is a bit convoluted, there are a few paths you can follow. If you choose to use the starter repo (https://github.com/saylesss88/my-flake) just follow the included README and use this for reference.

What does LUKS Encryption Protect?

It’s important to understand what disk encryption protects and what it doesn’t protect so you don’t have any misconceptions about how safe your data is.

What LUKS Protects:

Data Confidentiality at Rest: LUKS encrypts entire block devices (such as disk partitions or whole drives), ensuring that all data stored on the encrypted device is unreadable without the correct decryption key or passphrase. This protects sensitive information from unauthorized access if the device is lost, stolen, or physically accessed by an attacker.
Physical Security: If someone gains physical possession of your device (for example, by stealing your laptop or removing a hard drive), LUKS ensures the data remains inaccessible and appears as random, meaningless bytes without the correct credentials.
Protection Against Offline Attacks: LUKS defends against attackers who attempt to bypass the operating system by booting from another device or removing the drive and mounting it elsewhere. Without the decryption key, the data remains protected.

What LUKS Does Not Protect:

Data in Use: Once the system is booted and the encrypted device is unlocked, the data becomes accessible to the operating system and any user or process with the necessary permissions. LUKS does not protect against attacks on a running system, such as malware, remote exploits, or unauthorized users with access to an unlocked session.
File-Level Access Control: LUKS encrypts entire partitions or disks, not individual files or directories. It does not provide granular file-level encryption or access control within the operating system.
Network Attacks: LUKS only protects data stored on disk. It does not encrypt data transmitted over networks or protect against network-based attacks.
Bootloader and EFI Partitions: The initial bootloader or EFI system partition cannot be encrypted with LUKS, so some parts of the boot process may remain exposed unless additional measures are taken. (i.e., Secure Boot, additional passwords, TPM2)

To Sum it Up: LUKS encryption protects the confidentiality of all data stored on an encrypted block device by making it unreadable without the correct passphrase or key. This ensures that, if your device is lost or stolen, your data remains secure and inaccessible to unauthorized users. However, LUKS does not protect data once the system is unlocked and running, nor does it provide file-level encryption or protect against malware and network attacks. For comprehensive security, LUKS should be combined with strong access controls and other security best practices.

The Install

Get the Nixos Minimal ISO Get it on a usb stick, I use Ventoy with Ventoy2Disk.sh. The following is the link to the Ventoy TarBall download, untar it with tar -xzf ventoy-1.1.05-linux.tar.gz, and make it executable with chmod +x Ventoy2Disk.sh, and finally execute it with sudo bash Ventoy2Disk.sh Follow the prompts to finish the install.
Configuring Networking

The minimal installer uses wpa_supplicant instead of NetworkManager. Choose one of the following methods to enable networking:

sudo systemctl start wpa_supplicant
wpa_cli

Option A: Interactive `wpa_cli`

> add_network
0

> set_network 0 ssid "myhomenetwork"
OK

> set_network 0 psk "mypassword"
OK

> enable_network 0
OK

To exit type quit, then check your connection with ping google.com.

Option B: Non-Interactive `wpa_passphrase`

This method is quicker for known networks and persists the configuration for the live environment.

First, identify your wireless interface name (e.g., wlan0) using ip a.

sudo systemctl start wpa_supplicant # Ensure wpa_supplicant is running
# This command generates the config and appends it to a file specific to wlan0
sudo wpa_passphrase "myhomenetwork" "mypassword" | sudo tee /etc/wpa_supplicant/wpa_supplicant-wlan0.conf
sudo systemctl restart wpa_supplicant@wlan0.service

After either method, exit wpa_cli with quit. Then test your connection:

ping 1.1.1.1

Get your Disk Name with lsblk

The output should be something like:

NAME        MAJ:MIN RM   SIZE RO TYPE MOUNTPOINTS
nvme0n1     259:0    0   1,8T  0 disk

❗ From here, you can either

Copy the disk configuration to your machine. You can choose one from the examples directory.

There is still a starter repo that can save you some typing, make sure to carefully review if you decide to use it:

export NIX_CONFIG='experimental-features = nix-command flakes'
export EDITOR='hx' # or 'vi'
nix-shell -p git yazi helix mkpasswd
git config --global user.name "gitUsername"
git config --global user.email "gitEmail"
# OPTIONAL starter repo containing disk-config set up for impermanence
git clone https://github.com/saylesss88/my-flake.git

I prefer helix here as it’s defaults are great. (i.e., auto closing brackets and much more)

If you choose to use the starter repo you won’t need to run the next command as it is already populated in the repo and should use the Starter Repo README most of the rest of the guide is for manual disko without the starter repo.

If you click on the layout you want then click the Raw button near the top, then copy the url and use it in the following command:

cd /tmp
curl https://raw.githubusercontent.com/nix-community/disko/refs/heads/master/example/luks-btrfs-subvolumes.nix -o /tmp/disk-config.nix

The above curl command is to the luks-btrfs-subvolumes.nix layout.

Make Necessary changes, I prepared mine for impermanence with the following:

hx /tmp/disk-config.nix

Make sure you identify your system disk name with lsblk and change the device attribute below to match your disk.

lsblk
nvme0n1       259:0    0 476.9G  0 disk
├─nvme0n1p1   259:1    0   512M  0 part  /boot
└─nvme0n1p2   259:2    0 476.4G  0 part

My disk is nvme0n1, change below to match yours:

{
  disko.devices = {
    disk = {
      nvme0n1 = {
        type = "disk";
        # Make sure this is correct with `lsblk`
        device = "/dev/nvme0n1";
        content = {
          type = "gpt";
          partitions = {
            ESP = {
              label = "boot";
              name = "ESP";
              size = "1G";
              type = "EF00";
              content = {
                type = "filesystem";
                format = "vfat";
                mountpoint = "/boot";
                mountOptions = [
                  "defaults"
                ];
              };
            };
            luks = {
              size = "100%";
              label = "luks";
              content = {
                type = "luks";
                name = "cryptroot";
                content = {
                  type = "btrfs";
                  extraArgs = ["-L" "nixos" "-f"];
                  subvolumes = {
                    "/root" = {
                      mountpoint = "/";
                      mountOptions = ["subvol=root" "compress=zstd" "noatime"];
                    };
                    "/root-blank" = {
                      mountOptions = ["subvol=root-blank" "nodatacow" "noatime"];
                    };
                    "/home" = {
                      mountpoint = "/home";
                      mountOptions = ["subvol=home" "compress=zstd" "noatime"];
                    };
                    "/nix" = {
                      mountpoint = "/nix";
                      mountOptions = ["subvol=nix" "compress=zstd" "noatime"];
                    };
                    "/persist" = {
                      mountpoint = "/persist";
                      mountOptions = ["subvol=persist" "compress=zstd" "noatime"];
                    };
                    "/log" = {
                      mountpoint = "/var/log";
                      mountOptions = ["subvol=log" "compress=zstd" "noatime"];
                    };
                    "/lib" = {
                      mountpoint = "/var/lib";
                      mountOptions = ["subvol=lib" "compress=zstd" "noatime"];
                    };
                    "/persist/swap" = {
                      mountpoint = "/persist/swap";
                      mountOptions = ["subvol=swap" "noatime" "nodatacow" "compress=no"];
                      swap.swapfile.size = "18G";
                    };
                  };
                };
              };
            };
          };
        };
      };
    };
  };

  fileSystems."/persist".neededForBoot = true;
  fileSystems."/var/log".neededForBoot = true;
  fileSystems."/var/lib".neededForBoot = true;
}

I have 16G of RAM so to be safe for hibernation I chose to give it some extra space. The boot partition is 1G, this extra space is for specialisations and lanzaboote.

or for a swapfile:

swapDevices = [
  {
    device = "/persist/swap/swapfile";
    size = 18 * 1024; # Size in MB (18GB)
    # or
    # size = 16384; # Size in MB (16G);
  }
];

Setting up zram and /tmp on RAM

While /tmp is handled by tmpfs (as shown the below configuration.nix), you can further enhance memory efficiency with zram for compressed swap, as shown below.

{
  lib,
  config,
  ...
}: let
  cfg = config.custom.zram;
in {
  options.custom.zram = {
    enable = lib.mkEnableOption "Enable utils module";
  };

  config = lib.mkIf cfg.enable {
    zramSwap = {
      enable = true;
      # one of "lzo", "lz4", "zstd"
      algorithm = "zstd";
       priority = 5;
       memoryPercent = 50;
    };
  };
}

And in your configuration.nix you would add:

# configuration.nix
custom = {
    zram.enable = true;
};

After adding the above module and rebuilding, you can see it with:

swapon --show
NAME       TYPE      SIZE USED PRIO
/dev/zram0 partition 7.5G   0B    5

Run disko to partition, format and mount your disks. Warning this will wipe EVERYTHING on your disk. Disko doesn’t work with dual boot.

sudo nix --experimental-features "nix-command flakes" run github:nix-community/disko/latest -- --mode destroy,format,mount /tmp/disk-config.nix

Check it with the following:

mount | grep /mnt

The output for an nvme0n1 disk would be similar to the following:

#... snip ...
/dev/nvme0n1p2 on /mnt type btrfs (rw,noatime,compress=zstd:3,ssd,discard=async,space_cache=v2,subvolid=285,subvol=/root)
/dev/nvme0n1p2 on /mnt/persist type btrfs (rw,noatime,compress=zstd:3,ssd,discard=async,space_cache=v2,subvolid=261,subvol=/persist)
/dev/nvme0n1p2 on /mnt/etc type btrfs (rw,noatime,compress=zstd:3,ssd,discard=async,space_cache=v2,subvolid=261,subvol=/persist)
/dev/nvme0n1p2 on /mnt/nix type btrfs (rw,noatime,compress=zstd:3,ssd,discard=async,space_cache=v2,subvolid=260,subvol=/nix)
/dev/nvme0n1p2 on /mnt/var/lib type btrfs (rw,noatime,compress=zstd:3,ssd,discard=async,space_cache=v2,subvolid=258,subvol=/lib)
/dev/nvme0n1p2 on /mnt/var/log type btrfs (rw,noatime,compress=zstd:3,ssd,discard=async,space_cache=v2,subvolid=259,subvol=/log)
/dev/nvme0n1p2 on /mnt/nix/store type btrfs (ro,noatime,compress=zstd:3,ssd,discard=async,space_cache=v2,subvolid=260,subvol=/nix)
# ... snip ...

Generate necessary files, here we use --no-filesystems because disko handles the fileSystems attribute for us.

nixos-generate-config --no-filesystems --root /mnt

The above command will place a configuration.nix and hardware-configuration.nix in /mnt/etc/nixos/

It may be helpful to add a couple things to your configuration.nix now, while it’s in its default location. You can just add what you want and rebuild once with sudo nixos-rebuild switch and move on. (i.e. git, an editor, etc.).

Setting a Flake for your minimal Install

Create the flake in your home directory to avoid needing to use sudo for every command:

cd   # Move to home directory
mkdir flake
cd /mnt/etc/nixos/
sudo mv hardware-configuration.nix configuration.nix ~/flake/
sudo mv /tmp/disk-config.nix ~/flake/

cd flake
hx flake.nix

You’ll change hostName = nixpkgs.lib.nixosSystem to your chosen hostname, (e.g. magic = nixpkgs.lib.nixosSystem). This will be the same as your networking.hostName = "magic"; in your configuration.nix that we will set up shortly.

# flake.nix
{
  description = "NixOS configuration";

  inputs = {
    nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
    disko.url = "github:nix-community/disko/latest";
    disko.inputs.nixpkgs.follows = "nixpkgs";
    # impermanence.url = "github:nix-community/impermanence";
  };

  outputs = inputs@{ nixpkgs, ... }: {
    nixosConfigurations = {
      # Change `hostName` to your chosen host name
      nixos = nixpkgs.lib.nixosSystem {
        system = "x86_64-linux";
        modules = [
          ./configuration.nix
          inputs.disko.nixosModules.disko
          # inputs.impermanence.nixosModules.impermanence
        ];
      };
    };
  };
}

Edit configuration.nix with what is required, the following are required, I clone my original flake repo and move the pieces into place but it’s fairly easy to just type it all out:

Bootloader, (e.g., boot.loader.systemd-boot.enable = true;)
User, the example uses username change this to your chosen username. If you don’t set your hostname it will be nixos.
Networking, networking.networkmanager.enable = true;
hardware-configuration.nix & disk-config.nix for this setup
If you type this out by hand and mess up a single character, you will have to start over completely. A fairly safe way to do this is with vim or hx and redirect the hashed pass to a /tmp/pass.txt, you can then read it into your users.nix:

mkpasswd --method=yescrypt > /tmp/pass.txt
# Enter your chosen password

And then when inside configuration.nix, move to the line where you want the hashed password and type :r /tmp/pass.txt to read the hash into your current file.

# configuration.nix
{
  config,
  lib,
  pkgs,
  inputs,
  ...
}: {
  imports = [
    # Include the results of the hardware scan.
    ./hardware-configuration.nix
    ./disk-config.nix
  ];

  # systemd Stage 1: if enabled, it handles unlocking of LUKS-encrypted volumes during boot.
    boot.initrd.luks.devices = {
    cryptroot = {
      device = "/dev/disk/by-partlabel/luks";
      allowDiscards = true;
    };
  };

  # This complements using zram, putting /tmp on RAM
    boot = {
    tmp = {
      useTmpfs = true;
      tmpfsSize = "50%";
    };
  };

  # Enable autoScrub for btrfs
    services.btrfs.autoScrub = {
    enable = true;
    interval = "weekly";
    fileSystems = ["/"];
  };


  # Change me!
  networking.hostName = "nixos"; # This will match the `hostname` of your flake

  networking.networkmanager.enable = true;

  boot.loader.systemd-boot.enable = true; # (for UEFI systems only)
  # List packages installed in system profile.
  # You can use https://search.nixos.org/ to find more packages (and options).
  environment.systemPackages = with pkgs; [
    vim # Do not forget to add an editor to edit configuration.nix! The Nano editor is also installed by default.
    #   wget
    git
  ];

  time.timeZone = "America/New_York";

# Change me to your chosen username (i.e. change nixosUser to your username)
  users.users.nixosUser = {
    isNormalUser = true;
    extraGroups = [ "wheel" "networkmanager" ]; # Add "wheel" for sudo access
    initialHashedPassword = "READ_MKPASSWD_OUTPUT_HERE"; # <-- This is where it goes!
    # home = "/home/nixos"; # Optional: Disko typically handles home subvolumes
  };
  # Change me to match your chosen username
  users.group.nixosUser = {};

  console.keyMap = "us";

  nixpkgs.config.allowUnfree = true;

  system.stateVersion = "25.05";
}

Although, just adding the disk-config.nix works for prompting you for your encryption passphrase adding the following is a more robust way of ensuring Nix is aware of this:

    boot.initrd.luks.devices = {
    cryptroot = {
      device = "/dev/disk/by-partlabel/luks";
      allowDiscards = true;
    };
  };

Move the flake to /mnt/etc/nixos and run nixos-install:

sudo mv ~/flake /mnt/etc/nixos/

Give everything a quick once over, insuring your host is set in both your flake.nix, and configuration.nix. Ensure you changed the username in the configuration.nix from nixos to your chosen name, this is the name you’ll use to login after you enter your encryption passphrase.

The below command uses #nixos because that’s what the defaults are, you’ll change it to your chosen hostname.

sudo nixos-install --flake /mnt/etc/nixos/flake#nixos

You will be prompted to enter a new password if everything succeeds.

Create a Blank Snapshot of /root

This is essential if you plan on using impermanence with this encrypted setup. We take a snapshot of /root while it’s a clean slate, right after we run disko to format the disk.

To access all of the subvolumes, we have to mount the Btrfs partitions top-level.

Unlock the LUKS device, if not already unlocked as it should be from running disko:

sudo cryptsetup open /dev/disk/by-partlabel/luks cryptroot

Mount the Btrfs top-level (subvolid=5):

sudo mount -o subvolid=5 /dev/mapper/cryptroot /mnt

List the contents:

ls /mnt
# you should see something like
root   home  nix  persist  log  lib  ...

Now we can take a snapshot of the root subvolume:

sudo btrfs subvolume snapshot -r /mnt/root /mnt/root-blank

Verify Your Blank Snapshot:

Before continuing, make sure your blank snapshot exists. This is crucial for impermanence to work properly.

sudo btrfs subvolume list /mnt

You should see output containing both root and root-blank subvolumes:

ID 256 gen ... path root
ID 257 gen ... path root-blank

Check that the snapshot is read only, this ensures that our snapshot will remain the same as the day we took it. It was set ro in disko but lets check anyways:

sudo btrfs property get -ts /mnt/root-blank
# output should be
ro=true

Make sure to unmount:

sudo umount /mnt

If everything checks out, reboot the system and you should be prompted to enter your user and password to login to a shell to get started.
The flake will be placed at /etc/nixos/flake after the install and reboot, I choose to move it to my home directory. Since the file was first in /etc you’ll need to adjust the permissions with something like sudo chown -R $USER:$USER ~/flake and then you can work on it without privilege escalation. This requires that you create a group for your user as done in the configuration.nix above.
You can check the layout of your btrfs system with:

sudo btrfs subvolume list /

Persisting Critical System State

The following is a one time operation, we’re just getting it out of the way now. This moves all of the important system state to a persistant location, further preparing for impermanence.

It’s essential that you have first run the nixos-install command to populate these directories before copying them over.

sudo mkdir -p /mnt/persist/etc
sudo mkdir -p /mnt/persist/var/lib
sudo mkdir -p /mnt/persist/var/log
sudo mkdir -p /mnt/persist/home
sudo mkdir -p /mnt/persist/root
sudo cp -a /mnt/etc/. /mnt/persist/etc/
sudo cp -a /mnt/var/lib/. /mnt/persist/var/lib
sudo cp -a /mnt/var/log/. /mnt/persist/var/log
sudo cp -a /mnt/home/. /mnt/persist/home/
sudo cp -a /mnt/root/. /mnt/persist/root/

Since we are in a live environment, after the install and reboot the /mnt prefix will be removed.

Reboot

Now that everything is done, we can safely reboot and ensure that our LUKS password/passphrase is accepted as well as our userlevel password and username.

After reboot, you can continue to setup Sops Encrypted Secrets and Lanzaboote Secure Boot

To set up impermanence for this specific layout, follow the link Encrypted Impermanence
BTRFS Subvolumes
systemd-cryptenroll man page
Linux TPM PCR Registry
Bypassing FDE with TPM2

USB Keyfile

2025-11-22T00:00:00+00:00

USB Stick Keyfile

✔️ Click to Expand Table of Contents

This allows you to use a USB stick for your keyfile, with a backup in case you want or need it. There is a setting fallbackToPassword that protects you in case something fails with the USB key.

First, I’ll show how to set up a dedicated USB stick for a keyfile. (i.e., one that is only used for this). After that I will show the process of adding the keyfile to a USB stick with existing data on it that you don’t want to lose.

Generate the keyfile

sudo dd if=/dev/urandom of=/root/usb-luks.key bs=4096 count=1

Keyfile Enrollment Methods

This is for a dedicated USB stick that we will wipe first then add the key.

Disko defaults to LUKS2

# cryptsetup works for both LUKS1 and LUKS2 formats but doesn't work for
# TPM2, FIDO2, and smartcards
sudo cryptsetup luksAddKey /dev/disk/by-partlabel/luks /root/usb-luks.key

✔️ Click to expand Experimental TPM2 auto-unlock for LUKS

⚠️ WARNING: Security Implications of TPM2 Auto-Unlock

Enabling TPM2 auto-unlock fundamentally changes your system’s security model. While this feature protects against certain forms of malicious software injection by tying the decryption key to the system’s boot state, it eliminates the need for a user password at boot. This creates a significant risk if your machine is stolen or seized, do not use this feature if the physical security of your machine is a concern. This is still at a stage where you can expect rough edges and workarounds.

⚠️ WARNING: Do NOT use TPM auto-unlock if your CPU is vulnerable to faulTPM! All AMD Zen2 and Zen3 Processors are known to be affected with AMD Zen1 likely also affected and Zen4 unknown! Misconfigurations are also common, do your own research!

You can add an additional layer by encrypting user data, such as individual home folders, with a different mechanism, such as fscrypt-experimental or systemd-homed. Or, you can use a TPM pin to benefit from the security properties of the TPM, while avoiding completely unattended unlocking. –Arch Wiki

I am reading that fscrypt is no longer experimental.

security.pam.enableFscrypt = true;

sudo fscrypt setup --all-users
sudo mv /home/<user> /home/old<user>
sudo mkdir /home/<user>
sudo chown <user>:users /home/<user>
sudo fscrypt encrypt --source pam_passphrase --user <user> --skip-unlock /home/<user>/

–☝️Discourse

It is fairly complex as to how TPM2 auto-unlock can improve security in some ways, it has to do with how Linux distributions fail to authenticate the boot process past the initrd.Even with encryption and Secure Boot enabled, the initrd stage often remains unverified, meaning a tampered initrd could be substituted without detection.

Brave New Trusted Boot World

TPMs protect secrets by releasing them only if the boot process can be authenticated through “measurements.” During boot, each component involved (firmware, bootloader, kernel, etc.) is hashed, and these hashes are extended into special TPM registers called Platform Configuration Registers (PCRs). These PCRs hold a cumulative, tamper-evident record of the boot process state.

If any part of the boot sequence changes (even slightly), the PCR values will differ from the expected, causing the TPM to refuse to release the bound secret (such as a disk decryption key). This ensures that the system only boots or unlocks secrets when its software stack is known and trusted, providing strong protection against tampering or unauthorized modifications. The values aren’t only protected by these PCRs but encrypted with a “seed key” that’s generated on the TPM chip itself, and cannot leave the TPM.

Check TPM support:

cat /sys/class/tpm/tpm0/device/description
TPM 2.0 Device

Check for necessary software dependencies:

systemd-analyze has-tpm2

Find your encrypted partition with lsblk:

lsblk

First, you need to use the systemd-cryptenroll command to add a TPM2 key to your encrypted LUKS partition. This process binds a key slot on your disk to the state of your TPM2 chip’s PCRs (Platform Configuration Registers).

# This command adds a new key to the LUKS volume, using a key generated by the TPM2 chip.
# It binds the key to PCRs 0,2,7,and 15 ensuring the key is only released if the firmware
# and Secure Boot state of your system is unchanged.
sudo systemd-cryptenroll --tpm2-device=auto --tpm2-pcrs=0+2+7+15 /dev/disk/by-partlabel/luks

There are quite a few options for the above command, some use the following with less pcrs and a wipe feature:

sudo systemd-cryptenroll --wipe-slot=tpm2 --tpm2-device=auto --tpm2-pcrs=0+7 /dev/disk/by-partlabel/luks

Using less pcrs could prevent breakage but reduces security. Check out the PCR Definitions below and decide if you require additional PCRs or less.
wipe-slot tells the system to delete any key associated with the TPM2 chip from the LUKS volume’s keyslot before adding a new one.

You can choose a more complex --tpm2-pcrs for more security but it makes the configuration more fragile because any legitimate system update altering any measured component tied to these PCRs will prevent the TPM from releasing the key and lock you out, unless you re-enroll the key with the updated PCR values.

PCR Definitions
Authenticated Boot and FDE This article explains the limitations and remedies very well.

That said, I do often see people mention a firmware update breaking their TPM2 auto-unlock functionality. Keep this in mind and have a backup plan. This is also incompatible with the encrypted impermanence setup shared in this book, the boot.initrd.postDeviceCommands conflict.

Change YourUser to your username and ensure that cryptroot is the name of yours, if you followed this books encrypted disko install it should be:

  # Adds your user to the 'tss' group, allowing you to interact with the TPM
  users.users.YourUser.extraGroups = [ "tss" ];
  # Enables TPM2 services and tools on your system
  security.tpm2.enable = true;
  # Ensure the necessary kernel modules are in the initrd
  boot.initrd.kernelModules = ["tpm_tis"];
  # switches the initrd to a systemd-based environment, required for TPM2
  boot.initrd.systemd.enable = true;
  # ❗ Tell the initrd to use the TPM2 key for the encrypted root
  boot.initrd.luks.devices.cryptroot = {
    device = "/dev/disk/by-partlabel/luks";
    # These options tell systemd-cryptsetup to automatically try to unlock the device
    # using the TPM2 key. 'tpm2-measure=yes' ensures the PCRs are verified but only works if you use one disk
    crypttabExtraOpts = ["tpm2-device=auto" "tpm2-measure=yes"];
    fallbackToPassword = true;
  };
  environment.systemPackages = [ pkgs.tpm2-tss ];

❗ NOTE: cryptroot needs to match what your encrypted partition is named, I have seen quite a few different names here.

If you use this, you can’t also use the USB Keyfile or the included impermanence guide.

Description

/dev/disk/by-partlabel/luks refers to your encrypted partition by its partition label, which is stable and less likely to change than /dev/nvme0n1p2
/root/usb-luks.key is the keyfile we generated.
You’ll be prompted to enter your existing LUKS passphrase to authorize adding the new key.
Now our LUKS volume will accept both our existing passphrase and the new keyfile (from the USB stick) for unlocking.

Clear Data on USB stick and replace with 0’s

lsblk
NAME        MAJ:MIN RM   SIZE RO TYPE MOUNTPOINTS
sda           8:0    1   239M  0 disk
sdb           8:16   1   1.4M  0 disk  /run/media/jr/7CD1-149A # Example USB mount
zram0       253:0    0   7.5G  0 disk  [SWAP]
nvme0n1     259:0    0 476.9G  0 disk
├─nvme0n1p1 259:1    0   512M  0 part  /boot
└─nvme0n1p2 259:2    0 476.4G  0 part
  └─cryptroot 254:0  0 476.4G  0 crypt /persist  # Main Btrfs mount
                                               # (other subvolumes are within /persist and bind-mounted by impermanence)
# unplug the device and run lsblk again so your sure

Before wiping you must unmount any mounted partitions:

sudo umount /dev/sda1

# Overwrite with Zeros (fast, sufficient for most uses)
sudo dd if=/dev/zero of=/dev/sda bs=4M status=progress
# Or overwrite with Random Data (More Secure, Slower)
sudo dd if=/dev/urandom of=/dev/sda bs=4M status=progress
# Or for the most secure way run multiple passes of
sudo shred -v -n 3 /dev/sda

Create a New Partition and Format (Optional)

sudo fdisk /dev/sda

Press o to create a new empty DOS partition table (if you are creating partitions on a fresh disk or want to wipe existing partitions and start over). Be very careful with this step as it will erase all existing partition information on the disk.
Press n to create a new partition.

You will then be prompted for the partition type:
- p for a primary partition (you can have up to 4 primary partitions)
- e for an extended partition (which can contain logical partitions)
Next, you’ll be asked for the partition number (e.g., 1, 2, 3, 4).
Then, you’ll be asked for the first sector (press Enter to accept the default, which is usually the first available sector after the previous partition or the beginning of the disk).
Finally, you’ll be asked for the last sector or size (you can specify a size like +10G for 10 Gigabytes, +512M for 512 Megabytes, or press Enter to use the rest of the available space).

Press w to write the changes to the partition table and exit fdisk.

After pressing w, the kernel needs to be aware of the new partition table. Sometimes this happens automatically, but if you encounter issues, a reboot or a command like partprobe (if available and needed) can help.

Formats as FAT32:

sudo mkfs.vfat /dev/sda1
# or as ext4
sudo mkfs.ext4 /dev/sda1

I chose vfat so I ran sudo mkfs.vfat /dev/sda1. In my case this changed the device path to /run/media/jr/7CD1-149A so it’s important to find your own UUID with the following command:

sudo blkid /dev/sda1
/dev/sda1: SEC_TYPE="msdos" UUID="B7B4-863B" BLOCK_SIZE="512" TYPE="vfat" PARTUUID="7d1f9d7f-01"

As you can see the above UUID is "B7B4-863B"
Remove and re-insert the USB stick, this ensures the system recognizes the new partition and filesystem.

Copy the keyfile to your USB Stick

sudo cp /root/usb-luks.key /run/media/jr/B7B4-863B/
sync

Update your NixOS Configuration

Note the output of blkid /dev/sda1 and if you have a backup device list that also:

The following is from the wiki edited for my setup, it was created by Tzanko Matev:

let
  PRIMARYUSBID = "B7B4-863B";
  BACKUPUSBID = "Ventoy";
in {

  boot.initrd.kernelModules = [
    "uas"
    "usbcore"
    "usb_storage"
    "vfat"
    "nls_cp437"
    "nls_iso8859_1"
  ];

  boot.initrd.postDeviceCommands = lib.mkBefore ''
    mkdir -p /key
    sleep 2
    mount -n -t vfat -o ro $(findfs UUID=${PRIMARYUSBID}) /key || \
    mount -n -t vfat -o ro $(findfs UUID=${BACKUPUSBID}) /key || echo "No USB key found"
  '';

  boot.initrd.luks.devices.cryptroot = {
    device = "/dev/disk/by-partlabel/luks";
    keyFile = "/key/usb-luks.key";
    fallbackToPassword = true;
    allowDiscards = true;
    preLVM = false; # Crucial!
  };
}

If you have issues or just want to remove the key take note of the path used to add it so you don’t have to enter the whole key:

sudo cryptsetup luksRemoveKey /dev/disk/by-partlabel/luks --key-file /root/usb-luks.key

Securely Remove the Keyfile from Your System:

sudo shred --remove --zero /root/usb-luks.key

Instructions for Using a USB Stick with Existing Data

Generate the Keyfile

sudo dd if=/dev/urandom of=/root/usb-luks.key bs=4096 count=1

Add the Keyfile to your LUKS Volume

sudo cryptsetup luksAddKey /dev/disk/by-partlabel/luks /root/usb-luks.key

(enter your existing passphrase when prompted)

Copy the Keyfile to the USB Stick

Plug in the USB Stick and note its mount point (e.g.,/run/media/$USER/YourLabel)
Copy the keyfile:

sudo cp /root/usb-luks.key /run/media/$USER/YourLabel/
sync

You run the above as 2 commands, the second being sync.
You can rename it if you wish (e.g., luks.key)

Securely Delete the Local Keyfile

sudo shred --remove --zero /root/usb-luks.key

You need to ensure the keyfile is accessible in the initrd. Since automounting (like /run/media/...) does not happen in initrd, you must manually mount the USB in the initrd using its UUID or label.

Find the USB Partition UUID:

lsblk -o NAME,UUID
# or
blkid /dev/sda1

Suppose the UUID is B7B4-863B

Add to your configuration.nix:

boot.initrd.kernelModules = [ "usb_storage" "vfat" "nls_cp437" "nls_iso8859_1" ];

boot.initrd.postDeviceCommands = lib.mkBefore ''
  mkdir -p /key
  sleep 1
  mount -n -t vfat -o ro $(findfs UUID=B7B4-863B) /key || echo "USB not found"
'';

boot.initrd.luks.devices.cryptroot = {
  device = "/dev/disk/by-partlabel/luks";
  keyFile = "/key/usb-luks.key"; # or whatever you named it
  fallbackToPassword = true;
  allowDiscards = true;
};

Encrypted BTRFS Impermanence

2025-11-22T00:00:00+00:00

Encrypted Impermanence

✔️ Click to Expand Table of Contents

❗ Important Note: This guide details a setup involving encrypted partitions and impermanent NixOS. While powerful, such configurations require careful attention to detail. Incorrect steps, especially concerning encryption keys or persistent data paths, can lead to permanent data loss. Please read all instructions thoroughly before proceeding and consider backing up any critical data beforehand. This has only been tested with the disk layout described in Encrypted Setups

As a system operates, it gradually accumulates state on its root partition. This state is stored in various directories such as /etc and /var, capturing all the configuration changes, logs, and other modifications—whether they’re well-documented or the result of ad-hoc adjustments made while setting up and running services.

Impermanence,in the context of operating systems, refers to a setup where the majority of the system’s root filesystem (/) is reset to a pristine state on every reboot. This means any changes made to the system (e.g., installing new packages, modifying system files outside of configuration management, creating temporary files) are discarded upon shutdown or reboot.

Having an impermanent root and /tmp has some security benefits as well. By reducing your persistent footprint you reduce your chance of leaving behind sensitive activity or data. Since Nix can boot with only /nix and /boot, experienced users familiar with “stateless” systems can take advantage of this smaller attack surface.

Although this setup does not use /tmp as the root filesystem, the root itself is restored to its original state upon each reboot, as it was at installation. However, by configuring /tmp to reside in RAM, you ensure that temporary files including sensitive data like passwords are stored only in volatile memory and are automatically cleared on shutdown or reboot. This significantly enhances the security of temporary data by preventing it from ever being written to disk.

Getting Started

Add impermanence to your flake.nix. You will change the hostname in the flake to match your networking.hostName.

# flake.nix
{
  description = "NixOS configuration";

  inputs = {
    nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
    disko.url = "github:nix-community/disko/latest";
    disko.inputs.nixpkgs.follows = "nixpkgs";
    impermanence.url = "github:nix-community/impermanence";
  };

  outputs = inputs@{ nixpkgs, ... }: {
    nixosConfigurations = {
      hostname = nixpkgs.lib.nixosSystem {
        system = "x86_64-linux";
        modules = [
          ./configuration.nix
          inputs.disko.nixosModules.disko
          inputs.impermanence.nixosModules.impermanence
        ];
      };
    };
  };
}

Discover where your root subvolume is located with findmnt:

If you followed the Encrypted Setups guide, your encrypted subvolume should be located at: /dev/mapper/cryptroot /mnt

Your encrypted Btrfs partition, once unlocked by LUKS, will be available at /dev/mapper/cryptroot as configured here in the disk-config.nix:

# disk-config2.nix
# ... snip ...
            luks = {
              size = "100%";
              label = "luks";
              content = {
                type = "luks";
                name = "cryptroot";
                content = {
# ... snip ...

Double check that the paths exist:

cd /dev/mapper/crypt<TAB>  # autocomplete should fill out /dev/mapper/cryptroot

Create an impermanence.nix:

Now, create a new file named impermanence.nix in your configuration directory (i.e. your flake directory). This file will contain all the specific settings for your impermanent setup, including BTRFS subvolume management and persistent data locations. Since this file is right next to your configuration.nix, you’ll just add an imports = [ ./impermanence.nix ] to your configuration.nix apply it to your configuration.

{
  config,
  lib,
  ...
}: {
  boot.initrd.postDeviceCommands = lib.mkAfter ''
    echo "Rollback running" > /mnt/rollback.log
     mkdir -p /mnt
     mount -t btrfs /dev/mapper/cryptroot /mnt

     # Recursively delete all nested subvolumes inside /mnt/root
     btrfs subvolume list -o /mnt/root | cut -f9 -d' ' | while read subvolume; do
       echo "Deleting /$subvolume subvolume..." >> /mnt/rollback.log
       btrfs subvolume delete "/mnt/$subvolume"
     done

     echo "Deleting /root subvolume..." >> /mnt/rollback.log
     btrfs subvolume delete /mnt/root

     echo "Restoring blank /root subvolume..." >> /mnt/rollback.log
     btrfs subvolume snapshot /mnt/root-blank /mnt/root

     umount /mnt
  '';

  environment.persistence."/persist" = {
    directories = [
      "/etc"
      "/var/spool"
      "/srv"
      "/etc/NetworkManager/system-connections"
      "/var/lib/bluetooth"
    ];
    files = [
      # "/etc/machine-id"
      # Add more files you want to persist
    ];
  };

# optional quality of life setting
  security.sudo.extraConfig = ''
    Defaults lecture = never
  '';
}

/mnt/rollback.log: this log will be available during the boot process for debugging if the rollback fails, but won’t persist.

With the above impermanence script, the btrfs subvolumes are deleted recursively and replaced with the root-blank snapshot we took during the install.

I have commented out "/etc/machine-id" because we already copied over all of the files to their persistent location and the above setting would work once and then cause a conflict.

configuration.nix changes

# configuration.nix
  boot.initrd.luks.devices = {
    cryptroot = {
      device = "/dev/disk/by-partlabel/luks";
      allowDiscards = true;
      preLVM = true;
    };
  };

This defines how your system’s initial ramdisk (initrd) should handle a specific encrypted disk during the boot process. It helps with timing and is a more robust way of telling Nix that we are using an encrypted disk.

The following is optional to enable autoScrub for btrfs, the wiki shows interval = "monthly"; FYI.

# configuration.nix
  services.btrfs.autoScrub = {
    enable = true;
    interval = "weekly";
    fileSystems = ["/"];
  };

Remember to ensure that your hostname in your configuration.nix matches the hostname in your flake.nix.

Applying Your Impermanence Configuration

Once you have completed all the steps and created or modified the necessary files (flake.nix, impermanence.nix), you need to apply these changes to your NixOS system.

Navigate to your NixOS configuration directory (where your flake.nix is located).

cd /path/to/your/flake

Rebuild and Switch: Execute the nixos-rebuild switch command. This command will:

Evaluate your flake.nix and the modules it imports (including your new impermanence.nix).
Build a new NixOS system closure based on your updated configuration.
Activate the new system configuration, making it the current running system.

sudo nixos-rebuild switch --flake .#hostname # Replace 'hostname' with your actual system hostname

Perform an Impermanence Test (Before Reboot):

Before you reboot, create a temporary directory and file in a non-persistent location. Since you haven’t explicitly added /imperm_test to your environment.persistence."/persist" directories, this file should not survive a reboot.

mkdir /imperm_test
echo "This should be Gone after Reboot" | sudo tee /imperm_test/testfile
ls -l /imperm_test/testfile # Verify the file exists
cat /imperm_test/testfile # Verify content

Reboot Your System: For the impermanence setup to take full effect and for your root filesystem to be reset for the first time, you must reboot your machine.

sudo reboot

Verify Impermanence (After Reboot):

After the system has rebooted, check if the test directory and file still exist:

ls -l /imperm_test/testfile

Your system should now come up with a fresh root filesystem, and only the data specified in your environment.persistence."/persist" configuration will be persistent.

Sops-Nix

2025-11-22T00:00:00+00:00

Sops-Nix encrypted secrets

Click to Expand Table of Contents

SOPS, short for SecretsOPerationS, is an editor of encrypted files that supports quite a few BINARY formats and encrypts with AWS KMS, GCP KMS, Azure Key Vault, age, and PGP.

Managing secrets—like API keys, SSH deploy keys, and password hashes is a critical part of system configuration, but it’s also one of the trickiest to do securely and reproducibly. Traditionally, secrets might be stored in ad hoc locations, referenced by absolute paths, or managed manually outside of version control. This approach makes it hard to share, rebuild, or audit your configuration, and increases the risk of accidental leaks or inconsistencies between systems.

sops-nix solves these problems by integrating Mozilla SOPS directly into your NixOS configuration. Instead of relying on hardcoded file paths or copying secrets around, you declare your secrets in your Nix code, encrypt them with strong keys, and let sops-nix handle decryption and placement at activation time.

Encryption with strong keys, as used by sops-nix, makes brute force attacks computationally unfeasible with current technology—the time and resources required to try every possible key would be astronomically high. However, this protection relies on using strong, secret keys and good security practices; advances in technology or poor key management can weaken this defense.

❗ CRITICAL SECURITY NOTE: While the encryption itself is robust, this protection fundamentally relies on using strong, secret keys and diligent security practices. If your PGP passphrase is weak, your Age private key is easily guessable, or the cleartext secret itself is very short and has low entropy (e.g., “12345”, “true”, “admin”), an attacker might be able to compromise your secrets regardless of the encryption.

Add sops to your flake.nix:

{
  inputs.sops-nix.url = "github:Mic92/sops-nix";
  inputs.sops-nix.inputs.nixpkgs.follows = "nixpkgs";

  outputs = { self, nixpkgs, sops-nix }: {
    # change `yourhostname` to your actual hostname
    nixosConfigurations.yourhostname = nixpkgs.lib.nixosSystem {
      # customize to your system
      system = "x86_64-linux";
      modules = [
        ./configuration.nix
        sops-nix.nixosModules.sops
      ];
    };
  };
}

Add sops and age to your environment.systemPackages:

environment.systemPackages = [
    pkgs.sops
    pkgs.age
];

Generate a key (This is your private key and MUST NEVER BE COMMITTED TO GIT OR SHARED):

mkdir -p ~/.config/sops/age
age-keygen -o ~/.config/sops/age/keys.txt

To get the Public Keys Value, run the following command:

age-keygen -y ~/.config/sops/age/keys.txt
age12zlz6lvcdk6eqaewfylg35w0syh58sm7gh53q5vvn7hd7c6nngyseftjxl

Copy the age value it gives you back.

Create a .sops.yaml in the same directory as your flake.nix:

# .sops.yaml
keys:
  # Your personal age public key (from age-keygen -y ~/.config/sops/age/keys.txt)
  - &personal_age_key age12zlz6lvcdk6eqaewfylg35w0syh58sm7gh53q5vvn7hd7c6nngyseftjxl

  # You can also use PGP keys if you prefer, but age is often simpler
  # - &personal_pgp_key 0xDEADBEEFCAFE0123

creation_rules:
  # This rule applies to any file named 'secrets.yaml' directly in the 'secrets/' directory
  # or 'secrets/github-deploy-key.yaml' etc.
  - path_regex: "secrets/.*\\.yaml$"
    key_groups:
      - age:
          - *personal_age_key
        # Add host keys for decryption on the target system
        # sops-nix will automatically pick up the system's SSH host keys
        # as decryption keys if enabled in your NixOS config.
        # So you typically don't list them explicitly here unless you
        # want to restrict it to specific fingerprints, which is rare.
        # This part ensures your *personal* key can decrypt it.

Save it and move on, this file and sops.nix are safe to version control.

sops-nix’s automatic decryption feature using system SSH host keys only works with ed25519 host keys for deriving Age decryption keys. Therefore, for system decryption, ensure your using ed25519 not rsa keys:

ssh-keygen -t ed25519 -C "your_email@example.com"
# for multiple keys run something like
ssh-keygen -t ed25519 -f ~/nix-book-deploy-key -C "deploy-key-nix-book-repo"

Copy the PRIVATE key for each and add them to your secrets directory:

While in your flake directory:

mkdir secrets
sops secrets/github-deploy-key.yaml  # For your github ssh key

When you call a sops command, it will handle the encryption/decryption transparently and open the cleartext file in an editor.

Editing will happen in the editor that $SOPS_EDITOR or $EDITOR is set to, sops will wait for the editor to exit, and then try to reencrypt the file.

The above command will open a default sops github-deploy-key.yaml in your $EDITOR:

Erase the default sops filler and type github_deploy_key_ed25519: |, move your cursor 1 line down and type :r ~/.ssh/id_ed25519 to read the private key into the file and repeat as needed.

github_deploy_key_ed25519: |
  -----BEGIN OPENSSH PRIVATE KEY-----
  ...
  -----END OPENSSH PRIVATE KEY-----

github_deploy_key_ed25519_nix-book: |
  -----BEGIN OPENSSH PRIVATE KEY-----
  ...
  -----END OPENSSH PRIVATE KEY-----

The -----BEGIN and the rest of the private key must be indented 2 spaces

Ensure sops can decrypt it:

sops -d secrets/github-deploy-key.yaml

❗ WARNING: Only ever enter your private keys through the sops command. If you forget and paste them in without the sops command then run git add at any point, your git history will have contained an unencrypted secret which is a nono. Always use the sops command when dealing with files in the secrets directory, save the file and inspect that it is encrypted on save. If not something went wrong with the sops process, do not add it to Git. If you do, you will be required to rewrite your entire history which can be bad if you’re collaborating with others. git-filter-repo is one such solution that rewrites your history. Just keep this in mind. This happens because Git has a protection that stops you from doing stupid things.

Generate an encrypted password hash with:

mkpasswd --method=yescrypt > /tmp/password-hash.txt
# Enter your chosen password and copy the encrypted hash it gives you back

sops secrets/password-hash.yaml      # For your `hashedPasswordFile`

The above command will open your $EDITOR with the file password-hash.yaml, add the following content to it. Replace PasteEncryptedHashHere with the output of the mkpasswd command above:

Delete the default sops filler, type password_hash: and leave your cursor after the : and type :r /tmp/password-hash.txt

password_hash: PasteEncryptedHashHere

Ensure sops can decrypt it:

sops -d secrets/password-hash.yaml

Create a sops.nix and import it or add this directly to your configuration.nix:

My sops.nix is located at ~/flake/hosts/hostname/sops.nix and the secrets directory is located at ~/flake/secrets so the path from sops.nix to secrets/pasword-hash.yaml would be ../../secrets/password-hash.yaml

Another step you can take is to copy your key to a persistent location, preparing for impermanence:

sudo mkdir /persist/sops/age
sudo cp ~/.config/sops/age/keys.txt /persist/sops/age/keys.txt

Then you would change the age.keyFile = "/persist/sops/age/keys.txt" to match this location below.

# ~/flake/hosts/magic/sops.nix  # magic is my hostname
# hosts/magic/ is also where my configuration.nix is
{...}: {
  sops = {
    defaultSopsFile = ../../.sops.yaml; # Or the correct path to your .sops.yaml
    # Don't mix sshKeyPaths and keyFile
    age.sshKeyPaths = [];
    age.keyFile = "/persist/sops/age/keys.txt";

    secrets = {
      "password_hash" = {
        sopsFile = ../../secrets/password-hash.yaml; # <-- Points to your password hash file
        owner = "root";
        group = "root";
        mode = "0400";
        neededForUsers = true;
      };
      "github_deploy_key_ed25519_nix-book" = {
        sopsFile = ../../secrets/github-deploy-key.yaml;
        key = "github_deploy_key_ed25519_nix-book";
        owner = "root";
        group = "root";
        mode = "0400";
      };
      "github_deploy_key_ed25519" = {
        sopsFile = ../../secrets/github-deploy-key.yaml;
        key = "github_deploy_key_ed25519";
        owner = "root";
        group = "root";
        mode = "0400";
      };
    };
  };
}

Import sops.nix into your configuration.nix or equivalent:

# configuration.nix
imports = [
  ./sops.nix # Assuming sops.nix is in the same directory as configuration.nix, adjust path as needed
  # ... other imports
];

❗ NOTE: You may see in the sops quickstart guide that if you’re using impermanence, the key used for secret decryption (sops.age.keyFile) must be in a persistent directory, loaded early enough during the boot process. If you are using the btrfs subvolume layout you don’t need to worry about this because your home will be on its own partition when only the root partition is wiped on reboot. Adding neededForUsers = true; tells sops-nix to decrypt and make that secret available earlier in the boot process specifically, before user and group accounts are created.

You typically use age.sshKeyPaths for system-level secrets with a persistent SSH host key

For user-level secrets, use age.keyFile pointing to your Age private key, stored in a safe persistent location.

For reproducibility, keep your key files in a persistent, predictable path and document which keys are used for which secrets in your .sops.yaml.

If you don’t need both age.keyFile and age.sshKeyPaths it can reduce complexity to use one or the other. Although most people may choose one, it’s not bad to use both it just adds complexity.

And finally use the password-hash for your hashedPasswordFile for your user, my user is jr so I added this:

# ... snip ...
    users.users = {
      # ${username} = {
      jr = {
        homeMode = "755";
        isNormalUser = true;
        # description = userVars.gitUsername;
        hashedPasswordFile = config.sops.secrets.password_hash.path;
  # ...snip...

By integrating SOPS with NixOS through sops-nix, you gain a modern, secure, and reproducible way to manage sensitive secrets. Unlike traditional approaches where secrets are often scattered in ad hoc locations, referenced by absolute paths, or managed outside version control, sops-nix keeps your secrets encrypted, declarative, and version-control friendly.

Readme1

2025-11-22T00:00:00+00:00

Hardening README

✔️ Click to Expand Table of Contents

📌 How to Use This Guide

Read warnings: Advanced hardening can break compatibility or cause data loss! Pause and research before enabling anything not listed above unless you understand the consequences.

Hardening NixOS:

🔷 Start Here:

Additional security/hardening topics

Getting Started

There is a lot covered in this guide which can get overwhelming when trying to decide what is worth implementing. Here, I will list some common recommendations that most users should follow to harden their stance.

“The major problem with current systems is their inability to provide effective isolation between various programs running on one machine. E.g. if the user’s Web browser gets compromised (due to a bug exploited by a malicious web site), the OS is usually unable to protect other user’s applications and data from also being compromised.”–Qubes arch-spec

Threat Modeling

You should always start by conducting a personal threat assesment to identify potential threats and vulnerabilities that you need to develop strategies to defend against.

Threat modeling in computing involves evaluating the security risks to your computer or network. It helps uncover possible threats and weaknesses so you can create plans to safeguard your systems and data effectively. By examining various attack scenarios, you can anticipate potential cyber threats and better protect your digital resources.

It’s not possible to protect yourself against every attack(er), focus on the most probable threats to your specific situation.

Baseline Hardening

Before diving into advanced or specialized hardening, apply these baseline security measures suitable for all NixOS users. These settings help protect your system with minimal risk of breaking workflows or causing admin headaches.

There is something to be said about the window manager you use. GNOME, KDE Plasma, and Sway secure privileged Wayland protocols like screencopy. This means that on environments outside of GNOME, KDE, and Sway, applications can access screen content of the entire desktop. This implicitly includes the content of other applications. It’s primarily for this reason that Silverblue, Kinoite, and Sericea images are recommended. COSMIC has plans to fix this. –secureblue Images

Secureblue recommends disabling Xwayland and finding alternatives for those apps as well as disabling xdg-desktop-portal-wlr, this is because the wlroots desktop portal reintroduces the screencopy vulnerability.

Use Disk Encryption (LUKS) to protect your data at rest.
Keep your system up to date (update regularly).
Use strong, unique passwords. To generate one from the command-line, there is pkgs.diceware. Generate a password with: diceware -n 12 -w en_eff, add spaces between the words for higher entropy.
- Kicksecure Password_Generation
Avoid reusing passwords, use a password manager.
Avoid storing files directly in the root home folder (i.e., /home/user), create sub-folders instead.(i.e., Instead of creating ~/notes.txt, create ~/my-notes/notes.txt or ~/Documents/notes.txt).
- If you are able to implement a Mandatory Access Control framework, there are more sub-folders that should be avoided such as ~/Downloads. Another reason to use non-default sub-dirs is to avoid typos deleting important files.
- Home-Manager has an option xdg.userDirs.enable

# home.nix or equivalent
{
  xdg.userDirs.enable = true;
  xdg.userDirs.createDirectories = true;
  # Optionally create non-default sub-dirs
  # xdg.userDirs.documents = "/home/jr/my-documents";
  # xdg.userDirs.download = "/home/jr/my-downloads";
}

The XDG Base Directory Specification defines a consistent way for apps and desktops to store and find files. It helps prevent “dotfile clutter” by directing application files into clear, organized locations.
Only enable what you use, and actively disable what’s no longer in use.
Enable at least a basic firewall, a more complex firewall example that utilizes nftables is shared in the Hardening Networking Chapter

Although the firewall is enabled by default on NixOS, let’s be explicit about it, add the following to your configuration.nix or equivalent:

# configuration.nix
# this denies incoming connections but allows outgoing and established connections
networking.firewall.enable = true;

Many services provide an option to open the required firewall ports automatically. For example:

services.tor.openFirewall = true;

This prevents you from having to manually open ports

Audit and remove local user accounts that are no longer needed: Regularly review and remove unused or outdated accounts to reduce your system’s attack surface, improve compliance, and ensure only authorized users have access. The following setting ensures that user (and group) management is fully declarative:

# configuration.nix
# All users must be declared
users.mutableUsers = false;

With users.mutableUsers = false;, all non-declaratively managed (imperative) user management including creation, modification, or password changes will fail or be reset on rebuild. User and group definitions become entirely controlled by your system configuration for maximum reproducibility and security. If you need to add, remove, or modify users, you must do so in your configuration.nix and rebuild the system.

Don’t log in as root, it’s unnecessary.

Commands that require root permissions should be run individually using sudo in all cases. Avoid logging in as root & using sudo su.

Never run GUI applications as root. If there is a legitimate reason for doing this, use lxsudo instead.

NOTE: There is mention of making userborn the default for NixOS in the future. It can be more secure by prohibiting UID/GID re-use and giving warnings about insecure password hashing schemes.

I have personally had nothing but problems with userborn and find the docs extremely lacking, you need to read the source code to figure anything out which is ridiculous. I don’t personally use this but if you figure it out, more power to ya.

To enable userborn, just add the following to your configuration.nix or equivalent:

# users.nix
{pkgs,...}:{
services.userborn = {
    enable = true;
    # Only needed if `/etc` is immutable
    # passwordFilesLocation = "/var/lib/nixos/userborn"
};
    users.users = {
       "newuser" = {
         homeMode = "755";
         uid = 1000;
         isNormalUser = true;
         description = "New user account";
         extraGroups = [ "networkmanager" "wheel" "libvirtd" ];
         shell = pkgs.bash;
         ignoreShellProgramCheck = true;
         packages = with pkgs; [];
       };
    };
    }

With userborn, you configure your users as you normally would declaratively with NixOS with users.users, change "newuser" to your desired username.

Explicitly setting uid = 1000; is a best practice for compatibility and predictability.

Only install, enable, and run what is needed: Disable or uninstall unnecessary software and services to minimize potential vulnerabilities. Take advantage of NixOS’s easy package management and minimalism to keep your system lean and secure.

Avoid permanently installing temporary tools: Use tools like nix-shell, comma, devShells and nix-direnv to test or run software temporarily. This prevents clutter and reduces potential risks from unused software lingering on the system.

Update regularly: Keep your system and software up to date to receive the latest security patches. Delaying updates leaves known vulnerabilities open to exploitation.

Apply the Principle of Least Privilege: Never run tools or services as root unless absolutely necessary. Create dedicated users and groups with the minimum required permissions to limit potential damage if compromised.

Use strong passwords and passphrases: Aim for at least 14–16 characters by combining several unrelated words, symbols, and numbers. For example: sunset-CoffeeHorse$guitar!. Strong passphrases are both memorable and secure.

Use a password manager and enable multi-factor authentication (MFA): Manage unique, strong passwords effectively with a trusted manager and protect accounts with MFA wherever possible for a second layer of defense.

Check logs regularly: Reviewing your system logs helps you spot unusual activity, errors, or failed login attempts that could indicate a security problem. NixOS uses journald by default, which makes this easy. For example, to see the logs for your current boot session:

journalctl -b
# for the previous session
journalctl -b -1

After establishing some standard best practices and a hardened base, it’s time to dive deeper into system hardening, the process of adding layered safeguards throughout your NixOS setup. This next section guides you through concrete steps and options for hardening critical areas of your system: from encryption and secure boot to managing secrets, tightening kernel security, and leveraging platform-specific tools. Hardening NixOS

Lanzaboote

2025-11-22T00:00:00+00:00

Secure Boot with Lanzaboote

Click to Expand Table of Contents

⚠️ Warning: This can easily brick your system ⚠️

We will mainly follow the lanzaboote Quick Start Guide

For Windows dual-booters and BitLocker users, you should export your BitLocker recovery keys and confirm that they are correct. Refer to this Microsoft support article

❗ NOTE: There are some serious limitations to this setup when used without encryption, I’d say it could stop the average person. But an experienced hacker could easily bypass this without encryption if they had access to your computer. For more protection look into TPM2 Hardware Requirements, and full disk encryption.

Important Considerations

I found This Article fairly enlightening as far as the state of Authenticated Boot and Disk Encryption on Linux.

Brave New Trusted Boot World

Lanzaboote only secures the boot chain. The userspace remains unverified (i.e., the nix store, etc.), to verify userspace you need to implement additional integrity checks. It’s common to rely to disk encryption to prevent tampering with and keep the Nix store safe but it’s not always desirable. (i.e., unattended boot)

Requirements

To be able to setup Secure Boot on your device, NixOS needs to be installed in UEFI mode and systemd-boot must be used as a boot loader. This means if you wish to install lanzaboote on a new machine, you need to follow the install instruction for systemd-boot and then switch to lanzaboote after the first boot.

Check these prerequisits with bootctl status, this is an example output:

sudo bootctl status
System:
     Firmware: UEFI 2.70 (Lenovo 0.4720)
  Secure Boot: disabled (disabled)
 TPM2 Support: yes
 Boot into FW: supported

Current Boot Loader:
      Product: systemd-boot 251.7
...

The firmware must be UEFI and the current bootloader needs to be systemd-boot. If you check these boxes, you’re good to go.

Security Requirements

To provide any security your system needs to defend against an attacker turning UEFI Secure Boot off or being able to sign binaries with the keys we are going to generate.

The easiest way to achieve this is to:

Enable a BIOS password for your system, this will prevent someone from just shutting off secure boot.
Use full disk encryption.

Preparation

Finding the UEFI System Partition (ESP)

The UEFI boot process revolves around the ESP, the (U)EFI System Partition. This partition is conventionally mounted at /boot on NixOS.

Verify this with the command sudo bootctl status. Look for ESP:

Creating Your Keys

First you’ll need to install sbctl which is available in Nixpkgs:

# configuration.nix or equivalent
environment.systemPackages = [ pkgs.sbctl ];

Create the keys:

$ sudo sbctl create-keys
[sudo] password for julian:
Created Owner UUID 8ec4b2c3-dc7f-4362-b9a3-0cc17e5a34cd
Creating secure boot keys...✓
Secure boot keys created!

If you already have keys in /etc/secureboot migrate these to /var/lib/sbctl:

sbctl setup --migrate

Configuring Lanzaboote With Flakes

Shown all in flake.nix for brevity. Can easily be split up into a boot.nix, etc:

{
  description = "A SecureBoot-enabled NixOS configurations";

  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";

    lanzaboote = {
      url = "github:nix-community/lanzaboote/v0.4.2";

      # Optional but recommended to limit the size of your system closure.
      inputs.nixpkgs.follows = "nixpkgs";
    };
  };

  outputs = { self, nixpkgs, lanzaboote, ...}: {
    nixosConfigurations = {
      yourHost = nixpkgs.lib.nixosSystem {
        system = "x86_64-linux";

        modules = [
          # This is not a complete NixOS configuration and you need to reference
          # your normal configuration here.

          lanzaboote.nixosModules.lanzaboote

          ({ pkgs, lib, ... }: {

            environment.systemPackages = [
              # For debugging and troubleshooting Secure Boot.
              pkgs.sbctl
            ];

            # Lanzaboote currently replaces the systemd-boot module.
            # This setting is usually set to true in configuration.nix
            # generated at installation time. So we force it to false
            # for now.
            boot.loader.systemd-boot.enable = lib.mkForce false;

            boot.lanzaboote = {
              enable = true;
              pkiBundle = "/var/lib/sbctl";
            };
          })
        ];
      };
    };
  };
}

Build it

sudo nixos-rebuild switch --flake /path/to/flake

Ensure Your Machine is Ready for Secure Boot enforcement

$ sudo sbctl verify
Verifying file database and EFI images in /boot...
✓ /boot/EFI/BOOT/BOOTX64.EFI is signed
✓ /boot/EFI/Linux/nixos-generation-355.efi is signed
✓ /boot/EFI/Linux/nixos-generation-356.efi is signed
✗ /boot/EFI/nixos/0n01vj3mq06pc31i2yhxndvhv4kwl2vp-linux-6.1.3-bzImage.efi is not signed
✓ /boot/EFI/systemd/systemd-bootx64.efi is signed

Enabling Secure Boot and Entering Setup Mode

This is where things can get tricky because UEFI/BIOS are widely different and use different conventions.

You can see your BIOS from the output of bootctl status:

sudo bootctl status
doas (jr@magic) password:
System:
      Firmware: UEFI 2.70 (American Megatrends)

My UEFI is an American Megatrends, find yours and look up which key you have to hit to enter the BIOS on reboot, mine is the delete key. So I reboot and repeatedly hit delete until it brings up the BIOS settings.

The lanzaboote guide shows a few systems and how to enter setup mode for them.

For a ThinkPad the steps are:

Select the “Security” tab.
Select the “Secure Boot” entry.
Set “Secure Boot” to enabled.
Select “Reset to Setup Mode”.

For my system, it would allow me to do the above steps but when I saved and exited I got a red screen then blue screen and it said No Valid Keys or something like that and eventually brought me to the MOK Manager where you can manually register keys, this is NOT what you want to do.

Even after this mistake I was able to re-enable secure boot and get back into the system.

After some tinkering, I found that I was able to enter “custom mode” without enabling secure boot, which in turn allowed me to select the “Reset to Setup Mode”

It asks if you are sure you want to erase all of the variables to enter setup mode? Hit “Yes”. Then it asks if you want to exit without saving, we want to save our changes so hit “No” do not exit without saving.

After this you should see all No Keys entries.

Finally, Hit the setting to save and exit, some BIOS list an F4 or F9 keybind that saves and exits.

❗: For my system, choosing “save and reboot” would not work for some reason, I had to choose “save and exit”.

After hitting “save and exit”, the system boots into NixOS like normal but you are in setup mode if everything worked correctly.

Open a terminal and type:

sudo sbctl enroll-keys --microsoft
Enrolling keys to EFI variables...
With vendor keys from microsoft...✓
Enrolled keys to the EFI variables!

⚠️ If you used --microsoft while enrolling the keys, you might want to check that the Secure Boot Forbidden Signature Database (dbx) is not empty. A quick and dirty way is by checking the file size of /sys/firmware/efi/efivars/dbx-\*. Keeping an up to date dbx reduces Secure Boot bypasses, see for example: https://uefi.org/sites/default/files/resources/dbx_release_info.pdf

I then Rebooted into BIOS and enabled secure boot, saved and exited. This loads NixOS as if you just rebooted.

And finally check the output of sbctl status:

sudo sbctl status
System:
      Firmware: UEFI 2.70 (American Megatrends)
 Firmware Arch: x64
   Secure Boot: enabled (user)
  TPM2 Support: yes
  Measured UKI: yes
  Boot into FW: supported

We can see the Secure Boot: enabled (user)

What Lanzaboote (Secure Boot) Actually Secures on NixOS and Limitations

As mentioned earlier, this provides some basic protection that may be good enough for your desktop in your bedroom but there are some serious limitations. I want to be clear that this may stop an average person but an advanced threat actor with resources could still fairly easily get in.

Secure Boot (with Lanzaboote or any other tool) on NixOS primarily protects the boot chain—the bootloader, kernel, and initrd—by ensuring only signed, trusted binaries are executed at boot. This is a real and valuable security improvement, especially for defending against “evil maid” attacks (where someone with physical access tampers with your bootloader or kernel) and for preventing many forms of persistent malware.

Here are some of the caveats:

Userspace Remains Unverified

Once the kernel and initrd have booted, NixOS (by default) does not cryptographically verify the integrity of the rest of userspace (the programs and libraries in the Nix store, your configs, etc.).

This means an attacker who can modify userspace (e.g., by gaining root access) can potentially install persistent malware, even if your boot chain is protected

.
Kernel Lockdown Is Not Enabled

The Linux kernel’s [lockdown mode]

is designed to prevent even root from tampering with the kernel at runtime (e.g., by loading unsigned modules, using kexec, or accessing /dev/mem).

NixOS does not enable kernel lockdown by default, and enabling it is non-trivial, especially given how the Nix store works (modules and kernels are built dynamically and not always signed at install time).

Without lockdown, a root user (or malware with root) can still compromise the kernel after boot.
Stage 2 Verification Is Lacking

Some distributions (like Fedora Silverblue or systems using dm-verity) cryptographically verify the entire userspace at boot, making it immutable and much harder to tamper with. This is not the default on NixOS, though there are experimental or appliance-focused solutions

.
Disk Encryption Complements Secure Boot

Full disk encryption (e.g., LUKS) is strongly recommended alongside Secure Boot. Encryption protects your data at rest and ensures that even if someone bypasses Secure Boot, they cannot read or modify your files without your passphrase

Local Nixpkgs

2025-11-22T00:00:00+00:00

Chapter 10

✔️ Click to Expand Table of Contents

Working with Nixpkgs Locally: Benefits and Best Practices

Nixpkgs, the package repository for NixOS, is a powerful resource for building and customizing software.
Working with a local copy enhances development, debugging, and contribution workflows.
This post covers setting up a local Nixpkgs repository, searching for dependencies, and leveraging its advantages, incorporating tips from the Nix community.

I. Why Work with Nixpkgs Locally?

A local Nixpkgs repository offers significant advantages for Nix developers:

A. Faster Development Cycle
- Local searches for packages and dependencies are significantly quicker than querying remote repositories or channels.
- This speedup is crucial for efficient debugging and rapid prototyping of Nix expressions.
B. Enhanced Version Control
- By pinning your local repository to specific commits or branches (e.g., nixos-unstable), you ensure build reproducibility.
- This prevents unexpected issues arising from upstream changes in Nixpkgs.
C. Flexible Debugging Capabilities
- You can directly test and modify package derivations within your local copy.
- This allows for quick fixes to issues like missing dependencies without waiting for upstream updates or releases.
D. Streamlined Contribution Workflow
- Developing and testing new packages or patches locally is essential before submitting them as pull requests to Nixpkgs.
- A local setup provides an isolated environment for experimentation.
E. Up-to-Date Documentation Source
- The source code and comments within the Nixpkgs repository often contain the most current information about packages.
- This can sometimes be more up-to-date than official, external documentation.
F. Optimized Storage and Performance
- Employing efficient cloning strategies (e.g., shallow clones) and avoiding unnecessary practices (like directly using Nixpkgs as a flake for local development) minimizes disk usage and build times.

II. Flake vs. Non-Flake Syntax for Local Nixpkgs

When working with Nixpkgs locally, the choice between Flake and non-Flake syntax has implications for performance and storage:

A. Flake Syntax (nix build .#<package>)
- Treats the current directory as a flake, requiring evaluation of flake.nix.
- For local Nixpkgs, this evaluates the flake definition in the repository root.
- Performance and Storage Overhead: Flakes copy the entire working directory (including Git history if present) to /nix/store for evaluation. This can be slow and storage-intensive for large repositories like Nixpkgs.
B. Non-Flake Syntax (nix-build -f . <package> or nix build -f . <package>)
- -f . specifies the Nix expression (e.g., default.nix or a specific file) in the current directory.
- Efficiency: Evaluates the Nix expression directly without copying the entire worktree to /nix/store. This is significantly faster and more storage-efficient for local development on large repositories.

III. Setting Up a Local Nixpkgs Repository Efficiently

Cloning Nixpkgs requires careful consideration due to its size.

A.a Initial Clone: Shallow Cloning

It is common to place your local clone in the /src directory:

mkdir src && cd src

❗ Warning, A shallow clone (--depth 1) is not recommended for general development or contributing changes back to Nixpkgs via pull requests. It’s primarily suitable for:

Quick checks or builds: If you only need to verify a package’s current state or build a specific version without needing historical context.

CI/CD environments: Where disk space and clone time are critical, and only the latest commit is needed for automated tests or builds.

With that said, to avoid downloading the entire history, perform a shallow clone:

git clone [https://github.com/NixOS/nixpkgs](https://github.com/NixOS/nixpkgs) --depth 1
cd nixpkgs

A.b A few Examples exploring Nixpkgs

While in the nixpkgs directory, you can check the version of a package:

nix-instantiate --eval -A openssl.version
"3.4.1"

Or to directly edit the file you can use nix edit:

nix edit nixpkgs#openssl

It uses the nix registry and openssl.meta.position to locate the file.

man nix3 registry

The above command will open the openssl/default.nix in your $EDITOR.

A.1 Full Fork and Clone of Nixpkgs

If you want to contribute to Nixpkgs, you need to set up a local version following the Contributing guide

You’ll need to, this is directly from the Contributing.md:

Fork the Nixpkgs repository
Clone the forked repo into a local nixpkgs directory.

git clone git@github.com:your-user/nixpkgs.git

Configure the upstream Nixpkgs repo

git remote add upstream git@github.com:NixOS/nixpkgs.git
# Check them out
git remove -v

The Three Master Branches

Upstream Master (upstream/master):

Where it is: On the official NixOS servers.
Role: The absolute source of truth. Thousands of people are pushing to this daily.

Local Master (master):

Where it is: On your physical computer.
Role: Your working copy. This is the only one you can actually “rebase” or “commit” to directly.

Origin Master (origin/master):

Where it is: On your GitHub fork (github.com/your-user/nixpkgs).
Role: A personal backup and a place to host your code so you can open Pull Requests.

Create a branch

In the nixpkgs ecosystem, the “cleanest” way to work is to never add your own commits to your local master.

Keep your master as a “pure mirror” of upstream/master.
Whenever you want to fix a package or add something new, create a feature branch:

git checkout -b fix-my-package master

This way, syncing is as simple as a reset:

# Total reset of your local master to match the official one
git fetch upstream
git checkout master
git reset --hard upstream/master
git push origin master --force

Pushing a PR

When you’re ready to push changes you push to origin/feature-branch, visit your fork on github.com and submit the PR.

B. Managing Branches with Worktrees

Use Git worktrees to manage different branches efficiently:

git fetch --all --prune --depth=1
git worktree add -b nixos-unstable nixos-unstable # For just unstable

Explanation of git worktree: Allows multiple working directories attached to the same .git directory, sharing history and objects but with separate checked-out files.
git worktree add: Creates a new working directory for the specified branch (nixos-unstable in this case).

IV. Debugging Missing Dependencies: A Practical Example

Click to see icat Example

Let’s say you’re trying to build icat locally and encounter a missing dependency error:

nix-build -A icat
# ... (Error log showing "fatal error: X11/Xlib.h: No such file or directory")

The error fatal error: X11/Xlib.h: No such file or directory indicates a missing X11 dependency.

A. Online Search with `search.nixos.org`

The Nixpkgs package search website (https://search.nixos.org/packages) is a valuable first step.
However, broad terms like “x11” can yield many irrelevant results.
Tip: Utilize the left sidebar to filter by package sets (e.g., “xorg”).

B. Local Source Code Search with `rg` (ripgrep)

Familiarity with searching the Nixpkgs source code is crucial for finding dependencies.

Navigate to your local nixpkgs/ directory and use rg:

rg "x11 =" pkgs # Case-sensitive search

Output:

pkgs/tools/X11/primus/default.nix
21:  primus = if useNvidia then primusLib_ else primusLib_.override { nvidia_x11 = null; };
22:  primus_i686 = if useNvidia then primusLib_i686_ else primusLib_i686_.override { nvidia_x11 = null; };

pkgs/applications/graphics/imv/default.nix
38:    x11 = [ libGLU xorg.libxcb xorg.libX11 ];

Refining the search (case-insensitive):

rg -i "libx11 =" pkgs

Output:

# ... (Output showing "xorg.libX11")

The key result is xorg.libX11, which is likely the missing dependency.

V. Local Derivation Search with `nix-locate`

Click to Expand nix-locate command Example

nix-locate (from the nix-index package) allows searching for derivations on the command line.

Note: Install nix-index and run nix-index to create the initial index.
```
nix-locate libx11
# ... (Output showing paths related to libx11)
```
Combining online and local search tools (search.nixos.org, rg, nix-locate) provides a comprehensive approach to finding dependencies.

VI. Key Benefits of Working with Nixpkgs Locally (Recap)

Speed: Faster searches and builds compared to remote operations.
Control: Full control over the Nixpkgs version.
Up-to-Date Information: Repository source often has the latest details.

VII. Best Practices and Tips from the Community

✔️ Click To Expand Best Practices and Tips from the community

Rebasing over Merging: Never merge upstream changes into your local branch. Always rebase your branch onto the upstream (e.g., master or nixos-unstable) to avoid accidental large-scale pings in pull requests (Tip from soulsssx3 on Reddit).
Tip from ElvishJErrico: Avoid using Nixpkgs directly as a flake for local development due to slow copying to /nix/store and performance issues with garbage collection on large numbers of small files. Use nix build -f . <package> instead of nix build .#<package>.
Edge Cases for Flake Syntax: Flake syntax might be necessary in specific scenarios, such as NixOS installer tests where copying the Git history should be avoided.
Base Changes on nixos-unstable: For better binary cache hits, base your changes on the nixos-unstable branch instead of master. Consider the merge-base for staging branches as well.
Consider jujutsu: Explore jj-vcs, a Git-compatible alternative that can offer a more intuitive workflow, especially for large monorepos like Nixpkgs. While it has a learning curve, it can significantly improve parallel work and branch management.
Intro-To-Jujutsu

Fork, Clone, Contribute

2025-11-22T00:00:00+00:00

Fork, Clone, Contribute

In the Nixpkgs Repository.
Click Fork, then Create a new Fork.
Uncheck the box “Only fork the master branch”, for development we will need more branches.
- If you only fork master, you won’t have the nixos-XX.YY release branches available on your fork when you later try to create a PR against them, or when you want to create a feature branch from them on your fork.
Click <> Code and Clone the Repo. sayls8 is the name of my GitHub, yours will obviously be different.

git clone git@github.com:sayls8/nixpkgs.git

Figure out the branch that should be used for this change by going through this section

When in doubt use master, that’s where most changes should go. This can be changed later by rebasing

Add Nixpkgs as your upstream:

cd nixpkgs

git remote add upstream https://github.com/NixOS/nixpkgs.git
# Make sure you have the latest changes from upstream Nixpkgs
git fetch upstream
# Show currently configured remote repository
git remote -v
origin  git@github.com:sayls8/nixpkgs.git (fetch)
origin  git@github.com:sayls8/nixpkgs.git (push)
upstream        https://github.com/NixOS/nixpkgs.git (fetch)
upstream        https://github.com/NixOS/nixpkgs.git (push)

Understanding Your Remotes

This output confirms that:

origin is your personal fork on GitHub (sayls8/nixpkgs.git). When you git push origin ..., your changes go here.
upstream is the official Nixpkgs repository (NixOS/nixpkgs.git). When you git fetch upstream, you’re getting the latest updates from the main project.

This setup ensures you can easily pull updates from the original project and push your contributions to your own fork.

# Shows a ton of remote branches
git branch -r | grep upstream
# Narrow it down
git branch -r | grep upstream | grep nixos-

Next Steps for Contributing

Ensure master is up to date with upstream

git checkout master
git pull upstream master
git push origin master

git pull upstream master is equivalent to running git fetch upstream followed by git merge upstream/master into your current branch (master).
git push origin master updates your forks remote with the fetched changes.

This keeps your fork in sync to avoid conflicts.

If targeting another branch, replace master with nixos-24.11 for example.

Create a Feature Branch

git checkout master
git checkout -b my-feature-branch # name should represent the feature

Make and Test Changes

Packaging Conventions

New package: Add to pkgs/by-name/<first-two-letters>/<package-name>/default.nix.

Example structure:

{ lib, stdenv, fetchFromGitHub }: stdenv.mkDerivation {
pname = "xyz"; version = "1.2.3"; src = fetchFromGitHub { ... }; ... }

Update package: Edit version and sha256 in the package’s default.nix. Use nix-prefetch-url to update hashes:

nix-prefetch-url <source-url>

Fix a bug: Modify files in pkgs/, nixos/modules/, or elsewhere.

Test locally:

Build:

nix-build -A <package-name>

Test in a shell:

nix-shell -p <package-name>

For NixOS modules:

nixos-rebuild test

Follow the Nixpkgs Contributing Guide.

Commit and Push

Commit with a clear message, make sure to follow commit conventions:

Commit Conventions

Create a commit for each logical unit.
Check for unnecessary whitespace with git diff --check before committing.
If you have commits pkg-name: oh, forgot to insert whitespace: squash commits in this case. Use git rebase -i. See Squashing Commits for additional information.
For consistency, there should not be a period at the end of the commit message’s summary line (the first line of the commit message).
When adding yourself as maintainer in the same pull request, make a separate commit with the message maintainers: add <handle>. Add the commit before those making changes to the package or module. See Nixpkgs Maintainers for details.

Format the commit messages in the following way:

(pkg-name): (from -> to | init at version | refactor | etc)

(Motivation for change. Link to release notes. Additional information.)

a) For example, for the airshipper package:

git add pkgs/by-name/ai/airshipper/
git commit -m "airshipper: init at 0.1.0"

Adds the airshipper tool for managing game assets.
Upstream homepage: https://github.com/someuser/airshipper"

b) Updating airshipper to a new version

git add pkgs/by-name/ai/airshipper/
git commit -m "airshipper: 0.1.0 -> 0.2.0

Updated airshipper to version 0.2.0. This release includes:
- Improved asset fetching logic
- Bug fixes for network errors

Release notes: https://github.com/someuser/airshipper/releases/tag/v0.2.0"

c) Fixing a bug in airshipper’s package definition

git add pkgs/by-name/ai/airshipper/
git commit -m "airshipper: fix: build with latest glibc

Resolved build failures on unstable channel due to changes in glibc.
Patched source to use updated API calls.
"

Examples:

nginx: init at 2.0.1
firefox: 122.0 -> 123.0
vim: fix build with gcc13

Push:

git push origin my-feature-branch

When you push your feature branch, it will output a link that you can follow to complete the PR on GitHub.

If you have the gh-cli set up you can also do this from the command line:

gh pr create --repo NixOS/nixpkgs --base master --head sayls8:feat/my-package

Create a Pull Request

Go to https://github.com/sayls8/nixpkgs. (your fork) Click the PR prompt for my-feature-branch. Set the base branch to NixOS/nixpkgs:master (or nixos-24.11). Write a PR description: Purpose of the change. Related issues (e.g., Fixes #1234). Testing steps (e.g., nix-build -A <package-name>). Submit and respond to feedback.

Handle Updates

For reviewer feedback or upstream changes:

Edit, commit, and push:

git add . git commit -m "<package-name>: address feedback" git push origin my-feature-branch

Rebase if needed:

git fetch upstream
git rebase upstream/master  # or upstream/nixos-24.11
git push origin my-feature-branch --force

Cleanup

After PR merge:

Delete branch:

git push origin --delete my-feature-branch

Sync master:

git checkout master
git pull upstream master
git push origin master

Addressing the Many Branches

No need to manage all branches: The nixos-branches are just metadata from upstream. You only check out the one you need (e.g., master or nixos-24.11).
Focus on relevant branches: The filter (grep nixos-) shows the key release branches. Ignore -small branches and older releases unless specifically required. Confirm latest stable: If you’re targeting a stable branch, nixos-24.11 is likely the latest (or nixos-25.05 if it’s active). Verify via NixOS status.

Local Nixpkgs

2025-11-22T00:00:00+00:00

✔️ Table of Contents

Creating and Building a Local Package within a Nixpkgs Clone

This chapter demonstrates the fundamental pattern for creating a package. Every package recipe is a file that declares a function. This function takes the packages dependencies as argument.

In this example we’ll make a simple package with coreutils and build it. Demonstrating the process of building and testing a local package.

This chapter will assume you have already have a cloned fork of Nixpkgs. I choose to clone mine to the ~/src/ directory.

You can check out the nixpkgs/pkgs/README.md Here

The Nixpkgs Contributing Guide can be found Here

Create your Package directory and a `default.nix`

For this example, we’ll create a package called testPackage and will place it in the nixpkgs/pkgs/misc directory.

cd ~/src/nixpkgs/pkgs/misc
mkdir testPackage && cd testPackage
hx default.nix

# default.nix
{
  runCommand,
  coreutils,
}:
runCommand "testPackage" {
  nativeBuildInputs = [
    coreutils
  ];
} ''

  echo 'This is a Test' > $out
''

Now we need to add our testPackage to all-packages.nix

cd pkgs/top-level
hx all-packages.nix

all-packages.nix is a centralized module that defines all available package expressions.

We’ll add our package in the list alphabetically:

# all-packages.nix
# `/msc` # editor search inside file
# Scroll down to t's
# snip ...
termusic = callPackage ../applications/autio/termusic { };

# we add our package here
testPackage = callPackage ../misc/testPackage { };

tfk8s = callPackage ../applications/misc/tfk8s { };
# snip ...

callPackage is a core utility in Nixpkgs. It takes a Nix expression (like our default.nix file, which defines a function) and automatically provides the function with any arguments it declares, by looking them up within the pkgs set (or the scope where callPackage is invoked). This means you only need to list the dependencies your package needs in its default.nix function signature, and callPackage will “inject” the correct versions of those packages. This is what the callPackage Nix Pill demonstrates at a lower level.

Understanding `pkgs/by-name/` and other locations

Nixpkgs uses different conventions for package placement:

Older categories (e.g., pkgs/misc/, pkgs/applications/): Packages within these directories typically use default.nix as their definition file (e.g., pkgs/misc/testPackage/default.nix). These packages are NOT automatically included in the top-level pkgs set; they must be This chapter will assume you have already have a cloned fork of Nixpkgs. explicitly added via a callPackage entry in pkgs/top-level/all-packages.nix. This is the method demonstrated in this chapter for our testPackage.
The new pkgs/by-name/ convention: This is the preferred location for new packages.
- Packages here are placed in a directory structure like pkgs/by-name/<first-two-letters>/<package-name>/.
- Crucially, their main definition file is named package.nix (e.g., pkgs/by-name/te/testPackage/package.nix).
- Packages placed within pkgs/by-name/ are automatically discovered and exposed by Nixpkgs’ top-level pkgs set. They do not require a manual callPackage entry in all-packages.nix. This results in a more modular and scalable approach, reducing manual maintenance.

❗ : While this example uses pkgs/misc/ to demonstrate explicit callPackage usage, when contributing a new package to Nixpkgs, you should nearly always place it within pkgs/by-name/ and name its definition file package.nix.

pkgs/by-name/README
There are some Limitations to this approach.
nixpkgs-vet

Previously, packages were manually added to all-packages.nix. While this is no longer needed in most cases, understanding the old method provides useful context for troubleshooting legacy configurations or custom integrations.

Try Building the Package

Move to the root directory of Nixpkgs:

cd ~/src/nixpkgs

Try building it:

nix-build -A testPackage
this derivation will be built:
this derivation will be built:
  /nix/store/yrbjsxmgzkl24n75sqjfxbpv5cs3b9hc-testPackage.drv
building '/nix/store/yrbjsxmgzkl24n75sqjfxbpv5cs3b9hc-testPackage.drv'...
/nix/store/3012zlv30vn6ifihr1jxbg5z3ysw0hl3-testPackage

runCommand is a simple builder, it takes 3 arguments. The first is the package name the second is the derivation attributes, and the third is the script to run.

cat ~/src/nixpkgs/result
───────┬──────────────────────────────
       │ File: result
───────┼──────────────────────────────
   1   │ This is a Test
───────┴──────────────────────────────

nix-instantiate --eval -A testPackage.meta.position
"/home/jr/src/nixpkgs/pkgs/misc/testPackage/default.nix:6"

Tools like nix search and the Nixpkgs website use the meta information for documentation and discoverability. It can also be useful for debugging and helps to provide better error messages. The above command shows that the meta.position attribute points to the file and line where the package definition begins, which is very useful for debugging.

Typically a file will have a meta attribute that looks similar to the following:

meta = with lib; {
    homepage = "https://www.openssl.org/";
    description = "A cryptographic library that implements the SSL and TLS protocols";
    license = licenses.openssl;
    platforms = platforms.all;
} // extraMeta;

For example, the following shows how Nix is able to discover different parts of your configuration:

Launch the nix repl and load your local flake:

cd /src
nix repl
nix-repl> :lf nixpkgs
nix-repl> outputs.legacyPackages.x86_64-linux.openssl.meta.position
"/nix/store/syvnmj3hhckkbncm94kfkbl76qsdqqj3-source/pkgs/development/libraries/openssl/default.nix:303"
nix-repl> builtins.unsafeGetAttrPos "description" outputs.legacyPackages.x86_64-linux.openssl.meta
{
  column = 9;
  file = "/nix/store/syvnmj3hhckkbncm94kfkbl76qsdqqj3-source/pkgs/development/libraries/openssl/default.nix";
  line = 303;
}

Lets create just the meta.description for demonstration purposes.

Adding the meta attribute

Since we don’t have a meta attribute this points to a default value that’s incorrect.

Let’s add the meta attribute and try it again:

# default.nix
{
  runCommand,
  coreutils,
}:
runCommand "testPackage" {
  nativeBuildInputs = [
    coreutils
  ];

  meta = {
    description = "test package";
};
} ''

  echo 'This is a Test' > $out
''

nix-instantiate --eval -A testPackage.meta.position
"/home/jr/src/nixpkgs/pkgs/misc/testPackage/default.nix:11"

Now it points us to the 11’th line, right where our meta.description is.

Let’s stage our package so nix recognises it:

cd ~/nixpkgs
git add pkgs/misc/testPackage/
nix edit .#testPackage

I used nix edit here to ensure it was picked up properly.

The default.nix that we’ve been working on should open in your $EDITOR

Nixpkgs Overlays

2025-11-22T00:00:00+00:00

Nixpkgs Overlays

The following is done with a local clone of Nixpkgs located at ~/src/nixpkgs.

In this example, we will create an overlay to override the version of btrfs-progs. In the root directory of our local clone of Nixpkgs (i.e.~/src/nixpkgs) we can run the following command to locate btrfs-progs within Nixpkgs:

fd 'btrfs-progs' .
./pkgs/by-name/bt/btrfs-progs/

Open the package.nix in the above directory and copy the src block within the stdenv.mkDerivation block like so:

# package.nix
  version = "6.14";

  src = fetchurl {
    url = "mirror://kernel/linux/kernel/people/kdave/btrfs-progs/btrfs-progs-v${version}.tar.xz";
    hash = "sha256-31q4BPyzbikcQq2DYfgBrR4QJBtDvTBP5Qzj355+PaE=";
  };

When we use the above src block in our overlay we’ll need to add src = self.fetchurl for our overlay to have access to fetchurl.

We will replace the version with our desired version number. To find another version that actually exists we need to check their github repos btrfs-progs Releases. I can see that the previous version was v6.13, lets try that.

cd ~/src/nixpkgs
hx overlay.nix

We will change the version to 6.13 for demonstration purposes. All that is really required is changing the version and 1 character in the hash which would cause a refetch and recalculation of the hash. We will use an empty string to follow convention:

# overlay.nix
self: super: {
  btrfs-progs = super.btrfs-progs.overrideAttrs (old: rec {
      version = "6.13";

      # Notice the `self` added here
      src = self.fetchurl {
        url = "mirror://kernel/linux/kernel/people/kdave/btrfs-progs/btrfs-progs-v${version}.tar.xz";
        hash = "";
      };
    };
  });
}

To build this with the file right from the root of the local Nixpkgs (i.e. ~/src/nixpkgs) you could run the following. Running the command this way avoids the impurity of looking it up in the ~/.config directory:

nix-build -A btrfs-progs --arg overlays '[ (import ./overlay.nix) ]'

The compiler will give you back the correct hash:

specified: sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=
got:    sha256-ZbPyERellPgAE7QyYg7sxqfisMBeq5cTb/UGx01z7po=

Replace the empty hash with the new hash value we just got from the compiler so the overlay.nix would look like this:

self: super: {
  btrfs-progs = super.btrfs-progs.overrideAttrs (old: rec {
    version = "6.13";

    src = self.fetchurl {
      url = "mirror://kernel/linux/kernel/people/kdave/btrfs-progs/btrfs-progs-v${version}.tar.xz";
      hash = "sha256-ZbPyERellPgAE7QyYg7sxqfisMBeq5cTb/UGx01z7po=";
    };
  });
}

Try building it again:

nix-build -A btrfs-progs --arg overlays '[ (import ./overlay.nix) ]'
checking for references to /build/ in /nix/store/szd6lizahidjniz85a0g1wsrfknirhwb-btrfs-progs-6.13...
gzipping man pages under /nix/store/szd6lizahidjniz85a0g1wsrfknirhwb-btrfs-progs-6.13/share/man/
patching script interpreter paths in /nix/store/szd6lizahidjniz85a0g1wsrfknirhwb-btrfs-progs-6.13
/nix/store/szd6lizahidjniz85a0g1wsrfknirhwb-btrfs-progs-6.13/bin/fsck.btrfs: interpreter directive changed from "#!/bin/sh -f" to "/nix/store/xy4jjgw87sbgwylm5kn047d9gkbhsr9x-bash-5.2p37/bin/sh -f"
stripping (with command strip and flags -S -p) in  /nix/store/szd6lizahidjniz85a0g1wsrfknirhwb-btrfs-progs-6.13/lib /nix/store/szd6lizahidjniz85a0g1wsrfknirhwb-btrfs-progs-6.13/bin
/nix/store/szd6lizahidjniz85a0g1wsrfknirhwb-btrfs-progs-6.13

We can inspect it with the repl:

cd ~/src/nixpkgs
nix repl
nix-repl> :a import ./. { overlays = [ (import ./overlay.nix) ]; }
nix-repl> btrfs-progs
«derivation /nix/store/6yxhj84cwcsnrd87rcxbd6w08l9ikc6p-btrfs-progs-6.13.drv»
nix-repl> btrfs-progs.drvAttrs.buildInputs
[
  «derivation /nix/store/yg4llzkcla5rppv8r1iikyamfxg3g4sg-acl-2.3.2.drv»
  «derivation /nix/store/vqczbcwjnid6bs4cv3skl7kyd6kkzcfx-attr-2.5.2.drv»
  «derivation /nix/store/xrvx0azszpdh2x0lnldakqx25vfxab19-e2fsprogs-1.47.2.drv»
  «derivation /nix/store/iil4b8adk615zhp6wmzjx16z1v2f8f4j-util-linux-minimal-2.41.drv»
  «derivation /nix/store/wwld8wp91m26wz69gp8vzh090sh5ygxd-lzo-2.10.drv»
  «derivation /nix/store/w4ncw24gdfkbx9779xpgjli5sagi506m-systemd-minimal-libs-257.5.drv»
  «derivation /nix/store/dmh4lvmq6n8hy56q93kplvnfnlwqzzv5-zlib-1.3.1.drv»
  «derivation /nix/store/h8iwhnr636dwb72qqcyzp111ajjxgzr2-zstd-1.5.7.drv»
]
nix-repl> btrfs-progs.drvAttrs.version
"6.13"
nix-repl> btrfs-progs.drvAttrs.src
«derivation /nix/store/y5nkz1xczxha4xl93qq3adndyc46dcvf-btrfs-progs-v6.13.tar.xz.drv»

Using :a adds the attributes from the resulting set into scope and avoids bringing the entire nixpkgs set into scope.

To see whats available, you can for example type btrfs-progs.drvAttrs. then hit TAB.

Another way to do this is to move our overlay to the ~/.config/nixpkgs/overlays directory and rename the file like the following, agian this adds an impurity because it relies on your ~/.config directory which is different from user to user:

mv overlay.nix ~/.config/nixpkgs/overlays/btrfs-progs.nix
cd ~/src/nixpkgs
nix-build -A btrfs-progs
checking for references to /build/ in /nix/store/szd6lizahidjniz85a0g1wsrfknirhwb-btrfs-progs-6.13...
gzipping man pages under /nix/store/szd6lizahidjniz85a0g1wsrfknirhwb-btrfs-progs-6.13/share/man/
patching script interpreter paths in /nix/store/szd6lizahidjniz85a0g1wsrfknirhwb-btrfs-progs-6.13
/nix/store/szd6lizahidjniz85a0g1wsrfknirhwb-btrfs-progs-6.13/bin/fsck.btrfs: interpreter directive changed from "#!/bin/sh -f" to "/nix/store/xy4jjgw87sbgwylm5kn047d9gkbhsr9x-bash-5.2p37/bin/sh -f"
stripping (with command strip and flags -S -p) in  /nix/store/szd6lizahidjniz85a0g1wsrfknirhwb-btrfs-progs-6.13/lib /nix/store/szd6lizahidjniz85a0g1wsrfknirhwb-btrfs-progs-6.13/bin
/nix/store/szd6lizahidjniz85a0g1wsrfknirhwb-btrfs-progs-6.13

Overlays with Flakes

In a flake, overlays are defined in the outputs.overlays attribute set of the flake.nix.

They are then applied to nixpkgs inputs using inputs.nixpkgs.follows = "nixpkgs"; (or similar) and the overlays attribute on the input.

Example of flake usage:

# flake.nix
{
  description = "My NixOS flake with custom overlays";

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

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

    overlays.myCustomOverlay = final: prev: {
      btrfs-progs = prev.btrfs-progs.overrideAttrs (old: rec {
        version = "6.13";
        src = self.fetchurl {
          url = "mirror://kernel/linux/kernel/people/kdave/btrfs-progs/btrfs-progs-v${version}.tar.xz";
          hash = "sha256-ZbPyERellPgAE7QyYg7sxqfisMBeq5cTb/UGx01z7po=";
        };
      });
    };

    nixosConfigurations.my-system = nixpkgs.lib.nixosSystem {
      system = "x86_64-linux";
      modules = [
        # Apply the overlay
        { nixpkgs.overlays = [ self.overlays.myCustomOverlay ]; }
        ./configuration.nix
      ];
    };
  };
}

nix flake show
path:/home/jr/btrfs-progs?lastModified=1749655369&narHash=sha256-ln6dLiqo7TxStQSXgcIwfbdt7STGw4ZHftZRfWpY/JQ%3D
├───nixosConfigurations
│   └───my-system: NixOS configuration
└───overlays
    └───myCustomOverlay: Nixpkgs overlay

Debugging NixOS modules

2025-11-22T00:00:00+00:00

Chapter 11

This chapter covers debugging NixOS modules, focusing on tracing module options and evaluating merges.

✔️ Click to Expand Table of Contents

Debugging and Tracing NixOS Modules

Other related post if you haven’t read my previous post on modules, that may be helpful before reading this one:
- nix-modules-explained
- This post is my notes following Nix Hour 40. If it seems a little chaotic, try watching one. They are hard to follow if you’re not extremely familiar with the concepts.
- Nix Hour 40

Nix Code is particularly hard to debug because of (e.g. lazy evaluation, declarative nature, layered modules)

The following simple Nix code snippet illustrates a basic NixOS module definition and how options are declared and configured. We’ll use this example to demonstrate fundamental debugging techniques using nix-instantiate.

let
  lib = import <nixpkgs/lib>;
in
lib.evalModules {
  modules = [
    ({ lib, ... }: {
      options.foo = lib.mkOption {
        # type = lib.types.raw;
        type = lib.types.anything;
        # default = pkgs;
      };
      config.foo = {
        bar = 10;
        list = [1 2 3 ];
        baz = lib.mkDefault "baz";
      };
    })
    {
      foo.baz = "bar";
    }
  ];
}

In the above code, adding lib to the function arguments isn’t required but if you were to move the module to another file it would fail without it because lib comes from outside of it. So it’s good practice to refer to lib in the modules themselves.
You should always assign a type to your options, if you don’t know which type to use you could use raw. raw is a type that doesn’t do any processing. So if you were to assign the entire packages set to the option e.g. default = pkgs; it wouldn’t recurseinto all the packages and try to evaluate them. There is also anything, that is useful if you do want to recurse into the values.
The following is an example of how you would run this inside vim/neovim, the rest of the examples will be from the command line:

:!nix-instantiate --eval -A config.foo --strict

Output:

Click to Expand the Output

{ bar = 10; baz = "bar"; list = [ 1 2 3 ]; }

To show the difference you could uncomment the raw type and comment the anything type and run the above command again you’ll see that you get an error:

error: The option 'foo' is defined multiple times while it's expected to be
unique

To execute this command on the command line:

nix-instantiate --eval --strict -A config.foo

It will show you the start of a trace. To get the full trace add:

nix-instantiate --eval --strict -A config.foo --show-trace

Example 2

Click to Expand Example 2

In the previous example, we looked at a simplified module. Now, let’s examine a more realistic scenario involving a basic NixOS configuration file (configuration.nix).

This example will demonstrate how to use nix-instantiate to evaluate an entire system configuration and how --show-trace helps in diagnosing errors within this context.

Consider the following configuration.nix file:

# configuration.nix
{ lib, ... }: {
  boot.loader.grub.device = "nodev";
  fileSystems."/".device = "/devst";
  system.stateVersion = "24.11";
}

This configuration snippet sets the GRUB bootloader device, defines a root filesystem, and specifies the expected NixOS state version. To evaluate this entire system configuration, you can use nix-instantiate and point it to the <nixpkgs/nixos> entrypoint, providing our configuration.nix file as an argument. The -A system flag selects the top-level system attribute, which represents the instantiated system configuration.

Run it in with:

nix-instantiate '<nixpkgs/nixos>' --arg configuration ./configuration.nix -A system

Output:

/nix/store/kfcwvvpdbsb3xcks1s76id16i1mc3l5k-nixos-system-nixos-25.05pre-git.drv

Ok, we can see that this successfully instantiates. Let’s introduce an error to trace:

{ lib, ... }: {
  boot.loader.grub.device = "nodev";
  fileSystems."/".device = "/devst";
  system.stateVersion = builtins.genList "24.11" null;
}

Output:

(stack trace truncated; use '--show-trace' to show the full, detailed trace)
error: expected an integer but found null: null

Rerun the command with --show-trace appended:

Or on the command line

nix-instantiate '<nixpkgs/nixos>' --arg configuration ./configuration.nix -A system --show-trace

This outputs a much longer trace than the first example. It shows you the file the error occured in and you can see that in this case they are a lot of internal functions. (e.g. at /nix/store/ccfwxygjrarahgfv5865x2f828sjr5h0- source/lib/attrsets.nix:1529:14:)

To show your own error message you could do something like this:

{lib, ...}: {
  boot.loader.grub.device = "nodev";
  fileSystems."/".device = "/devst";
  system.stateVersion = builtins.addErrorContext "AAAAAAAAAAAAAAAAA" (builtins.genList "24.11" null);
}

Run it:

nix-instantiate '<nixpkgs/nixos>' --arg configuration ./configuration.nix -A system --show-trace`

Output:

 … while evaluating the attribute 'value'
     at /nix/store/ccfwxygjrarahgfv5865x2f828sjr5h0-source/lib/modules.nix:770:21:
      769|             inherit (module) file;
      770|             inherit value;
         |                     ^
      771|           }) module.config

   … AAAAAAAAAAAAAAAAA

   … while calling the 'genList' builtin
     at /home/jr/tests/configuration.nix:4:71:
        3|   fileSystems."/".device = "/devst";
        4|   system.stateVersion = builtins.addErrorContext "AAAAAAAAAAAAAAAAA"
         (builtins.genList "24.11" null);
         |                                                                       ^
        5| }

   … while evaluating the second argument passed to builtins.genList

   error: expected an integer but found null: null

In the latest nix they actually inverted the error messages so the most relevant parts will be at the bottom.

Example 3

Click to Expand Example 3

Let’s consider another example, this time demonstrating the definition of configuration options using lib.mkOption within a module structure.

# default.nix
let
  lib = import <nixpkgs/lib>;
in
lib.evalModules {
  modules = [
    ({ lib, ... }: {
      options.ints = lib.mkOption {
        type = lib.types.attrsOf lib.types.int;
      };
      options.strings = lib.mkOption {
        type = lib.types.string;
        # type = lib.types.attrsOf lib.types.string;
        default = "foo";
      };
    })
  ];
}

Instantiate this with:

nix-instantiate --eval --strict -A config.strings

Output:

evaluation warning: The type `types.string` is deprecated.
See https://github.com/NixOS/nixpkgs/pull/66346 for better alternative types.
"foo"

Unfortunately you won’t get the same depreciation warning from lib.attrsOf

Below is an interesting way to provide nixpkgs run it on the command line:

export NIX_PATH=nixpkgs=channel:nixpkgs-unstable
echo $NIX_PATH

Output:

nixpkgs=channel:nixpkgs-unstable

The next two commands are to check that after using the above way to provide nixpkgs-unstable that they both point to the same store path, the following command will fetch nixpkgs from the channel above:

nix-instantiate --find-file nixpkgs

Output 1️⃣

/nix/store/ydrgwsibghsyx884qz97zbs1xs93yk11-source

nix-instantiate --eval channel:nixpkgs-unstable -A path

Output: 2️⃣

/nix/store/ydrgwsibghsyx884qz97zbs1xs93yk11-source

As you can see both commands produce the same store path

Example 4

In our previous example, we encountered a deprecation warning for lib.types.string. This next example delves deeper into why that type was deprecated and demonstrates the consequences of its behavior, along with the recommended fix.

# default.nix
let
  lib = import <nixpkgs/lib>;
in
  lib.evalModules {
    modules = [
      ({lib, ...}: {
        options.ints = lib.mkOption {
          type = lib.types.attrsOf lib.types.int;
        };
        options.strings = lib.mkOption {
          # type = lib.types.string;
          type = lib.types.attrsOf lib.types.string;
          default = {
            x = "foo";
          };
        };
        config = {
          strings = lib.mkOptionDefault {
            x = "bar";
          };
        };
      })
    ];
  }

Evaluate it with:

nix-instantiate --eval --strict -A config.strings

types.string depricated because it silently concatenates strings
The above command has two options with the same priority level and evaluates to { x = "foobar"; }

Output:

evaluation warning: The type `types.string` is deprecated. See https://github.
com/NixOS/nixpkgs/pull/66346 for better alternative types.
{ x = "foobar"; }

types.str was the replacement for the depricated types.string:

# default.nix
let
  lib = import <nixpkgs/lib>;
in
  lib.evalModules {
    modules = [
      ({lib, ...}: {
        options.ints = lib.mkOption {
          type = lib.types.attrsOf lib.types.int;
        };
        options.strings = lib.mkOption {
          # type = lib.types.string;
          type = lib.types.attrsOf lib.types.str;
          # Sets the value with a lower priority: lib.mkOptionDefault
          default = {
            x = "foo";
          };
        };
        config = {
          strings = lib.mkOptionDefault {
            x = "bar";
          };
        };
      })
    ];
  }

Output:

error:
… while evaluating the attribute 'x'

… while evaluating the attribute 'value'
 at /nix/store/ydrgwsibghsyx884qz97zbs1xs93yk11-source/lib/modules.nix:1148:41:
 1147|
 1148|     optionalValue = if isDefined then { value = mergedValue; } else { };
     |                                         ^
 1149|   };

… while calling the 'foldl'' builtin
 at /nix/store/ydrgwsibghsyx884qz97zbs1xs93yk11-source/lib/options.nix:508:8:
  507|     else
  508|       (foldl' (
     |        ^
  509|         first: def:

(stack trace truncated; use '--show-trace' to show the full, detailed trace)

error: The option `strings.x' has conflicting definition values:
- In `<unknown-file>': "foo"
- In `<unknown-file>': "bar"
Use `lib.mkForce value` or `lib.mkDefault value` to change the priority on any of these definitions.

shell returned 1

Summary

So types in the module system aren’t just types in the conventional sense but they also specify the emerging behavior of these values.
If we switch the type in the above example to types.lines you get this returned, { x = "foo\nbar"; }
mkOptionDefault isn’t typically something you should generally use, instead options have a default setting
If you want to make sure that you set a default but if the user specifies it, it shouldn’t get overridden. You should not set it in the following:

options.strings = lib.mkOption {
  type = lib.types.attrsOf lib.types.lines;
  default = {
    x = "foo";
  };
}

Because the above uses mkOptionDefault but instead in under the config attribute like the following:

# ...snip...
options.strings = lib.mkOption {
  type = lib.types.attrsOf lib.types.lines;
  # default = {
    # x = "foo";
  # };
};
config = {
  strings = {
    x = lib.mkDefault "foo";
  };
};
# ...snip...

let
  lib = import <nixpkgs/lib>;
in
  lib.evalModules {
    modules = [
      ({lib, ...}: {
        options.ints = lib.mkOption {
          type = lib.types.attrsOf lib.types.int;
        };
        options.strings = lib.mkOption {
          # type = lib.types.string;
          type = lib.types.attrsOf lib.types.str;
          # Sets the value with a lower priority: lib.mkOptionDefault
          #default = {
          #  x = "foo";
          #};
        };
        config.strings = {
          x = "foo";
        };
      })
      {
        config.strings = {
          y = "bar";
        };
      }
    ];
  }

Output:

This works now because there’s no difference between x and y

{ x = "foo"; y = "bar"; }

More Functionality between modules

let
  lib = import <nixpkgs/lib>;
in
  lib.evalModules {
    modules = [
      ({lib, ...}: {
        options.ints = lib.mkOption {
          type = lib.types.attrsOf lib.types.int;
        };
        options.strings = lib.mkOption {
          # type = lib.types.string;
          type = lib.types.attrsOf lib.types.str;
          # Sets the value with a lower priority: lib.mkOptionDefault
          #default = {
          #  x = "foo";
          #};
        };
        config.strings = {
          x = lib.mkDefault "foo";
        };
      })
      {
        config.strings = {
          x = "x";
          y = "bar";
        };
      }
    ];
  }

The above command would cause a conflict without the x = lib.mkDefault foo And this is typically what you want to do for defaults and modules in things like nested configuration.

Output:

{ x = "x"; y = "bar"; }

Infinite recursion error

A common pitfall is to introduce a hard to debug error infinite recursion when shadowing a name. The simplest example for this is:

let a = 1; in rec { a = a; }

💡TIP: Avoid rec. Use let ... in Example:
let
 a = 1;
in {
 a = a;
 b = a + 2;
}

Click to Expand a more involved infinite recursion error

We’ll separate the logic for this example, this will be the default.nix this is where having lib defined in your inline modules is helpful because you can just delete the section and paste it into your modules.nix:

# default.nix
let
  lib = import <nixpkgs/lib>;
in
  lib.evalModules {
    modules = [
      ./module.nix
    ];
  }

And in the module.nix:

# module.nix
{ lib, pkgs, ...}: {
  options.etc = lib.mkOption {
    type = lib.types.attrsOf lib.types.path;
    default = { };
    description = ''
      Specifies which paths are is /etc/
    '';
  };

  config._module.args.pkgs = import <nixpkgs> {
    config = {};
    overlays = [];
  };
  config.etc.foo = pkgs.writeText "foo" ''
    foo configuration
  '';
}

If you evaluate this with the following you will get an infinite recursion error.

nix-instantiate --eval --strict -A config.etc

This happens because --strict evaluates the etc, then it goes into the attrsOf, and the path

nix repl
nix-repl> :l <nixpkgs>
nix-repl> hello.out.out.out

In this example:

:l <nixpkgs> loads the Nixpkgs library into the repl environment, making its definitions available.
hello refers to the hello package definition within Nixpkgs. Packages in Nixpkgs are defined as derivations.
.out is a common attribute name for the main output of a derivation (e.g., the installed package). Some packages, especially those with complex build processes or multiple outputs, might have nested output attributes. In the case of hello, accessing .out.out.out ultimately leads us to the derivation itself.

The key takeaway here is that when you evaluate a package in the nix repl, you’re often interacting with its derivation or one of its output paths in the Nix store. The «derivation ...» indicates that hello.out.out.out evaluates to a derivation – the blueprint for building the hello package. This is in contrast to --eval --strict, which tries to fully evaluate values, potentially leading to infinite recursion if it encounters a derivation that refers back to itself indirectly during attribute evaluation.

Output:

«derivation /nix/store/b1vcpm321dwbwx6wj4n13l35f4y2wrfv-hello-2.12.1.drv»

So it recurses through the entire thing and tries to evaluate its string.

So we want to change the command from --eval --strict which is only based on evaluation to at least nix-instantiate which is based on derivations:

nix-instantiate -A config.etc

Output:

warning: you did not specify '--add-root'; the result might be removed by the garbage collector
/nix/store/abyfp1rxk73p0n5kfilv7pawxwvc7hsg-foo.drv

We don’t really have a derivation yet for example:

# module.nix
{
  lib,
  pkgs,
  ...
}: {
  options.etc = lib.mkOption {
    type = lib.types.attrsOf (lib.types.attrsOf lib.types.path);
    default = {};
    description = ''
      Specifies which paths are in /etc/
    '';
  };

  config._module.args.pkgs = import <nixpkgs> {
    config = {};
    overlays = [];
  };
  config.etc.foo.bar = pkgs.writeText "foo" ''
    foo configuration
  '';
}

Try to evaluate the above command with nix-instantiate -A config.etc and Nix doesn’t even try to build it. With nested attrsOf

nix repl -f default.nix
nix-repl> config.etc
{
  foo = { ... };
}
nix-repl> config.etc.foo
{
  bar = «derivation /nix/store/abyfp1rxk73p0n5kfilv7pawxwvc7hsg-foo.drv»;
}

So config.foo is an attribute set and config.etc.foo is also an attribute set but it’s not a derivation by itself. So nix-instantiate does this one level of recursion here and it would have built foo value if it were a derivation.

Example 5

Click to Expand Example 5

We’ll use the same module.nix and default.nix from the previous example.

Building More Complex Configurations with Modules In this next example, we’ll focus on a common task in system configuration: managing files within the /etc/ directory. We’ll define a module that allows us to specify the content of arbitrary files in /etc/ and then use a special Nix function to combine these individual file definitions into a single, manageable entity.

We’ll introduce a new option, options.etc, which will allow us to define the content of files within /etc/. Then, we’ll use pkgs.linkFarm to create a derivation that represents the entire /etc/ directory as a collection of symbolic links pointing to the individual file contents we’ve defined. This demonstrates how modules can abstract away the details of creating complex system configurations, providing a declarative and reproducible way to manage even fundamental aspects of the operating system.

Let’s show how we can use Nix modules to declaratively manage the /etc/ directory

# default.nix
let
  lib = import <nixpkgs/lib>;
in
  lib.evalModules {
    modules = [
      ./module.nix
    ];
  }

# module.nix
{
  lib,
  pkgs,
  config,
  ...
}: {
  options.etc = lib.mkOption {
    type = lib.types.attrsOf (lib.types.attrsOf lib.types.path);
    default = {};
    description = ''
      Specifies which paths are in /etc/
    '';
  };
  options.etcCombined = lib.mkOption {
    type = lib.types.package;
    default =
      pkgs.linkFarm "etc"
      (lib.mapAttrsToList (name: value: {
        name = name;
        path = value;
      }) config.etc);
  };

  config._module.args.pkgs = import <nixpkgs> {
    config = {};
    overlays = [];
  };
  config.etc.foo = pkgs.writeText "foo" ''
    foo configuration
  '';
  config.etc.bar = pkgs.writeText "bar" ''
    bar configuration
  '';
}

Run it with:

nix-instantiate -A config.etcCombined

Output:

/nix/store/3da61nmfk546qn2zpxsm57mq6vz6fjx8-etc.drv

So we can see that it will instantiate, lets see if it will build:

nix-build -A config.etcCombined

Output:

these 3 derivations will be built:
/nix/store/41yfxq4af1vrs0rrgfk5gc36kmjc7270-bar.drv
/nix/store/abyfp1rxk73p0n5kfilv7pawxwvc7hsg-foo.drv
/nix/store/3da61nmfk546qn2zpxsm57mq6vz6fjx8-etc.drv
building '/nix/store/41yfxq4af1vrs0rrgfk5gc36kmjc7270-bar.drv'...
building '/nix/store/abyfp1rxk73p0n5kfilv7pawxwvc7hsg-foo.drv'...
building '/nix/store/3da61nmfk546qn2zpxsm57mq6vz6fjx8-etc.drv'...
/nix/store/ca3wyk5m3qhy8n1nbn0181m29qvp1klp-etc

nix-build -A config.etcCombined && ls result/ -laa

Output:

/nix/store/ca3wyk5m3qhy8n1nbn0181m29qvp1klp-etc
dr-xr-xr-x - root 31 Dec  1969  .
drwxrwxr-t - root 16 May 15:13  ..
lrwxrwxrwx - root 31 Dec  1969  bar -> /nix/store/1fsjyc2hmilab1qw6jfkf6cb767kz858-bar
lrwxrwxrwx - root 31 Dec  1969  foo -> /nix/store/wai5dycp0zx1lxg0rhpdxnydhiadpk05-foo

We can see that foo and bar link to different derivations
When trying to figure out which default to use for etcCombined infinisil went to the Nixpkgs Reference Manual. Make sure to go to the correct version.
- 24.11pre-git
- 25.05pre-git (i.e. unstable)
- Once at the website press Ctrl+f and type symlinkjoin and hit enter.

Or in your local copy of Nixpkgs you could go to nixpkgs/pkgs/build-support/ trivial-builders/default.nix. Then use your editors search feature, with nvim and helix you press /symlinkjoin or /linkFarm hit enter then press n to cycle to the next match. It will bring you to comments and up to date information.

# linkFarm "myexample" [ { name = "hello-test"; path = pkgs.hello; }
# { name = "foobar"; path = pkgs.stack; } ]

Tests

Click to Expand Test Example

How to create a Derivation with passthru.tests outside of Nixpkgs and then run tests available to your package set?

mkdir passthru-tests && cd passthru-tests

Create a default.nix with the following:

# default.nix
let
  pkgs = import <nixpkgs> {};

  package = pkgs.runCommand "foo" {
    passthru.tests.simple = pkgs.runCommand "foo-test" {} ''
      if [[ "$(cat ${package})" != "foo" ]]; then
        echo "Result is not foo"
        exit 1
      fi
      touch $out
  '';
  } ''
    echo foo > $out
  '';
in
package

See if it will build:

nix-build

Try running the test:

nix-build -A passthru.tests

this derivation will be built:
/nix/store/pqpqq9x1wnsabzbsb52z4g4y4zy6p7yx-foo-test.drv
building '/nix/store/pqpqq9x1wnsabzbsb52z4g4y4zy6p7yx-foo-test.drv'...
/nix/store/7bbw2ban0mgkh4d59yz3cnai4aavwvb6-foo-test

Test 2

passthru.tests is the convention for defining tests associated with a derivation. The attributes in passthru are preserved and accessible after the derivation is built.

let
  pkgs = import <nixpkgs> {};

  package =
    pkgs.runCommand "foo" {
      passthru.tests.simple = pkgs.runCommand "foo-test" {} ''
        if [[ "$(cat ${package})" != "foo" ]]; then
          echo "Result is not foo"
          exit 1
        fi
        touch $out
      '';

      passthru.tests.version = pkgs.testers.testVersion {
         package = package;
         version = "1.2";
     };

      # pkgs.writeShellApplication
      script = ''
        #!${pkgs.runtimeShell}
        echo "1.2"
      '';
      passAsFiles = [ "script" ];

    } ''
      cp "$scriptPath" "$out"
    '';
in
  package

Try to build it:

nix-build -A passthru.tests

testers.testVersion checks if an executable outputs a specific version string.
nix-build -A passthru.tests specifically targets the derivations defined within the tests attribute of the main derivation.

these 3 derivations will be built:
  /nix/store/lyz86bd78p7f3yjy1qky6annmggymcwd-foo.drv
  /nix/store/s4iawjy5zpv89dbkc3zz7z3ngz4jq2cv-foo-test.drv
  /nix/store/z3gi4pb8jn2h9rvk4dhba85fiphp5g4z-foo-test-version.drv
building '/nix/store/lyz86bd78p7f3yjy1qky6annmggymcwd-foo.drv'...
cp: cannot stat '': No such file or directory
error: builder for '/nix/store/lyz86bd78p7f3yjy1qky6annmggymcwd-foo.drv'
 failed with exit code 1;
     last 1 log lines:
     > cp: cannot stat '': No such file or directory
     For full logs, run:
       nix log /nix/store/lyz86bd78p7f3yjy1qky6annmggymcwd-foo.drv
error: 1 dependencies of derivation '/nix/store/z3gi4pb8jn2h9rvk4dhba85fiphp5g4z
-foo-test-version.drv' failed to build
error: build of '/nix/store/s4iawjy5zpv89dbkc3zz7z3ngz4jq2cv-foo-test.drv',
 '/nix/store/z3gi4pb8jn2h9rvk4dhba85fiphp5g4z-foo-test-version.drv' failed

Run nix-build with no arguments:

nix-build

nix derivation show /nix/store/lyz86bd78p7f3yjy1qky6annmggymcwd-foo.drv | jq '.[].env'

Output:

{
  "__structuredAttrs": "",
  "buildCommand": "cp \"$scriptPath\" \"$out\"\n",
  "buildInputs": "",
  "builder": "/nix/store/xg75pc4yyfd5n2fimhb98ps910q5lm5n-bash-5.2p37/bin/bash",
  "cmakeFlags": "",
  "configureFlags": "",
  "depsBuildBuild": "",
  "depsBuildBuildPropagated": "",
  "depsBuildTarget": "",
  "depsBuildTargetPropagated": "",
  "depsHostHost": "",
  "depsHostHostPropagated": "",
  "depsTargetTarget": "",
  "depsTargetTargetPropagated": "",
  "doCheck": "",
  "doInstallCheck": "",
  "enableParallelBuilding": "1",
  "enableParallelChecking": "1",
  "enableParallelInstalling": "1",
  "mesonFlags": "",
  "name": "foo",
  "nativeBuildInputs": "",
  "out": "/nix/store/9mcrnddb6lf1md14v4lj6s089i99l5k7-foo",
  "outputs": "out",
  "passAsFile": "buildCommand",
  "passAsFiles": "script",
  "patches": "",
  "propagatedBuildInputs": "",
  "propagatedNativeBuildInputs": "",
  "script": "#!/nix/store/xg75pc4yyfd5n2fimhb98ps910q5lm5n-bash-5.2p37/bin/bash\necho \"1.2\"\n",
  "stdenv": "/nix/store/lgydi1gl5wqcw6k4gyjbaxx7b40zxrsp-stdenv-linux",
  "strictDeps": "",
  "system": "x86_64-linux"
}

nix derivation show /nix/store/lyz86bd78p7f3yjy1qky6annmggymcwd-foo.drv | jq
 '.[].env.buildCommand'

Output:

"cp \"$scriptPath\" \"$out\"\n"

raw mode below

nix derivation show /nix/store/lyz86bd78p7f3yjy1qky6annmggymcwd-foo.drv | jq
 '.[].env.buildCommand' -r

Output:

cp "$scriptPath" "$out"

It turns out the correct command was passAsFile not passAsFiles but that change wasn’t enough to fix it. passAsFiles expects a list of files, not a single file path. Running nix-build -A passthru.tests failed saying > foo --version returned a non-zero exit code.

let
  pkgs = import <nixpkgs> {};

  package =
    pkgs.runCommand "foo" {
      #passthru.tests.simple = pkgs.runCommand "foo-test" {} ''
      #  if [[ "$(cat ${package})" != "foo" ]]; then
      #    echo "Result is not foo"
      #    exit 1
      #  fi
      #  touch $out
      #'';

      passthru.tests.version = pkgs.testers.testVersion {
        package = package;
        version = "1.2";
      };

      # pkgs.writeShellApplication
      script = ''
        #!${pkgs.runtimeShell}
        echo "1.2"
      '';
      passAsFile = ["script"];
    } ''
      mkdir -p "$out/bin"
      cp "$scriptPath" "$out/bin/foo"
      chmod +x "$out/bin/foo"
    '';
in
  package

Build it:

nix-build -A passthru.tests

Output:

these 2 derivations will be built:
  /nix/store/lqrlcd64dmpzkggcfzlnsnwjd339czd3-foo.drv
  /nix/store/c3kw4xbdlrig08jrdm5wis1dmv2gnqsd-foo-test-version.drv
building '/nix/store/lqrlcd64dmpzkggcfzlnsnwjd339czd3-foo.drv'...
building '/nix/store/c3kw4xbdlrig08jrdm5wis1dmv2gnqsd-foo-test-version.drv'...
1.2
/nix/store/zsbk5zawak68ailvkwi2gad2bqbqmdz9-foo-test-version

Key Takeaways for Debugging NixOS Modules

nix-instantiate is Your Friend: Use nix-instantiate to evaluate your NixOS modules and pinpoint errors.
Unlock Details with --show-trace: When errors occur, always append --show-trace to get a comprehensive stack trace, revealing the origin of the problem. Remember that in newer Nix versions, the most relevant parts of the trace are often at the bottom.
Understand Option Types: Nix option types (raw, anything, string/str, lines, attrsOf) are not just about data types; they also dictate how values are merged and processed within the module system.
Be Mindful of mkOptionDefault: While useful in specific scenarios, mkOptionDefault sets a lower priority default. For standard defaults that can be overridden by user configuration, define them directly within the config attribute using lib.mkDefault.
Use builtins.addErrorContext: Enhance your custom error messages by providing specific context relevant to your module’s logic using builtins.addErrorContext.
Derivations vs. Evaluation: Be aware of the difference between evaluating expressions (--eval --strict) and instantiating derivations (nix-instantiate). Strict evaluation can trigger infinite recursion if it encounters unevaluated derivations with cyclic dependencies during attribute access.
Explore with nix repl: The nix repl allows you to interactively explore Nix expressions and the outputs of derivations, providing insights into the structure and values within Nixpkgs.

Conclusion

This chapter has equipped you with essential techniques for debugging and tracing NixOS modules. We’ve explored how to use nix-instantiate and --show-trace to pinpoint errors, how to interpret Nix’s often-verbose error messages, and how to leverage the nix repl for interactive exploration. Understanding option types and the nuances of mkOptionDefault is crucial for writing robust and predictable modules. We’ve also touched upon the distinction between evaluation and instantiation, and how that impacts debugging.

While these tools and techniques are invaluable for understanding and troubleshooting your own Nix configurations, they also become essential when you want to contribute to or modify the vast collection of packages and modules within Nixpkgs itself. Nixpkgs is where the majority of Nix packages and NixOS modules reside, and learning how to navigate and contribute to it opens up a whole new level of control and customization within the Nix ecosystem.

In the next chapter, Working with Nixpkgs Locally, we’ll shift our focus to exploring and modifying Nixpkgs. We’ll cover how to clone Nixpkgs, how to make changes to package definitions, and how to test those changes locally before contributing them back upstream. This chapter will empower you to not just use existing Nix packages, but also to customize and extend them to fit your specific needs.

Nix Module System Explained

2025-11-21T00:00:00+00:00

Chapter 3

✔️ Click to Expand Table of Contents

Nix Module System Explained

TL;DR: In this chapter, we will break down the Nix module system used by both NixOS and Home-Manager. We will discuss using home-manager as a module and the flexibility that modules give us. We will touch on options and break down the vim module from the Nixpkgs collection. Finally we will display how to test modules with the repl.

Your configuration.nix is a module. For the Nixpkgs collection most modules are in nixos/modules.

The suggested way of using home-manager according to their manual is as a NixOS module. Both home-manager and NixOS use the same module system.

Module Structure

{
  imports = [
    # Paths to other modules.
    # Compose this module out of smaller ones.
  ];

  options = {
    # Option declarations.
    # Declare what settings a user of this module can set.
    # Usually this includes a global "enable" option which defaults to false.
  };

  config = {
    # Option definitions.
    # Define what other settings, services and resources should be active.
    # Usually these depend on whether a user of this module chose to "enable" it
    # using the "option" above.
    # Options for modules imported in "imports" can be set here.
  };
}

imports, options, and config are the top-level attributes of a Nix module. They are the primary, reserved keys that the Nix module system recognizes and processes to combine different configurations into a single, cohesive system or user environment. config is the same config you receive as a module argument (e.g. { pkgs, config, ... }: at the top of your module function)

Understanding config:

config is the big constantly updated blueprint of your entire system.

Every time you bring in a new module, it adds its own settings and options to this blueprint. So, when a module receives the config argument, it’s getting the complete picture of everything you’ve asked NixOS to set up so far.

This allows the module to:

See what other parts of your system are doing.
Make smart decisions based on those settings.
Add its own pieces to the overall plan, building on what’s already there.
Most modules are functions that take an attribute set and return an attribute set.

To turn the above module into a function accepting an attribute set just add the function arguments to the top, click the eye to see the whole module:

{ config, pkgs, ... }:
~ {
~   imports = [
~     # Paths to other modules.
~     # Compose this module out of smaller ones.
~   ];
~
~   options = {
~     # Option declarations.
~     # Declare what settings a user of this module can set.
~     # Usually this includes a global "enable" option which defaults to false.
~   };
~
~   config = {
~     # Option definitions.
~     # Define what other settings, services and resources should be active.
~     # Usually these depend on whether a user of this module chose to "enable" it
~     # using the "option" above.
~     # Options for modules imported in "imports" can be set here.
~   };
~ }

It may require the attribute set to contain:

config: The configuration of the entire system.
options: All option declarations refined with all definition and declaration references.
pkgs: The attribute set extracted from the Nix package collection and enhanced with the nixpkgs.config option.
modulesPath: The location of the module directory of NixOS.

Modularize your configuration.nix

Many people start of using a single configuration.nix and eventually their single file configuration gets too large to search through and maintain conveniently.

This is where modules come in allowing you to break up your configuration into logical parts. Your boot.nix will contain settings and options related to the actual boot process. You’re services.nix will only have services and so on…

These modules are placed in a logical path relative to either your configuration.nix or equivalent or if you’re using flakes relative to your flake.nix or equivalent.
- The imports mechanism takes paths to other modules as its argument and combines them to be included in the evaluation of the system configuration.

{ ... }:
{
  imports = [
     # Paths to other modules

     # They can be relative paths
     ./otherModule.nix

     # Or absolute
     /path/to/otherModule.nix

     # Or to a directory
     ../modules/home/shells/nushell
  ];
}

❗: The imports mechanism includes and evaluates the Nix expression found at the given path as a module. If that path is a directory, it will automatically look for and evaluate a default.nix file within that directory as a module. It is common to have that default.nix be a function that only imports and combines all the modules in said directory. Like the above example, in the nushell directory would be a default.nix that is automatically imported and evaluated.

Crucial Distinction: imports vs. import:

Beginners often confuse the modules attribute imports = [./module.nix] here with the Nix builtins function import module.nix. The first expects a path to a file containing a NixOS module (having the same specific structure we’re describing here), while the second loads whatever Nix expression is in that file (no expected structure). –NixOS Wiki.

Considering configuration.nix is a module, it can be imported like any other module and this is exactly what you do when getting started with flakes.

# flake.nix
{
  description = "NixOS configuration";

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

  outputs = inputs@{ nixpkgs, home-manager, ... }: {
    nixosConfigurations = {
      hostname = nixpkgs.lib.nixosSystem {
        system = "x86_64-linux";
        modules = [
          ./configuration.nix
          home-manager.nixosModules.home-manager
          {
            home-manager.useGlobalPkgs = true;
            home-manager.useUserPackages = true;
            home-manager.users.jdoe = ./home.nix;

            # Optionally, use home-manager.extraSpecialArgs to pass
            # arguments to home.nix
          }
        ];
      };
    };
  };
}

modules = [...] in flake.nix: This is effectively the initial imports list for your entire NixOS system or Home Manager user configuration. It tells the Nix module system: “Start by collecting and merging the configurations defined in these specific modules.”

The above example is what you get from running: nix flake new /etc/nixos -t github:nix-community/home-manager#nixos

If you notice the home-manager.nixosModules.home-manager, that is what imports home-manager as a module.

You could also make the actual home-manager module and import it like this:

# home-manager.nix
{ inputs, outputs, ... }: {
  imports = [
    # Import home-manager's NixOS module
    inputs.home-manager.nixosModules.home-manager
  ];

  home-manager = {
    extraSpecialArgs = { inherit inputs outputs; };
    users = {
      # Import your home-manager configuration
      your-username = import ../home-manager/home.nix;
    };
  };
}

This “module” isn’t much different from the one included in the flake.nix above, it is just shown here to show the flexibility of modules. They can be as big and complex or as small and simple as you want. You can break up every single program or component of your configuration into individual modules or have modules that bundle similar programs the choice is yours.

Then in your configuration.nix or equivalent you would add home-manager.nix to your imports list and you would have home-manager as a NixOS module.

✔️ Refresher (Click to Expand):

An attribute set is a collection of name-value pairs called attributes:

Attribute sets are written enclosed in curly braces {}. Attribute names and attribute values are separated by an equal sign =. Each value can be an arbitrary expression, terminated by a semicolon ;.

Example:nix.dev reference This defines an attribute set with attributes named:

x with the value 123, an integer

text with the value "Hello", a string

y where the value is the result of applying the function f to the attribute set {bla = 456; }
{
 x = 123;
 text = "Hello";
 y = f { bla = 456; };
}
{ a = "Foo"; b = "Bar"}.a
~ "Foo"

Attributes can appear in any order. An attribute name may only occur once in each attribute set.

❗ Remember {} is a valid attribute set in Nix.

The following is a function with an attribute set argument, remember that anytime you see a : in Nix code it means this is a function. To the left is the function arguments and to the right is the function body:

{ a, b }: a + b

The simplest possible NixOS Module:

{ ... }:
{
}

NixOS produces a full system configuration by combining smaller, more isolated and reusable components: Modules. If you want to understand Nix and NixOS make sure you grasp modules!

A NixOS module defines configuration options and behaviors for system components, allowing users to extend, customize, and compose configurations declaratively.

A module is a file containing a Nix expression with a specific structure. It declares options for other modules to define (give a value). Modules were introduced to allow extending NixOS without modifying its source code.

To define any values, the module system first has to know which ones are allowed. This is done by declaring options that specify which attributes can be set and used elsewhere.

If you want to write your own modules, I recommend setting up nixd or nil with your editor of choice. This will allow your editor to warn you about missing arguments and dependencies as well as syntax errors.

Declaring Options

Options are declared under the top-level options attribute with lib.mkOption.

mkOption Creates an Option attribute set. It accepts an attribute set with certain keys such as, default, package, and example.

# options.nix
{ lib, ... }:
{
  options = {
    name = lib.mkOption { type = lib.types.str; };
  };
}

lib provides helper functions from nixpkgs.lib and the ellipsis (...) is for arbitrary arguments which means that this function is prepared to accept any additional arguments that the caller might provide, even if those arguments are not explicitly named or used within the module’s body. They make the modules more flexible, without the ... each module would have to explicitly list every possible argument it might receive, which would be cumbersome and error-prone. So {lib, ... }: means that “I need the lib argument” and I acknowledge that the module system might pass other arguments automatically (like config, pkgs, etc.) and I’m fine with them being there, even if I don’t use them directly in this specific module file.

Defining Values

Options are set or defined under the top-level config attribute:

# config.nix
{ ... }:
{
  config = {
    name = "Slick Jones";
  };
}

In this option declaration, we created an option name of type string and set that same option to a string.

Option Definitions can be in a separate file than Option Declarations

Evaluating Modules

Modules are evaluated with lib.evalModules lib.evalModules evaluates a set of modules, typically once per application (e.g. once for NixOS and once for Home-Manager).

Checking out the Vim module provided by Nixpkgs

The following is nixpkgs/nixos/modules/programs/vim.nix, a module that is included in the Nixpkgs collection:

{
  config,
  lib,
  pkgs,
  ...
}:

let
  cfg = config.programs.vim;
in
{
  options.programs.vim = {
    enable = lib.mkEnableOption "Vi IMproved, an advanced text";

    defaultEditor = lib.mkEnableOption "vim as the default editor";

    package = lib.mkPackageOption pkgs "vim" { example = "vim-full"; };
  };

  # TODO: convert it into assert after 24.11 release
  config = lib.mkIf (cfg.enable || cfg.defaultEditor) {
    warnings = lib.mkIf (cfg.defaultEditor && !cfg.enable) [
      "programs.vim.defaultEditor will only work if programs.vim.enable is
       enabled, which will be enforced after the 24.11 release"
    ];
    environment = {
      systemPackages = [ cfg.package ];
      variables.EDITOR = lib.mkIf cfg.defaultEditor (lib.mkOverride 900 "vim");
      pathsToLink = [ "/share/vim-plugins" ];
    };
  };
}

It provides options to enable Vim, set it as the default editor, and specify the Vim package to use.

✔️ Breakdown of the vim module.(Click to Expand)

1. Module Inputs and Structure:

{
  config,
  lib,
  pkgs,
  ...
}

Inputs: The module takes the above inputs and ... (catch-all for other args)

config: Allows the module to read option values (e.g. config.programs.vim.enable). It provides access to the evaluated configuration.
lib: The Nixpkgs library, giving us helper functions like mkEnableOption , mkIf, and mkOverride.
pkgs: The Nixpkgs package set, used to access packages like pkgs.vim
...: Allows the module to accept additional arguments, making it flexible for extension in the future.

Key Takeaways: A NixOS module is typically a function that can include config, lib, and pkgs, but it doesn’t require them. The ... argument ensures flexibility, allowing a module to accept extra inputs without breaking future compatibility. Using lib simplifies handling options (mkEnableOption, mkIf, mkOverride) and helps follow best practices. Modules define options, which users can set in their configuration, and config, which applies changes based on those options.

Local Configuration Reference:

let
  cfg = config.programs.vim;
in

This is a local alias. Instead of typing config.programs.vim over and over, the module uses cfg.

Option Declaration

options.programs.vim = {
  enable = lib.mkEnableOption "Vi IMproved, an advanced text";
  defaultEditor = lib.mkEnableOption "vim as the default editor";
  package = lib.mkPackageOption pkgs "vim" { example = "vim-full"; };
};

This defines three user-configurable options:

enable: Turns on Vim support system-wide.
defaultEditor: Sets Vim as the system’s default $EDITOR.
package: lets the user override which Vim package is used.

mkPackageOption is a helper that defines a package-typed option with a default (pkgs.vim) and provides docs + example. Using lib.mkEnableOption makes it clear exactly where this function is coming from. Same with lib.mkIf and as you can see they can be further down the configuration, further from where you defined with lib; making it less clear where they come from. Explicitness is your friend when it comes to reproducability and clarity.

Conditional Configuration

config = lib.mkIf (cfg.enable || cfg.defaultEditor) {

This block is only activated if either programs.vim.enable or defaultEditor is set.

Warnings

warnings = lib.mkIf (cfg.defaultEditor && !cfg.enable) [
  "programs.vim.defaultEditor will only work if programs.vim.enable is enabled,
   which will be enforced after the 24.11 release"
];

Gives you a soft warning if you try to set defaultEditor = true without also enabling Vim.

Actual System Config Changes

environment = {
  systemPackages = [ cfg.package ];
  variables.EDITOR = lib.mkIf cfg.defaultEditor (lib.mkOverride 900 "vim");
  pathsToLink = [ "/share/vim-plugins" ];
};

It adds Vim to your systemPackages, sets $EDITOR if defaultEditor is true, and makes /share/vim-plugins available in the environment.

The following is a bat home-manager module that I wrote:

# bat.nix
{
  pkgs,
  config,
  lib,
  ...
}: let
  cfg = config.custom.batModule;
in {
  options.custom.batModule.enable = lib.mkOption {
    type = lib.types.bool;
    default = false;
    description = "Enable bat module";
  };

  config = lib.mkIf cfg.enable {
    programs.bat = {
      enable = true;
      themes = {
        dracula = {
          src = pkgs.fetchFromGitHub {
            owner = "dracula";
            repo = "sublime"; # Bat uses sublime syntax for its themes
            rev = "26c57ec282abcaa76e57e055f38432bd827ac34e";
            sha256 = "019hfl4zbn4vm4154hh3bwk6hm7bdxbr1hdww83nabxwjn99ndhv";
          };
          file = "Dracula.tmTheme";
        };
      };
      extraPackages = with pkgs.bat-extras; [
        batdiff
        batman
        prettybat
        batgrep
      ];
    };
  };
}

Now I could add this to my home.nix to enable it:

# home.nix
custom = {
  batModule.enable = true;
}

If I set this option to true the bat configuration is dropped in place. If it’s not set to true, it won’t put the bat configuration in the system. Same as with options defined in modules within the Nixpkgs repository.

If I had set the default to true, it would automatically enable the module without requiring an explicit custom.batModule.enable = true; call in my home.nix.

Module Composition

NixOS achieves its full system configuration by combining the configurations defined in various modules. This composition is primarily handled through the imports mechanism.

imports: This is a standard option within a NixOS or Home Manager configuration (often found in your configuration.nix or home.nix). It takes a list of paths to other Nix modules. When you include a module in the imports list, the options and configurations defined in that module become part of your overall system configuration.

You declaratively state the desired state of your system by setting options across various modules. The NixOS build system then evaluates and merges these option settings. The culmination of this process, which includes building the entire system closure, is represented by the derivation built by config.system.build.toplevel.

NixOS Modules and Dependency Locking with npins

✔️ npins example (Click to Expand)

As our NixOS configurations grow in complexity, so too does the challenge of managing the dependencies they rely on. Ensuring consistency and reproducibility not only applies to individual packages but also to the versions of Nixpkgs and other external resources our configurations depend upon.

Traditionally, NixOS configurations often implicitly rely on the version of Nixpkgs available when nixos-rebuild is run. However, for more robust and reproducible setups, especially in collaborative environments or when rolling back to specific configurations, explicitly locking these dependencies to specific versions becomes crucial.

In the following example, we’ll explore how to use a tool called npins to manage and lock the dependencies of a NixOS configuration, ensuring a more predictable and reproducible system. This will involve setting up a project structure and using npins to pin the specific version of Nixpkgs our configuration relies on.

This is the file structure:

❯ tree
.
├── configuration.nix
├── default.nix
├── desktop.nix
└── npins
    ├── default.nix
    └── sources.json

This uses npins for dependency locking. Install it and run this in the project

directory:

npins init

Create a default.nix with the following:

# default.nix
{ system ? builtins.currentSystem, sources ? import ./npins, }:
let
  pkgs = import sources.nixpkgs {
    config = { };
    overlays = [ ];
  };
  inherit (pkgs) lib;
in lib.makeScope pkgs.newScope (self: {

  shell = pkgs.mkShell { packages = [ pkgs.npins self.myPackage ]; };

    # inherit lib;

  nixosSystem = import (sources.nixpkgs + "/nixos") {
    configuration = ./configuration.nix;
  };

  moduleEvale = lib.evalModules {
    modules = [
      # ...
    ];
  };
})

A configuration.nix with the following:

# configuration.nix
{
  boot.loader.grub.device = "nodev";
  fileSystems."/".device = "/devst";
  system.stateVersion = "25.05";

  # declaring options means to declare a new option
  # defining options means to define a value of an option
  imports = [
    # ./main.nix
     ./desktop.nix # Files
    # ./minimal.nix
  ];

  # mine.desktop.enable = true;
}

And a desktop.nix with the following:

# desktop.nix
{ pkgs, lib, config, ... }:

{
  imports = [];

  # Define an option to enable or disable desktop configuration
  options.mine.desktop.enable = lib.mkEnableOption "desktop settings";

  # Configuration that applies when the option is enabled
  config = lib.mkIf config.mine.desktop.enable {
    environment.systemPackages = [ pkgs.git ];
  };
}

mkEnableOption defaults to false. Now in your configuration.nix you can uncomment mine.desktop.enable = true; to enable the desktop config and vice-versa.

You can test that this works by running:

nix-instantiate -A nixosSystem.system

nix-instantiate performs only the evaluation phase of Nix expressions. During this phase, Nix interprets the Nix code, resolves all dependencies, and constructs derivations but does not execute any build actions. Useful for testing.

To check if this worked and git is installed in systemPackages you can load it into nix repl but first you’ll want lib to be available so uncomment this in your default.nix:

# default.nix
inherit lib;

Rerun nix-instantiate -A nixosSystem.system

Then load the repl and check that git is in systemPackages:

nix repl -f .
nix-repl> builtins.filter (pkg: lib.hasPrefix "git" pkg.name) nixosSystem.config.environment.systemPackages

This shows the path to the derivation

Check that mine.desktop.enable is true

nix-repl> nixosSystem.config.mine.desktop.enable
true

As demonstrated with npins, explicitly managing the dependencies of your NixOS modules is a powerful technique for ensuring the long-term stability and reproducibility of your system configurations. By pinning specific versions of Nixpkgs and other resources, you gain greater control over your environment and reduce the risk of unexpected changes due to upstream updates.

Best Practices

You’ll see the following all throughout Nix code and is convenient although it doesn’t follow best practices. One reason is static analysis can’t reason about the code (e.g. Because it implicitly brings all attributes into scope, tools can’t verify which ones are actually being used), because it would have to actually evaluate the files to see which names are in scope:

# utils.nix
{ pkgs, ... }: {
  environment.systemPackages = with pkgs; [
    rustup
    evcxr
    nix-prefetch-git
  ];
}

Another reason the above expression is considered an “anti-pattern” is when more then one with is used, it’s no longer clear where the names are coming from.

Scoping rules for with are not intuitive, see issue –nix.dev This can make debugging harder, as searching for variable origins becomes ambiguous (i.e. open to more than one interpretation).

The following follows best practices:

{pkgs, ... }: {
  environment.systemPackages = builtins.attrValues {
    inherit (pkgs)
      rustup
      evcxr
      nix-prefetch-git;
  };
}

Noogle builtins.attrValues

✔️ Above Command Summary (Click to Expand)

{
  inherit (pkgs) rustup evcxr nix-prefetch-git;
}

is equivalent to:

{
  rustup = pkgs.rustup;
  evcxr = pkgs.evcxr;
  nix-prefetch-git = pkgs.nix-prefetch-git;
}

Applying builtins.attrValues produces:

[ pkgs.evcxr pkgs.nix-prefetch-git pkgs.rustup ]

As you can see only the values are included in the list, not the keys. This is more explicit and declarative but can be more complicated, especially for a beginner.

builtins.attrValues returns the values of all attributes in the given set, sorted by attribute name. The above expression turns into something like the following avoiding bringing every attribute name from nixpkgs into scope.

A more straightforward example:

attrValues {c = 3; a = 1; b = 2;}
=> [1 2 3]

This approach avoids unintended name clashes or confusion when debugging.

Upon looking into this a bit further, most people use the following format to avoid the “anti-pattern” from using with pkgs;:

# utils.nix
{ pkgs, ... }: {
  environment.systemPackages = [
    pkgs.rustup
    pkgs.evcxr
    pkgs.nix-prefetch-git
  ];
}

While the performance differences might be negligible on modern computers, adopting this best practice from the start is highly recommended. The above approach is more explicit, it’s clear exactly where each package is coming from.

If maintaining strict scope control matters, use builtins.attrValues.

If readability and simplicity are more your priority, explicitly referencing pkgs.<packageName> might be better. Now you can choose for yourself.

Conclusion

As we have seen throughout this chapter, modules are the building blocks of your NixOS system and are themselves often functions. There are a few different ways to use these modules to build your system. In the next chapter, Nix Flakes Explained we will learn about Nix Flakes as a more modern and comprehensive entrypoint for managing your entire system and its dependencies.

To further deepen your understanding of NixOS Modules and the broader ecosystem of tools and best practices surrounding them, the following resources offer valuable insights and information.

Resources on Modules

✔️ Resources (Click to Expand)

Videos

NixHour Writing NixOS modules – This example is from this video infinisilModules

tweagModuleSystemRecursion

Nix Flakes Explained

2025-11-21T00:00:00+00:00

Chapter 4

✔️ Click to Expand Table of Contents

Nix Flakes Explained

If you’re completely new, take a look at this to get flakes on your system.

For the Nix Flake man page type man nix3 flake and for a specific feature, type something like man nix3 flake-lock.

Flakes replace stateful channels (which cause much confusion among novices) and introduce a more intuitive and consistent CLI, making them a perfect opportunity to start using Nix. – Alexander Bantyev Practical Nix Flakes

The “state” being remembered and updated by channels is the specific revision of the Nixpkgs repository that your local Nix installation considers “current” for a given channel. When this state changes on your machine, your builds diverge from others whose machines have a different, independently updated channel state.

Channels are also constantly updated on the remote servers. So, “nixos-unstable” today refers to a different set of packages and versions than “nixos-unstable” did yesterday or will tomorrow.

Flakes solve this by making the exact revision of nixpkgs (and other dependencies) an explicit input within your flake.nix file, pinned in the flake.lock. This means the state is explicitly defined in the configuration itself, not implicitly managed by a global system setting.

Evaluation time is notoriously slow on NixOS, the problem was that in the past Nix evaluation wasn’t hermetic preventing effective evaluation caching. A .nix file can import other Nix files or by looking them up in the Nix search path ($NIX_PATH). This causes a cached result to be inconsistent unless every file is perfectly kept track of. Flakes solve this problem by ensuring fully hermetic evaluation.

“Hermetic” means that the output of an evaluation (the derivation itself) depends only on the explicit inputs provided, not on anything external like environment variables or pulling in files only on your system. This is the problem that Nix solves and the problem that flakes are built around.

What is a Nix Flake?

Nix flakes are independent components in the Nix ecosystem. They define their own dependencies (inputs) and what they produce (outputs), which can include packages, deployment configurations, or Nix functions for other flakes to use.

Flakes provide a standardized framework for building and managing software, making all project inputs explicit for greater reproducibility and self-containment.

At its core, a flake is a source tree (like a Git repository) that contains a flake.nix file in its root directory. This file provides a standardized way to access Nix artifacts such as packages and modules.

Flakes provide a standard way to write Nix expressions (and therefore packages) whose dependencies are version-pinned in a lock file, improving reproducibility of Nix installations. – NixOS Wiki

Think of flake.nix as the central entry point of a flake. It not only defines what the flake produces but also declares its dependencies.

Key Concepts

flake.nix: The Heart of a Flake

The flake.nix file is mandatory for any flake. It must contain an attribute set with at least one required attribute: outputs. It can also optionally include description and inputs.

Basic Structure:

{
  description = "Package description";
  inputs = { /* Dependencies go here */ };
  outputs = { /* What the flake produces */ };
  nixConfig = { /* Advanced configuration options */ };
}

I typically see nixConfig used for extra-substituters for cachix. This is a general-purpose way to define Nix configuration options that apply when this flake is evaluated or built. It ties into your /etc/nix/nix.conf or ~/.config/nix/nix.conf.

For example, create a directory and add a flake.nix with the following contents, yes this is a complete flake.nix demonstrating outputs being the only required attribute:

# flake.nix
{
  outputs = _: { multiply = 2 * 2; };
}

Now evaluate it with:

nix eval .#multiply
4

In the outputs = _: { ... }; line, the _ (underscore) is a placeholder argument. It represents the inputs that the outputs function could receive (like inputs, self, pkgs, etc.), but in this specific case, we’re not using any of them to define the multiply attribute. It’s a common convention in Nix to use _ when an argument is required by a function but intentionally ignored.

In the command nix eval .#multiply:

the . signifies the current directory, indicating that Nix should look for a flake.nix file in the directory where you’re running the command.
The # is used to select a specific attribute from the outputs of the flake. In this case, it’s telling Nix to evaluate the multiply attribute.

In the next example we will create a devShells output as well as a packages output.

flake.lock auto-generated lock file

All flake inputs are pinned to specific revisions in a lockfile called flake.lock This file stores the revision info as JSON.

The flake.lock file ensures that Nix flakes have purely deterministic outputs. A flake.nix file without an accompanying flake.lock should be considered incomplete and a kind of proto-flake. Any Nix CLI command that is run against the flake—like nix build, nix develop, or even nix flake show—generates a flake.lock for you.

Here’s an example section of a flake.lock file that pins Nixpkgs to a specific revision:

$ cat flake.lock
{
  "nodes": {
    "nixpkgs": {
      "info": {
        "lastModified": 1587398327,
        "narHash": "sha256-mEKkeLgUrzAsdEaJ/1wdvYn0YZBAKEG3AN21koD2AgU="
      },
      "locked": {
        "owner": "NixOS",
        "repo": "nixpkgs",
        "rev": "5272327b81ed355bbed5659b8d303cf2979b6953",
        "type": "github"
      },
      "original": {
        "owner": "NixOS",
        "ref": "nixos-20.03",
        "repo": "nixpkgs",
        "type": "github"
      }
    },
    "root": {
      "inputs": {
        "nixpkgs": "nixpkgs"
      }
    }
  },
  "root": "root",
  "version": 5
}

Any future build of this flake will use the version of nixpkgs recorded in the lock file. If you add new inputs, they will be automatically added when you run a nix flake command like nix flake show. But it won’t replace existing locks.

If you need to update a locked input to the latest version:

nix flake lock --update-input nixpkgs
nix build

The above command allows you to update individual inputs, and nix flake update will update the whole lock file.

Helper functions that are good to know for working with Flakes

lib.genAttrs: A function, given the name of the attribute, returns the attribute’s value

Example:

nix repl
nix-repl> :l <nixpkgs>
nix-repl> lib.genAttrs [ "boom" "bash" ] (name: "sonic" + name)

Output:

{
  bash = "sonicbash";
  boom = "sonicboom";
}

You will often see the following:

A common use for this with flakes is to have a list of different systems:

     systems = [
       "x86_64-linux"
       "aarch64-linux"
       "x86_64-darwin"
       "aarch64-darwin"
     ];

And use it to generate an attribute set for each listed system:

eachSystem = lib.genAttrs systems;

The above command creates an attribute set by mapping over a list of system strings. If you notice, you provide it a list (i.e. [ 1 2 3 ]) and the function returns a set (i.e. { ... })

Why genAttrs is useful:

It lets you define attributes (like packages, checks, devShells) per supported system in a DRY(don’t repeat yourself), structured way.
lib.mapAttrs: A function, given an attribute’s name and value, returns a new nameValuePair.

Example:

nix-repl> builtins.mapAttrs (name: value: name + "-" + value) { x = "foo"; y = "bar"; }

Output:

{
  x = "x-foo";
  y = "y-bar";
}

pkgs.mkShell: is a specialized stdenv.mkDerivation that removes some repetition when using it with nix-shell (or nix develop)

Example:

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

  inputsFrom = [ pkgs.hello pkgs.gnutar ];

  shellHook = ''
    export DEBUG=1
  '';
}

A Simple flake that outputs a devshell and a package

In a new directory create a flake.nix

# flake.nix
{
  outputs = {
    self,
    nixpkgs,
  }: let
    pkgs = nixpkgs.legacyPackages.x86_64-linux;
  in {

    packages.x86_64-linux.default = pkgs.kakoune; # You could define a meta-package here

    devShells.x86_64-linux.default = pkgs.mkShell {
      packages = [
        pkgs.kakoune
        pkgs.git
        pkgs.ripgrep
        pkgs.fzf
      ];
    };
  };
}

mkShell is a wrapper around mkDerivation

This flake offers two main outputs for x86_64-linux systems:

A standard package (packages.x86_64-linux.default): This simple example just re-exports kakoune from nixpkgs. You could build your own apps here.
A development shell (devShells.x86_64-linux.default): This provides a convenient environment where you have specific tools available without installing them globally on your system.

To use this flake you have a few options:

nix run will launch kakoune
nix develop will activate the development environment providing all of the pkgs listed under mkShell.
Or more explicitly nix develop .#devShells.x86_64-linux.default, does the same thing as the command above.

Flake References

✔️ Flake References (Click to Expand)

Flake references (flakerefs) are a way to specify the location of a flake. They have two different formats:

Attribute set representation:
{
  type = "github";
  owner = "NixOS";
  repo = "nixpkgs";
}
or URL-like syntax:
github:NixOS/nixpkgs
These are used on the command line as a more convenient alternative to the attribute set representation. For instance, in the command
nix build github:NixOS/nixpkgs#hello
github:NixOS/nixpkgs is a flake reference (while hello is an output attribute). They are also allowed in the inputs attribute of a flake, e.g.
inputs.nixpkgs.url = "github:NixOS/nixpkgs";
is equivalent to
inputs.nixpkgs = {
  type = "github";
  owner = "NixOS";
  repo = "nixpkgs";
};
– nix.dev flake-references

Nix Flake Commands

✔️ Flake Commands (Click to Expand)

nix flake provides subcommands for creating, modifying and querying Nix Flakes. Flakes are the unit for packaging Nix code in a reproducible and discoverable way. They can have dependencies on other flakes, making it possible to have multi-repository Nix projects.

— From nix.dev Reference Manual

The main thing to note here is that nix flake is used to manage Nix flakes and that Flake commands are whitespace separated rather than hyphen - separated.
Flakes do provide some advantages when it comes to discoverability of outputs.
For Example, two helpful commands to inspect a flake are:
- nix flake show command: Show the outputs provided by a flake.
- nix flake check command: check whether the flake evaluates and run its tests.
- Any Nix CLI command that is run against a flake – like nix build, nix develop, nix flake show – generate a flake.lock file for you.
  - The flake.lock file ensures that all flake inputs are pinned to specific revisions and that Flakes have purely deterministic outputs.
Example:

nix shell nixpkgs#ponysay --command ponysay "Flakes Rock!"

This works because of the [flake registry] that maps symbolic identifiers like nixpkgs to actual locations such as https://github.com/NixOS/nixpkgs. So the following are equivalent:

nix shell nixpkgs#ponysay --command ponysay Flakes Rock!
nix shell github:NixOS/nixpkgs#ponysay --command ponysay Flakes Rock!

To override the nixpkgs registry with your own local copy you could:

nix registry add nixpkgs ~/src/local-nixpkgs

Attribute Sets: The Building Blocks

✔️ Attribute set Refresher (Click to Expand)

Attribute sets are fundamental in Nix. They are simply collections of name-value pairs wrapped in curly braces {}.

Example, (click to see Output):

let
  my_attrset = { foo = "bar"; };
in
my_attrset.foo
~ "bar"

Top-Level Attributes of a Flake:

Flakes have specific top-level attributes that can be accessed directly (without dot notation). The most common ones are inputs, outputs, and nixConfig.

Deeper Dive into the Structure of `flake.nix`

inputs: Declaring Dependencies

The inputs attribute set specifies the other flakes that your current flake depends on.

Each key in the inputs set is a name you choose for the dependency, and the value is a reference to that flake (usually a URL or a Git Repo).

To access something from a dependency, you generally go through the inputs attribute (e.g., inputs.helix.packages).

See Nix Flake inputs for a flake inputs deep dive.

Example: This declares dependencies on the nixpkgs and import-cargo flakes:

inputs = {
  import-cargo.url = "github:edolstra/import-cargo";
  nixpkgs.url = "nixpkgs";
};

When Nix evaluates your flake, it fetches and evaluates each input. These evaluated inputs are then passed as an attribute set to the outputs function, with the keys matching the names you gave them in the inputs set.

The special input self is a reference to the outputs and the source tree of the current flake itself.

outputs: Defining What Your Flake Provides

The outputs attribute defines what your flake makes available. This can include packages, NixOS modules, development environments (devShells) and other Nix derivations.

Flakes can output arbitrary Nix values. However, certain outputs have specific meanings for Nix commands and must adhere to particular types (often derivations, as described in the output schema).

You can inspect the outputs of a flake using the command:

nix flake show

This command takes a flake URI and displays its outputs in a tree structure, showing the attribute paths and their corresponding types.

Understanding the outputs Function

Beginners often mistakenly think that self and nixpkgs within outputs = { self, nixpkgs, ... }: { ... } are the outputs themselves. Instead, they are the input arguments (often called output arguments) to the outputs function.

The outputs function in flake.nix always takes a single argument, which is an attribute set. The syntax { self, nixpkgs, ... } is Nix’s way of destructuring this single input attribute set to extract the values associated with the keys self and nixpkgs.

Flakes output your whole system configuration, packages, as well as Nix functions for use elsewhere.

For example, the nixpkgs repository has its own flake.nix file that outputs many helper functions via the lib attribute.
For a deep dive into flake outputs, see Nix Flake Outputs

The lib convention The convention of using lib to output functions is observed not just by Nixpkgs but by many other Nix projects. You’re free, however, to output functions via whichever attribute you prefer. – Zero to Nix Flakes

Some flake outputs are required to be system specific (i.e. “x86_64-linux” for (64-bit AMD/Intel Linux) including packages, development environments, and NixOS configurations)

Variadic Attributes (…) and @-patterns

The ... syntax in the input arguments of the outputs function indicates variadic attributes, meaning the input attribute set can contain more attributes than just those explicitly listed (like lib and nixpkgs).

Example:

mul = { a, b, ... }: a * b;
mul { a = 3; b = 4; c = 2; } # 'c' is an extra attribute

However, you cannot directly access these extra attributes within the function body unless you use the @-pattern:

(Click for Output)

mul = s@{ a, b, ... }: a  b  s.c; # 's' now refers to the entire input set
mul { a = 3; b = 4; c = 2; } # Output: 24
~ 24

When used in the outputs function argument list (e.g., outputs = { pkgs, ... } @ inputs), the @-pattern binds the entire input attribute set to a name (in this case, inputs) while also allowing you to destructure specific attributes like pkgs.

What outputs = { pkgs, ... } @ inputs: { ... }; does:

Destructuring: It tries to extract the value associated with the key pkgs from the input attribute set and binds it to the variable pkgs. The ... allows for other keys in the input attribute set to be ignored during this direct destructuring.
Binding the Entire Set: It binds the entire input attribute set to the variable inputs.
- Example flake.nix:

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

outputs = { self, nixpkgs, ... } @ attrs: { # A `packages` output for the x86_64-linux platform
packages.x86_64-linux.hello = nixpkgs.legacyPackages.x86_64-linux.hello;

    # A `nixosConfigurations` output (for a NixOS system named "fnord")
    nixosConfigurations.fnord = nixpkgs.lib.nixosSystem {
      system = "x86_64-linux";
      specialArgs = attrs;
      modules = [ ./configuration.nix ];
    };

};
}

Platform Specificity in Outputs

Flakes ensure that their outputs are consistent across different evaluation environments. Therefore, any package-related output must explicitly specify the target platform (a combination of architecture and OS, x86_64-linux).

legacyPackages Explained

legacyPackages is a way for flakes to interact with the traditional, less structured package organization of nixpkgs. Instead of packages being directly at the top level (e.g., pkgs.hello), legacyPackages provides a platform-aware way to access them within the flake’s structured output format (e.g., nixpkgs.legacyPackages.x86_64-linux.hello). It acts as a bridge between the flake’s expected output structure and nixpkgs’s historical organization.

The Sole Argument of outputs

It’s crucial to remember that the outputs function accepts only one argument, which is an attribute set. The { self, nixpkgs, ... } syntax is simply destructuring that single input attribute set.

Outputs of the Flake (Return Value)

The outputs of the flake refer to the attribute set that is returned by the outputs function. This attribute set can contain various named outputs like packages, nixosConfigurations, devShells, etc.

Imports: Including Other Nix Expressions

The import function in Nix is used to evaluate the Nix expression found at a specified path (usually a file or directory) and return its value.

Basic Usage: import ./path/to/file.nix

Passing Arguments During Import

import <nixpkgs> {} is calling two functions, not one.

import <nixpkgs>: The first function call

import is a built-in Nix function. Its job is to load and evaluate a Nix expression from a specified path.
<nixpkgs> is a flake reference. When you use import <nixpkgs>, Nix evaluates the default.nix file (or sometimes lib/default.nix) found at that location.
The default.nix in nixpkgs evaluates to a function. This function is designed to be configurable, allowing you to pass arguments like system, config, etc. to customize how nixpkgs behaves and what packages it provides.
So, import <nixpkgs> doesn’t give you the nixpkgs package set directly; it gives you the function that generates the nixpkgs package set derivation.

{}: The second function call (and its argument)

{} denotes an empty attribute set
When an attribute set immediately follows a function, it means you are calling that function and passing the attribute set as its single argument.

So, the {} after import <nixpkgs> is not part of the import function iteself. It’s the argument being passed to the function that import <nixpkgs> just returned.

You can also pass an attribute set as an argument to the Nix expression being imported:

let
myHelpers = import ./lib/my-helpers.nix { pkgs = nixpkgs; };
in
# ... use myHelpers

In this case, the Nix expression in ./lib/my-helpers.nix is likely a function that expects an argument (often named pkgs by convention):

# ./lib/my-helpers.nix

{ pkgs }:
let
myPackage = pkgs.stdenv.mkDerivation {
name = "my-package"; # ...
};
in
myPackage

By passing { pkgs = nixpkgs; } during the import, you are providing the nixpkgs value from your current flake.nix scope to the pkgs parameter expected by the code in ./lib/my-helpers.nix.

Importing Directories (default.nix)

When you use import with a path that points to a directory, Nix automatically looks for a file named default.nix within that directory. If found, Nix evaluates the expressions within default.nix as if you had specified its path directly in the import statement.

For more advanced examples see Nix Flake Examples

Conclusion: Unifying Your Nix Experience with Flakes

For some examples of more advanced outputs like devShells and checks, check out this blog post that I wrote: Nix Flakes Tips and Tricks

In this chapter, we’ve explored Nix Flakes as a powerful and modern approach to managing Nix projects, from development environments to entire system configurations. We’ve seen how they provide structure, dependency management, and reproducibility through well-defined inputs and outputs. Flakes offer a cohesive way to organize your Nix code and share it with others.

As we’ve worked with the flake.nix file, you’ve likely noticed its structure – a top-level attribute set defining various outputs like devShells, packages, nixosConfigurations, and more. These top-level attributes are not arbitrary; they follow certain conventions and play specific roles within the Flake ecosystem.

In the next chapter, Understanding Top-Level Attributes we will delve deeper into the meaning and purpose of these common top-level attributes. We’ll explore how they are structured, what kind of expressions they typically contain, and how they contribute to the overall functionality and organization of your Nix Flakes. Understanding these attributes is key to effectively leveraging the full potential of Nix Flakes.

Further Resources

✔️ Resources (Click to Expand)

Package Definitions Explained

2025-11-21T00:00:00+00:00

Chapter 8

✔️ Click to Expand Table of Contents

Package Definitions Explained

In Nix, the concept of a package can refer to two things:

A collection of files and data that constitute a piece of software or an artifact.
A Nix expression that describes how to create such a collection. This expression acts as a blueprint before the package exists in a tangible form.

The process begins with writing a package definition using the Nix language. This definition contains the necessary instructions and metadata about the software you intend to “package.”

The Journey from Definition to Package

✔️ Click to Expand

Package Definition:
- This is essentially a function written in the Nix language.
- Nix language shares similarities with JSON but includes the crucial addition of functions.
- It acts as the blueprint for creating a package.
Derivation:
- When the package definition is evaluated by Nix, it results in a derivation.
- A derivation is a concrete and detailed build plan.
- It outlines the exact steps Nix needs to take: fetching source code, building dependencies, compiling code, and ultimately producing the desired output (the package).
Realization (Building the Package):
- You don’t get a pre-built “package” directly from the definition or the derivation.
- The package comes into being when Nix executes the derivation. This process is often referred to as “realizing” the derivation.

Analogy: Think of a package definition as an architectural blueprint, the derivation as the detailed construction plan, and the realized package as the finished building.

## Skeleton of a Derivation

The most basic derivation structure in Nix looks like this:

{ stdenv }:

stdenv.mkDerivation { }

This is a function that expects an attribute set containing stdenv as its argument.
It then calls stdenv.mkDerivation (a function provided by stdenv) to produce a derivation.
Currently, this derivation doesn’t specify any build steps or outputs.
Further Reading:
The Standard Environment
Fundamentals of Stdenv

Example: A Simple “Hello” Package Definition

Here’s a package definition for the classic “hello” program:

# hello.nix
{
  stdenv,
  fetchzip,
}:

stdenv.mkDerivation {
  pname = "hello";
  version = "2.12.1";

  src = fetchzip {
    url = "[https://ftp.gnu.org/gnu/hello/hello-2.12.1.tar.gz](https://ftp.gnu.org/gnu/hello/hello-2.12.1.tar.gz)";
    sha256 = "";
  };
}

This is a Nix function that takes stdenv and fetchzip as arguments.
It uses stdenv.mkDerivation to define the build process for the “hello” package.
- pname: The package name.
- version: The package version.
- src: Specifies how to fetch the source code using fetchzip.

Handling Dependencies: Importing Nixpkgs

If you try to build hello.nix directly with nix-build hello.nix, it will fail because stdenv and fetchzip are part of Nixpkgs, which isn’t included in this isolated file.
To make this package definition work, you need to pass the correct arguments (stdenv, fetchzip) to the function.

The recommended approach is to create a default.nix file in the same directory:

# default.nix

let
  nixpkgs = fetchTarball "[https://github.com/NixOS/nixpkgs/tarball/nixos-24.05](https://github.com/NixOS/nixpkgs/tarball/nixos-24.05)";
  pkgs = import nixpkgs { config = {}; overlays = []; };
in
{
  hello = pkgs.callPackage ./hello.nix { };
}

This default.nix imports Nixpkgs.
It then uses pkgs.callPackage to call the function in hello.nix, passing the necessary dependencies from Nixpkgs.
You can now build the “hello” package using: nix-build -A hello. The -A flag tells Nix to build the attribute named hello from the top-level expression in default.nix.

Realizing the Derivation and Handling sha256

Evaluation vs. Realization: While “evaluate” refers to Nix processing an expression, “realize” often specifically means building a derivation and producing its output in the Nix store.
When you first run nix-build -A hello, it will likely fail due to a missing sha256 hash for the source file. Nix needs this hash for security and reproducibility. The error message will provide the correct sha256 value.
Example Error:

  nix-build -A hello
  error: hash mismatch in fixed-output derivation '/nix/store/pd2kiyfa0c06giparlhd1k31bvllypbb-source.drv':
  specified: sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=
  got: sha256-1kJjhtlsAkpNB7f6tZEs+dbKd8z7KoNHyDHEJ0tmhnc=
  error: 1 dependencies of derivation '/nix/store/b4mjwlv73nmiqgkdabsdjc4zq9gnma1l-hello-2.12.1.drv' failed to build

Replace the empty sha256 = ""; in hello.nix with the provided correct value: sha256 = "1kJjhtlsAkpNB7f6tZEs+dbKd8z7KoNHyDHEJ0tmhnc=";.

Building and Running the Result

After updating the sha256, you can successfully build the package:

nix-build -A hello

The output will be a result symlink pointing to the built package in the Nix store. You can then run the “hello” program:

./result/bin/hello
Hello, world!

Swaytools Package Definition

Example: The swaytools Package Definition

Let’s examine a more complex, real-world package definition from Nixpkgs: nixpkgs/pkgs/tools/wayland/swaytools/default.nix.

# default.nix
{
  lib,
  setuptools,
  buildPythonApplication,
  fetchFromGitHub,
  slurp,
}:

buildPythonApplication rec {
  pname = "swaytools";
  version = "0.1.2";

  format = "pyproject";

  src = fetchFromGitHub {
    owner = "tmccombs";
    repo = "swaytools";
    rev = version;
    sha256 = "sha256-UoWK53B1DNmKwNLFwJW1ZEm9dwMOvQeO03+RoMl6M0Q=";
  };

  nativeBuildInputs = [ setuptools ];

  propagatedBuildInputs = [ slurp ];

  meta = with lib; {
    homepage = "https://github.com/tmccombs/swaytools";
    description = "Collection of simple tools for sway (and i3)";
    license = licenses.gpl3Only;
    maintainers = with maintainers; [ atila ];
    platforms = platforms.linux;
  };
}

Breakdown of the Above default.nix

Click to Expand

1 Function Structure:

The file starts with a function taking an attribute set of dependencies from Nixpkgs: { lib, setuptools, buildPythonApplication, fetchFromGitHub, slurp }

.

Derivation Creation:

It calls buildPythonApplication, a specialized helper for Python packages (similar to stdenv.mkDerivation but pre-configured for Python). The rec keyword allows attributes within the derivation to refer to each other.

Package Metadata:

pname and version define the package’s name and version.
The meta attribute provides standard package information like the homepage, description, license, maintainers, and supported platforms.

Source Specification:

The src attribute uses fetchFromGitHub to download the source code from the specified repository and revision, along with its sha256 hash for verification.

Build and Runtime Dependencies:

nativeBuildInputs: Lists tools required during the build process (e.g., setuptools for Python).
propagatedBuildInputs: Lists dependencies needed at runtime (e.g., slurp).

Build Format:

format = "pyproject"; indicates that the package uses a pyproject.toml file for its Python build configuration.

Integration within Nixpkgs

Location: The swaytools definition resides in pkgs/tools/wayland/swaytools/default.nix.
Top-Level Inclusion: It’s made available as a top-level package in pkgs/top-level/all-packages.nix like this:

# all-packages.nix
swaytools = python3Packages.callPackage ../tools/wayland/swaytools { };

python3Packages.callPackage is used here because swaytools is a Python package, and it ensures the necessary Python-related dependencies are correctly passed to the swaytools definition.

Conclusion

In this chapter, we’ve journeyed through the fundamental concept of package definitions in Nix. We’ve seen how these Nix expressions act as blueprints, leading to the creation of derivations – the detailed plans for building software. Finally, we touched upon the realization process where Nix executes these derivations to produce tangible packages in the Nix store. Examining the simple “hello” package and the more complex “swaytools” definition provided practical insights into the structure and key attributes involved in defining software within the Nix ecosystem.

The crucial step in this process, the transformation from a package definition to a concrete build plan, is embodied by the derivation. This detailed specification outlines every step Nix needs to take to fetch sources, build dependencies, compile code, and produce the final package output. Understanding the anatomy and lifecycle of a derivation is key to unlocking the full power and flexibility of Nix.

In the next chapter, Introduction to Nix Derivations, we will delve deeper into the structure and components of these derivations. We will explore the attributes that define a build process, how dependencies are managed within a derivation, and how Nix ensures the reproducibility and isolation of your software builds through this fundamental concept.

Resources

Packaging Existing Software

Introduction

2000-01-01T00:00:00+00:00

📚 Welcome to nix-book!

🚀 If you find this guide helpful, please consider leaving a star ⭐ or supporting the project by buying me a coffee ☕. Your support helps keep this content updated and freely available.

Follow nix-book with your preferred feed format for automatic notifications of new content:

Welcome to my personal journey and guide through the Nix ecosystem! This “book” aims to be a practical and understandable resource for anyone looking to dive into Nix, NixOS, and Home Manager. Whether you’re just getting started or looking to deepen your understanding, I hope you find this resource helpful!

I am a technologist with a wide range of interests that I’m passionate about, NixOS being one of them. I am also a privacy advocate trying to spread the word.

✨ What You’ll Find Here

This book covers a range of topics to help you harness the power of Nix:

Getting Started with the Nix Ecosystem: Covers the Nix Language, Package Manager, and a minimal Btrfs-Subvol install with Disko and Flakes, including Btrfs Impermanence.
Hardening NixOS: A deep dive into security and hardening practices with NixOS
Hardening Networking: Configure dnscrypt-proxy, firewalls, and more.
Gnupg and gpg-agent on NixOS
Whonix KVM on NixOS
NixOS as a Guest VM with Secureblue as the Host
Version Control with Git
Version Control with JJ
Understanding Nix Functions: Explores practical Nix functions and their role with NixOS Modules.
NixOS Modules Explained: A dedicated deep dive into NixOS’s modular configuration system.
Nix Flakes Explained: Comprehensive coverage of Flake Inputs, Outputs, Examples, and extending Flakes with Custom Packages using Overlays.
Understanding Top-Level Attributes
Package Definitions Explained
Intro to Nix Derivations: Including how builders and Autotools work.
Comparing Flakes and Traditional Nix
Debugging and Tracing NixOS Modules
Working with Nixpkgs Locally
Fork, Clone, Contribute to Nixpkgs
Nix Pull Requests
Intro to Nushell on NixOS

My goal is to share my learnings and provide clear examples to make your Nix experience smoother and more enjoyable.

📖 How to Read the Book

You can read the book directly here on GitHub by navigating through the folders, or for a more comfortable reading experience, check out the dedicated website. I tried to write it in a way where you could jump to the chapter you’re interested in and still be able to follow along:

Start Here
Browse the book chapters here on GitHub.

🙏 Contributions & Feedback

This book is a living document, and I welcome your input! If you find any errors, have suggestions for improvements, or want to contribute a new section, please feel free to:

Reach out to me on Reddit u/saylesss88
Open an Issue: For bug reports, typos, or content suggestions.
Submit a Pull Request: If you have code changes or want to add content directly.

Your feedback is invaluable and helps make this resource better for everyone!

⚖️ License

This “Nix Book” is open-source and licensed under the Apache License 2.0.

This means you are free to use, modify, and distribute this work, provided you adhere to the terms of the license. You can find the full text of the license in the LICENSE file within this repository:

To see a WIP book on privacy, checkout privacy-book

View the Apache License 2.0

Chapter1

2000-01-01T00:00:00+00:00

Chapter1

✔️ Click to Expand Table of Contents

Intro

Welcome to nix-book, an introductory book about Nix. This book leans more towards using Flakes but will contrast traditional Nix where beneficial. Originally, this content started as a blog. I’m refining its flow to make it more cohesive.

In this chapter, I will touch on the different parts of the Nix ecosystem, give a quick example of each and explain how they fit together.

Click Here, or the logo on the top right, next to print for the RSS feed.

- ✔️: Will indicate an expandable section, click the little triangle to expand.

These sections are expandable!

The code blocks have an option to hide code, where I find it reasonable I will hide the outputs of the expressions. Click the eye in the right corner of the code block next to the copy clipboard.

Example hover over top-right corner of code block and click the eye to see hidden text:

{
  attrset = { a = 2; b = 4; };
~  hidden_set = { a = hidden; b = set; };
}

❗ If you’re new to Nix, think of it as a recipe book for software: you describe what you want (declarative), and Nix ensures it’s built the same way every time (reproducible).

Why Learn Nix?

The main reason to learn Nix is that it allows you to write declarative scripts for reproducible software builds. Rather than mutate the global state and install packages to a global location such as /usr/bin Nix stores packages in the Nix store, usually the directory /nix/store, where each package has its own unique subdirectory. This paradigm gives you some powerful features, such as:

Allowing multiple versions or variants of the same package at the same time. This prevents “DLL hell” from different applications having dependencies on different versions of the same package.
Atomic upgrades: Upgrading or uninstalling an application cannot break other applications and either succeed completely or fail completely preventing partial upgrades breaking your system. The nix store is immutable preventing package management operations from overwriting other packages. They wouldn’t overwrite each other anyways because the hashing scheme ensures that new versions or repeat packages end up at different paths.
Nix is designed to provide hermetic builds that aren’t affected by the environment, this helps you make sure that when packaging software that the dependencies are complete because they must be explicitly declared as inputs. With other package managers it is more difficult to be sure that an environment variable or something in your $PATH isn’t affecting your build.

Let’s dive into the key characteristics of Nix:

Concept	Description
Pure	Functions don’t cause side effects.
Functional	Functions can be passed as arguments and returned as results.
Lazy	Not evaluated until needed to complete a computation.
Declarative	Describing a system outcome.
Reproducible	Operations that are performed twice return same results

❗ Important: In Nix, everything is an expression, there are no statements.

❗ Important: Values in Nix are immutable.

The Nix Ecosystem

The Nix Language is the foundation of the ecosystem and is used to write Nix Expressions.

Example:

{ hello = "world"; }

or

"foo" + "bar"

While the Nix language provides the foundation for writing expressions, it is only part of the ecosystem. These expressions become powerful when used within the Nix Package Manager, which evaluates and realizes them into tangible software builds and system configurations. This is where Nixpkgs and NixOS come into play.

The Nix Package Manager, Nixpkgs, and NixOS

At the heart of the Nix ecosystem is Nix Package Manager. This powerful engine is responsible for orchestrating the entire process: taking Nix expressions (like package definitions and configuration modules), evaluating them into precise derivations, executing their build steps (the realization phase), and meticulously managing the immutable Nix store.

A cornerstone of the Nix ecosystem is Nixpkgs. This vast collection comprises tens of thousands of Nix expressions that describe how to build a wide array of software packages from source. Nixpkgs is more than just a package repository—it also contains NixOS Modules, declarative configurations that define system behavior, ensuring a structured and reproducible environment. These modules enable users to declaratively describe a Linux system, with each module contributing to the desired state of the overall system by leveraging package definitions and derivations. This is how NixOS emerges: it is quite simply the natural consequence of applying the Nix philosophy to building an entire Linux operating system.

We will further expand our understanding of modules in Chapter 3

The following is an example of a NixOS module that is part of the nixpkgs collection:

# nixpkgs/nixos/modules/programs/zmap.nix
{
  pkgs,
  config,
  lib,
  ...
}:

let
  cfg = config.programs.zmap;
in
{
  options.programs.zmap = {
    enable = lib.mkEnableOption "ZMap, a network scanner designed for Internet-wide network surveys";
  };

  config = lib.mkIf cfg.enable {
    environment.systemPackages = [ pkgs.zmap ];

    environment.etc."zmap/blacklist.conf".source = "${pkgs.zmap}/etc/zmap/blacklist.conf";
    environment.etc."zmap/zmap.conf".source = "${pkgs.zmap}/etc/zmap.conf";
  };
}

This module, programs.zmap.nix, demonstrates how NixOS configurations work. It defines an enable option for the ZMap network scanner. If enabled by the user in their system configuration, the module ensures the zmap package is installed and its default configuration files are placed in /etc, allowing ZMap to be managed declaratively as part of the operating system.
- When nixpkgs is imported (e.g., in a NixOS configuration), the configuration options and settings defined by its modules (like programs.zmap.nix) become available for use, typically accessed via dot notation (e.g., config.programs.zmap.enable). This ability to make such a huge set of modules and packages readily available without a significant performance penalty is due to Nix’s lazy evaluation; only the expressions required for a particular build or configuration are actually evaluated.
- Most of the time you’ll simply search to see if the package is already included in nixpkgs and follow the instructions there to get it on your system. It is good practice to first search for the options to see what configurable settings are available, and then proceed to search for the package itself if you know it exists or if you need its specific package definition. When you look up the options for Zmap, programs.zmap.enable is all that is listed in this example.
- Home Manager uses the same underlying Nix module system as NixOS, and when you do something like home.packages = with pkgs; you are referring to the same package derivations from nixpkgs as you would with environment.systemPackages. However, Home Manager’s own configuration modules (e.g., for programs.zsh or git) are distinct and reside in the Home Manager repository, designed for user-specific configurations.

One of the main differentiating aspects of Nix, as opposed to traditional package managers, is this concept that package builds are treated as pure functions. This functional paradigm ensures consistency and reproducibility, which are core tenets of the Nix philosophy.

Fig. X: Conceptual diagram illustrating the distinction between Nix and NixOS. Source: xeiaso, from the blog post “Making NixOS modules for fun and (hopefully) profit”, https://xeiaso.net/talks/asg-2023-nixos/.

Nix expressions permeate the ecosystem—everything in Nix is an expression, including the next key components: package definitions and derivations.

Package Definitions & Derivations

Package Definitions are specialized expressions that tell Nix how to build software.

Example package definition:

# hello.nix
 {pkgs ? import <nixpkgs> {}}:
 pkgs.stdenv.mkDerivation {
  pname = "hello";
  version = "2.12.1";

  src = pkgs.fetchurl {
    url = "https://ftp.gnu.org/gnu/hello/hello-2.12.1.tar.gz";
    sha256 = "086vqwk2wl8zfs47sq2xpjc9k066ilmb8z6dn0q6ymwjzlm196cd";
  };

  nativeBuildInputs = [pkgs.autoconf pkgs.automake pkgs.gcc];

  configurePhase = ''
    ./configure --prefix=$out
  '';

  buildPhase = ''
    make
  '';

  installPhase = ''
    make install
  '';
 }

Evaluation Phase:

Now when you run something like:

nix-instantiate hello.nix
warning: you did not specify '--add-root'; the result might be removed by the garbage collector
/nix/store/p2hbg16a9kpqgx2nzcsq39wmnyxyq4jy-hello-2.12.1.drv

Nix evaluates the expression and produces a .drv file (the derivation), a precise JSON-like blueprint describing how the package will be built. It does not contain the built software itself.

Realization Phase:

When you run:

nix-build hello.nix
#...snip...
shrinking RPATHs of ELF executables and libraries in /nix/store/53hqyw72dijq3wb5kc0ln04g681gk6cp-hello-2.12.1
shrinking /nix/store/53hqyw72dijq3wb5kc0ln04g681gk6cp-hello-2.12.1/bin/hello
checking for references to /build/ in /nix/store/53hqyw72dijq3wb5kc0ln04g681gk6cp-hello-2.12.1...
gzipping man pages under /nix/store/53hqyw72dijq3wb5kc0ln04g681gk6cp-hello-2.12.1/share/man/
patching script interpreter paths in /nix/store/53hqyw72dijq3wb5kc0ln04g681gk6cp-hello-2.12.1
stripping (with command strip and flags -S -p) in  /nix/store/53hqyw72dijq3wb5kc0ln04g681gk6cp-hello-2.12.1/bin
/nix/store/53hqyw72dijq3wb5kc0ln04g681gk6cp-hello-2.12.1

Nix realizes the derivation by actually executing the build steps, fetching sources, compiling (if needed), and producing the final result (typically stored in e.g. /nix/store/53hqyw72dijq3wb5kc0ln04g681gk6cp-hello-2.12.1)
nix-build also creates a symlink named result in your current directory, pointing to the final build output in the Nix store.

Execute the program:

./result/bin/hello
Hello, world!

result/bin/hello points to the executable inside the output of the derivation.The derivation describes how the package is built, but does not include the final binaries.

To say that another way, the derivation is not the executable. The executable is one of the derivations outputs. When Nix “realizes” a derivation, it executes those build instructions, and the result is the actual built software, which gets placed into its own unique path in the Nix store.

A single derivation can produce multiple outputs. The executable is typically part of the out output, specifically in its bin directory.

Here is a small snippet of what a .drv file could look like, I got this from building the hello derivation and running the following on the store path:

nix show-derivation /nix/store/9na8mwp5zaprikqaqw78v6cdn1rxac7i-hello-2.12.1

{
  "/nix/store/871398c9cbskmzy6bvfnynr8yrlh7nk0-hello-2.12.1.drv": {
    "args": [
      "-e",
      "/nix/store/v6x3cs394jgqfbi0a42pam708flxaphh-default-builder.sh"
    ],
    "builder": "/nix/store/1jzhbwq5rjjaqa75z88ws2b424vh7m53-bash-5.2p32/bin/bash",
    "env": {
      "__structuredAttrs": "",
      "buildInputs": "",
      "builder": "/nix/store/1jzhbwq5rjjaqa75z88ws2b424vh7m53-bash-5.2p32/bin/bash",
      "cmakeFlags": "",
      "configureFlags": "",
      "depsBuildBuild": "",
      "depsBuildBuildPropagated": "",
      "depsBuildTarget": "",
      "depsBuildTargetPropagated": "",
      "depsHostHost": "",
      "depsHostHostPropagated": "",
      "depsTargetTarget": "",
      "depsTargetTargetPropagated": "",
      "doCheck": "",
      "doInstallCheck": "",
      "mesonFlags": "",
      "name": "hello-2.12.1",
      "nativeBuildInputs": "",
      "out": "/nix/store/9na8mwp5zaprikqaqw78v6cdn1rxac7i-hello-2.12.1",
      "outputs": "out",
      "patches": "",
      "pname": "hello",
      "propagatedBuildInputs": "",
      "propagatedNativeBuildInputs": "",
      "src": "/nix/store/pa10z4ngm0g83kx9mssrqzz30s84vq7k-hello-2.12.1.tar.gz",
      "stdenv": "/nix/store/80wijs24wjp619zmrasrh805bax02xjm-stdenv-linux",
      "strictDeps": "",
      "system": "x86_64-linux",
      "version": "2.12.1"
    },
# ... snip ...

Conclusion

In this introductory chapter, we’ve laid the groundwork for understanding the powerful Nix ecosystem. We explored how the Nix Language forms the declarative bedrock, enabling us to define desired system states and software builds as expressions. You saw how the Nix Package Manager orchestrates this process, transforming those expressions into precise derivations during the evaluation phase, and then faithfully “realizing” them into reproducible, isolated artifacts within the immutable /nix/store.

We also introduced the vast Nixpkgs collection, which provides tens of thousands of package definitions and forms the foundation for NixOS — a fully declarative operating system built on these principles—and even user-level configurations like those managed by Home Manager. This unique functional approach, with its emphasis on immutability and lazy evaluation, is what enables Nix’s promises of consistency, atomic upgrades, and truly hermetic builds, fundamentally changing how we think about software and system management.

Related Sub-Chapters

The Nix Language
Nix Package Manager

Now that you have a foundational understanding of the Nix ecosystem and its core operational cycle, we are ready to delve deeper into the building blocks of Nix expressions. In the next chapter, Understanding Nix Functions, we will peel back the layers and explore the intricacies of function arguments, advanced patterns, scope, and how functions play a crucial role in building more sophisticated Nix expressions and derivations.

Here are some resources that are helpful for getting started:

Resources

✔️ Resources (Click to Expand)

NixOS Search
NixOS Options
Extranix Home-Manager Option Search
awesome-nix
Nix Core Ecosystem, Nix, NixOS, Nix Lang, Nixpkgs are all distinctly different; related things which can be confusing for beginners this article explains them.
nixpkgs: Vast package repository
How Nix Works
Nix Reference Manual Data Types The main Data Types you’ll come across in the Nix ecosystem
NixOS Wiki
nix.dev: Has become the top respected source of information in my opinion. There is a lot of great stuff in here, and they actively update the information.

`````nix repl
(let a = "2"; in                   # Let expressions are a way to create variables
a + a + builtins.toString "4")
`````

nix-book

Understanding Nix Functions

Chapter 2

Understanding Nix Functions

What are Nix Functions?

Builtins

Lambdas

Understanding Function Structure: The Role of the Colon

Single-Argument Functions: The Basics

Simulating Multiple Arguments: Currying

Currying example 2

Greeting Example

Partial Application: Using Functions Incrementally

Nix Functions being “first class citizens”

The Function Nature of NixOS and Home Manager Modules

Understanding passing and getting back arguments

Conclusion

Resources

Hardening NixOS

Hardening NixOS

Common Attack Vectors for Linux

Minimal Installation with LUKS

Manual Encrypted Install Following the Manual

Guided Encrypted BTRFS Subvol install using disko

Installing Software

Users and SUID Binaries

💥 The Danger of setuid

Capabilities

Impermanence

Replace timesyncd with a chron job that enables Network Time Security (NTS)

Secure Boot

The Kernel

Choosing your Kernel

The Hardened Kernel

sysctl

Kernel Security Settings

Further Hardening with sysctl

Hardening Boot Parameters

Hardened Memory Allocator

Hardening Systemd

Lynis and other tools

Securing SSH

Key generation

ssh-keygen

OpenSSH Server

Encrypted Secrets

Sops-nix Guide

Auditd

USB Port Protection

Doas over sudo (Warning Doas is unmaintained)

Firejail

Flatpak

SeLinux/AppArmor MAC (Mandatory Access Control)

Resources

Advanced Hardening with nix-mineral (Community Project)

Top-Level Attributes

Chapter 5

Understanding Top-Level Attributes in NixOS Modules

The Core of a NixOS System: system.build.toplevel

How Options Relate: A Chain of Influence

The NixOS Module System: Evaluating Options

How the Module System Works: A Simplified Overview

Conclusion

Practical Jujutsu

Practical Jujutsu

Quick Overview

Getting Started

Version Control Best Practices

The edit workflow

The squash Workflow

Pushing from the squash workflow

Bookmarks and Branches

Examples

Collaborating and opening PRs

Workflow Considerations

Tips & Tricks

The Dendritic Pattern with flake-parts

The Dendritic Pattern with flake-parts

Flake-Parts

The “Top-Level” (flake):

Advanced Hardening with `nix-mineral` (Community Project)

The Core of a NixOS System: `system.build.toplevel`

The “Top-Level” (`flake`):

The “Per-System” (`perSystem`)

Prep `configuration.nix`

Prep `configuration.nix`

GnuPG & `gpg-agent` on NixOS