![\"trees2\"](\"https://saylesss88.github.io/images/trees2.cleaned.png\")
Functions are the building blocks of Nix, appearing everywhere in Nix\nexpressions and configurations. Mastering them is essential for writing\neffective Nix code and understanding tools like NixOS and Home Manager. This\nchapter explores how Nix functions work, focusing on their single-argument\nnature, currying, partial application, and their role in modules.
\nA Nix Function is a rule that takes an input (called an argument) and\nproduces an output based on that input. Unlike many programming languages,\nNix functions are designed to take exactly one argument at a time. This unique\napproach, combined with a technique called currying, allows Nix to simulate\nmulti-argument functions in a flexible and reusable way.
\nThe Nix expression evaluator has a bunch of functions and constants built in:
\ntoString 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)
Nix functions are anonymous (lambdas) (e.g., x: x + 2), and technically take a\nsingle parameter. However, that single parameter is very often an attribute set,\nallowing you to effectively pass multiple named inputs by destructuring (e.g.,\n{ arg1, arg2 }: arg1 + arg2).
Type the parameter name, followed by a colon, and finally the body of the\nfunction.
\nnix-repl> param: param * 2\n<<lambda @ <<string>>:1:1>>\n\nnix-repl> (param: param * 2) 2\n4\nThe above example shows that everything in Nix returns a value. When you call a\nfunction directly (without first assigning the function itself to a variable),\nthe result of that call is immediately evaluated and displayed/used.
\nIn order to make our function reusable and be able to pass different values at\ndifferent times we have to assign our function to a variable:
\nnix-repl> twoTimes = param: param * 2\nNow, we can reference our function by it’s name and pass our required parameter:
\nnix-repl> twoTimes\n«lambda @ «string»:1:2»\nnix-repl> twoTimes 2\n4\nnix-repl> twoTimes 4\n8\nWe defined a function param: param * 2 takes one parameter param, and\nreturns param * 2. We then assigned this function to the variable twoTimes.\nLastly, we called the function with a few different arguments showing it’s\nreusability.
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\nname for a value that will be provided when the function is called.
\nRight of the Colon: This is the function body. It’s the expression\nthat will be evaluated when the function is invoked.
\nThink of function arguments as naming values that aren’t known in advance.\nThese names are placeholders that get filled with specific values when the\nfunction is used.
\nExample:
\ngreet = personName: \"Hello, ${personName}!\";\nHere, personName is the argument (the placeholder).
\"Hello, ${personName}!\", is the function body (which uses the\nplaceholder to create the greeting).
When you call the function, (click to see Output):
\ngreet \"Anonymous\"\n~ \"Hello, Anonymous!\"\nThe value \"Anonymous\" is substituted for the personName placeholder within\nthe function body.
This structure is the foundation of all Nix functions, whether simple or\ncomplex.
\nThe simplest form of a Nix function takes a single argument. In Nix, function\ndefinitions like x: x + 1 or personName: \"Hello, ${personName}!\"; are\nanonymous lambda functions. They exist as values until they are assigned to\na variable.
# This is an anonymous lambda function value:\n# x: x + 1\ninc = x: x + 1; # here we assigned our lambda to a variable `inc`\ninc 5\n~ 6\nx is the argument.
x + 1 is the function body.
This straightforward design makes single-argument functions easy to understand\nand use. But what if you need a function that seems to take multiple arguments?\nThat’s where currying comes in.
\nTo create functions that appear to take multiple arguments, Nix uses currying.\nThis involves nesting single-argument functions, where each function takes one\nargument and returns another function that takes the next argument, and so on.
\nnix-repl> multiply = x: (y: x*y)\nnix-repl> multiply\n«lambda»\nnix-repl> multiply 4\n«lambda»\nnix-repl> (mul 4) 5\n20\nWe defined a function that takes the parameter x, the body returns another\nfunction. This other function takes a parameter y and returns x*y.\nTherefore, calling multiply 4 returns a function like: x: 4*y. In turn, we\ncall the returned function with 5, and get the expected result.
# concat is equivalent to:\n# concat = x: (y: x + y);\nconcat = x: y: x + y;\nconcat 6 6 # Evaluates to 12\n12\nHere, 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\nfunctions.
Here’s how it works step by step:
\nWhen you call concat 6, the outer function binds x to 6 and returns a\nnew function: y: 6 + y.
When you call that function with 6 (i.e., concat 6 6), it computes\n6 + 6, resulting in 12.
This chaining is why Nix functions are so powerful—it allows you to build\nflexible, reusable functions.
\nCurrying is a powerful feature in Nix that enables you to partially apply\narguments to functions, leading to increased reusability. This behavior is a\ndirect consequence of Nix functions being “first-class citizens” (a concept\nwe’ll delve into later), and it proves invaluable for decomposing intricate\nlogic into a series of smaller, more focused functions.
\nKey Insight: Every colon in a function definition separates a single\nargument from its function body, even if that body is another function\ndefinition.
\nLet’s explore currying with a more relatable example in the nix repl:
nix repl\nnix-repl> greeting = prefix: name: \"${prefix}, ${name}!\";\n\nnix-repl> greeting \"Hello\"\n<<lambda @ <<string>>:1:10>> # partial application returns a lambda\n\nnix-repl> greeting \"Hello\" \"Alice\"\n\"Hello, Alice!\" # providing both arguments returns the expected result\nThis function is a chain of two single-argument functions:
\nThe outer function takes prefix (e.g. \"Hello\") and returns a function\nthat expects name.
The inner function takes name (e.g. \"Alice\") and combines it with\nprefix to produce the final string.
Thanks to lexical scope (where inner functions can access variables from\nouter functions), the inner function “remembers” the prefix value.
Because of currying, you can apply arguments to a Nix function one at a\ntime. This is called partial application. When you provide only some of the\nexpected arguments, you get a new function that “remembers” the provided\narguments and waits for the rest.
\n\n\n[!EXAMPLE]
\nUsing our
\ngreetingfunction again:\nnix repl\nnix-repl> greeting = prefix: name: \"${prefix}, ${name}!\";\nnix-repl> helloGreeting = greeting \"Hello\";\nnix-repl> helloGreeting \"Alice\"\n\"Hello, Alice\"\n\n
\n- \n
helloGreetingis now a new function. It has already received theprefix\nargument (\"Hello\"), when we provide the second argument we get\n\"Hello, Alice!\"
Benefits of Partial Application:
\nPartial application provides significant benefits by enabling you to derive\nspecialized functions from more general ones through the process of fixing\ncertain parameters. Additionally, it serves as a powerful tool for adapting\nexisting functions to fit the precise argument requirements of higher-order\nfunctions like map and filter.
In the context of Nix, the phrase “Nix treats functions as first-class citizens”\nmeans that functions in Nix are treated as values, just like numbers, strings,\nor lists. They can be manipulated, passed around, and used in the same flexible\nways as other data types. This concept comes from functional programming and has\nspecific implications in Nix.
\nWhat It Means in Nix
\n\n\n[!EXAMPLE]
\n\ngreet = name: \"Hello, ${name}!\";\n\n
\n- Here, greet is a variable that holds a function.
\n
\n\n[!EXAMPLE]
\n\napplyTwice = f: x: f (f x);\ninc = x: x + 1;\napplyTwice inc 5 # Output: 7 (increments 5 twice: 5 → 6 → 7)\n~ 7\n\n
\n- Here, applyTwice takes a function
\nf(in this case,inc) and applies it to\nxtwice.
\n\n[!EXAMPLE]
\n\ngreeting = prefix: name: \"${prefix}, ${name}!\";\nhelloGreeting = greeting \"Hello\"; # Returns a function\nhelloGreeting \"Alice\" # Output: \"Hello, Alice!\"\n~ \"Hello, Alice!\"\n\n
\n- The greeting function returns another function when partially applied with\nprefix.
\n
\n\n[!EXAMPLE]
\n\nmyFuncs = {\n add = x: y: x + y;\n multiply = x: y: x * y;\n};\nmyFuncs.add 3 4 # Output: 7\n~ 7\n\n
\n- \n
\nHere, functions are stored as values in an attribute set.
\n- \n
\nTo try this in the
\nrepljust remove the semi-colon (;)
Why This Matters in Nix:
\nThis functional approach is fundamental to Nix’s unique build system. In Nix,\npackage builds (called derivations) are essentially functions. They take\nspecific inputs (source code, dependencies, build scripts) and\ndeterministically produce outputs (a built package).
\nThis design ensures atomicity: if a build does not succeed completely and\nperfectly, it produces no output at all. This prevents situations common in\nother package managers where partial updates or corrupted builds can leave your\nsystem in an inconsistent or broken state.
\nMany NixOS and Home Manager modules are functions, and their first-class status\nmeans they can be combined, reused, or passed to other parts of the\nconfiguration system.
\nNow that we understand the “first-class” nature of Nix Functions let’s see how\nthey fit into NixOS and Home Manager modules.
\nIt’s crucial to understand that most NixOS and Home Manager modules are\nfundamentally functions.
\nThese module functions typically accept a single argument: an attribute set\n(remember this, it’s important to understand).
\nExample:
\nA practical NixOS module example for Thunar with plugins:
\n# thunar.nix\n{pkgs, ...}: {\n programs = {\n thunar = {\n enable = true;\n plugins = with pkgs.xfce; [\n thunar-archive-plugin\n thunar-volman\n ];\n };\n };\n}\nconfiguration.nix or\nequivalent, shown here for completeness.# configuration.nix\n# ... snip ...\nimports = [ ../nixos/thunar.nix ];\n# ... snip ...\nThis is actually a pretty good example of with making it a bit harder to\nreason where the plugins are from. You might instinctively try to trace a path\nlike programs.thunar.plugins.pkgs.xfce because you saw pkgs.xfce in the\nwith statement. But that’s now how with works. The pkgs.xfce path exists\noutside the plugins list, defining the source of the items, not their\nnested structure within the list.
To follow best practices you could write the above plugins section as:
\nplugins = [\n pkgs.xfce.thunar-archive-plugin\n pkgs.xfce.thunar-volman\n];\npkgs and each will\nresolve to a derivation.\nconfiguration.nix it would be a bit\nmore confusing to trace. Explicitness is your friend with Nix and\nmaintaining reproducability. with isn’t always bad but should be avoided\nat the top of a file for example to bring nixpkgs into scope, use let\ninstead.The entire module definition is a function that takes one argument (an attribute\nset):{ pkgs, ... }. When this module is included in your configuration, the\nNixOS module system calls this function with a specific attribute set. This\nattribute set contains the available packages (pkgs), and other relevant\ninformation. The module then uses these values to define parts of your system.
For this example we will build the Hello derivation from the Nix Pills series.
\nCreate an autotools.nix with the following contents:
pkgs: attrs: let\n defaultAttrs = {\n builder = \"${pkgs.bash}/bin/bash\";\n args = [./builder.sh];\n baseInputs = with pkgs; [\n gnutar\n gzip\n gnumake\n gcc\n coreutils\n gawk\n gnused\n gnugrep\n binutils.bintools\n ];\n buildInputs = [];\n system = builtins.currentSystem;\n };\nin\n derivation (defaultAttrs // attrs)\nLet’s create the hello derivation:
\nlet\n pkgs = import <nixpkgs> {};\n mkDerivation = import ./autotools.nix pkgs;\nin\n mkDerivation {\n name = \"hello\";\n src = ./hello-2.12.1.tar.gz;\n }\nautotools.nixAnd finally the builder.sh that autotools.nix declares for the args\nattribute:
#!/bin/bash\nset -e\nunset PATH\nfor p in $buildInputs $baseInputs; do\n export PATH=$p/bin${PATH:+:}$PATH\ndone\n\ntar -xf $src\n\nfor d in *; do\n if [ -d \"$d\" ]; then\n cd \"$d\"\n break\n fi\ndone\n\n./configure --prefix=$out\nmake\nmake install\nWhen you write:
\nmkDerivation = import ./autotools.nix pkgs;\nimport ./autotools.nix: This evaluates the autotools.nix file. Because it\nstarts with pkgs: attrs: ..., it means that autotools.nix evaluates to a\nfunction that expects one argument named pkgs.
... pkgs: We are immediately calling that function (the one returned by\nimport ./autotools.nix) and passing it our pkgs variable (which is the\nresult of import <nixpkgs> {}).
This illustrates the concept of Currying in Nix:
\nThe function defined in autotools.nix (pkgs: attrs: ...) is a curried\nfunction. It’s a function that, when given its first argument (pkgs), returns\nanother function (which then expects attrs).
The result of import ./autotools.nix pkgs is that second, inner function:\nattrs: derivation (defaultAttrs // attrs). This inner function is then bound\nto the mkDerivation variable, making it ready to be called with just the\nspecific 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\n # ... defaultAttrs definition ...\nin\n derivation (defaultAttrs // attrs)\nattrs Represents:Once autotools.nix has received its pkgs argument (and returned the inner\nfunction), this inner function is waiting for its final argument, which we\ncall attrs.
attrs is simply an attribute set (a key-value map in Nix). It’s designed to\nreceive all the specific properties of the individual package you want to\nbuild using this helper.
attrs is Used:Look at the final line of autotools.nix:\nderivation (defaultAttrs // attrs).
The // operator in Nix performs an attribute set merge. It takes all\nattributes from defaultAttrs and combines them with all attributes from\nattrs.
Crucially, if an attribute exists in both defaultAttrs and attrs, the\nvalue from attrs (the second operand) takes precedence and overrides the\ndefault value.
hello derivation, we call mkDerivation like this: mkDerivation {\n name = \"hello\";\n src = ./hello-2.12.1.tar.gz;\n }\nThe attribute set { name = \"hello\"; src = ./hello-2.12.1.tar.gz; } is what\ngets passed as the attrs argument to the mkDerivation function (which,\nremember, is the inner function returned by autotools.nix).
When derivation (defaultAttrs // attrs) is evaluated for “hello”, the name\nand src provided in the attrs set will be merged with all the\ndefaultAttrs (like builder, args, baseInputs, etc.).
In summary:
\nThe pkgs argument configures the general environment and available tools for\nthe builder.
The attrs argument is where you provide the unique details for each specific\npackage you intend to build using this autotools.nix helper. It allows you\nto specify things like the package’s name, source code, version, and any\ncustom build flags, while still benefiting from all the sensible defaults\nprovided by autotools.nix. This separation makes autotools.nix a reusable\nand flexible “template” for creating derivations.
Having explored the fundamental nature of functions in Nix, we can now see this\nconcept applies to more complex areas like NixOS configuration and derivations.\nIn the next chapter,\nNixOS Modules Explained.\nWe will learn about NixOS Modules which are themselves functions most of the\ntime.
\n![\"guy](\"https://saylesss88.github.io/../images/guy_fawks.png\")
Securing your NixOS system begins with a philosophy of minimalism, explicit\nconfiguration, and proactive control. As desktop Linux attracts more novice\nusers, it has become an increasingly valuable target for attackers. This makes\nit crucial to adopt security best practices early to protect your desktop from\ncommon attack vectors and to avoid configuration mistakes that could expose\nvulnerabilities.
\n\n\nI am not a security expert. This guide presents various options for hardening\nNixOS, but it is your responsibility to evaluate whether each\nadjustment suits your specific needs and environment. Security hardening and\nprocess isolation can introduce stability challenges, compatibility issues, or\nunexpected behavior. Additionally, these protections often come with\nperformance tradeoffs. Always conduct thorough research, there are no plug and\nplay one size fits all security solutions.
\n
\n\nThat said, I typically write about what I’m implementing myself to deepen\nunderstanding and share what works for me.
\n--Sourcemeans the proceeding\nparagraph came from--Source, you can often click to check for yourself. If\nyou use some common sense with a bit of caution you could end up with a more\nsecure NixOS system that fits your needs.
\n\nMuch of this guide draws inspiration or recommendations from the well-known\nLinux Hardening Guide\nby Madaidan’s Insecurities. Madaidan’s work is widely regarded in technical\nand security circles as one of the most comprehensive and rigorously\nresearched sources on practical Linux security, frequently cited for its depth\nand actionable advice. For example, much of the original basis for hardening\nfor nix-mineral came from this\nguide as well. This can be a starting point but shouldn’t be blindly followed\neither, always do your own research, things change frequently. Madaidan is\nalso a contributor to both\nKicksecure and\nWhonix.
\n
For an article with apposing perspectives, see\ndebunking-madaidans-insecurities.\nWe can learn from both and hopefully find something in between that is closer to\nthe truth.
\n\n\n❗ Note on SELinux and AppArmor: While NixOS can provide a high degree of\nsecurity through its immutable and declarative nature, it’s important to\nunderstand the limitations regarding Mandatory Access Control (MAC)\nframeworks. Neither SELinux nor AppArmor are fully supported or widely used in\nthe NixOS ecosystem. You can do a lot to secure NixOS but if anonymity and\nisolation are paramount, I recommend booting into a\nTails USB stick. Or using\nWhonix.
\n
☝️ The unique file structure of NixOS, particularly the immutable /nix/store,\nmakes it difficult to implement and manage the file-labeling mechanisms that\nthese frameworks rely on. There are ongoing community efforts to improve\nsupport, but as of now, they are considered experimental and not a standard part\nof a typical NixOS configuration. For an immutable distro that implements\nSELinux by default at a system level as well as many other hardening techniques,\nsee Fedora secureblue.
Containers and VMs are beyond the scope of this chapter but can also enhance\nsecurity and sandboxing if configured correctly. See\nRunning NixOS in a VM for more\ndetails on running NixOS in a Secureblue VM for additional security.
\nIt’s crucial to document every change you make. By creating smaller,\nfeature-complete commits, each with a descriptive message, you’re building a\nclear history. This approach makes it far simpler to revert a breaking change\nand quickly identify what went wrong. Over time, this discipline allows you to\ncreate security-focused checklists and ensure all angles are covered, building a\nmore robust and secure system.
\nDon’t rely on single solutions or products, develop processes and defense in\ndepth. Think ahead and fail securely so that a single failure doesn’t mean total\ninsecurity.
\nAttackers often monitor the latest Linux CVEs (Common Vulnerabilities and\nExposures) and check if and when specific distributions like NixOS have\nimplemented fixes. The unstable branch will receive the security patches and\nfixes faster than stable which is another thing to keep in mind.
\nCheck out the\nHardening NixOS Baseline Hardening README\nfor baseline hardening recommendations and best practices.
\nThere is something to be said about the window manager you use. GNOME, KDE\nPlasma, and Sway secure privileged Wayland protocols like screencopy. This means\nthat on environments outside of GNOME, KDE, and Sway, applications can access\nscreen content of the entire desktop. This implicitly includes the content of\nother applications. It’s primarily for this reason that Silverblue, Kinoite,\nSericea, and COSMIC images are recommended. COSMIC has plans to fix this.\n–secureblue Images
\n\n\nThis is a little misleading, hyprland takes a different approach that also\nworks. Disabling wlroots portal does not block screencopy for all apps, but\nonly with sandboxed clients. Unsandboxed apps (like
\ngrim) can still access\next-image-copy-capture directly on Sway without going through the portal.
For example, to disable Xwayland for sway on home-manager you would add:
\nwayland.windowManager.sway = {\n enable = true;\n extraConfig = ''\n xwayland disable\n '';\n}\nYou can explicitly disable xdg-desktop-portal-wlr with systemd in your\nconfiguration.nix like this:
# configuration.nix\nsystemd.user.services.\"xdg-desktop-portal-wlr\" = {\n enable = false; # Masks/stops the wlr service\n};\nxdg.portal.wlr.enable = false;\nPrivilege escalation: The unauthorized act of gaining elevated permissions\nrather than legitimate, controlled privilege use. It’s a very common tactic that\nthreat actors use to take over a system, steal data, delete files, and more.
\nProcesses to protect against Privilege escalation
\nAdopt the principle of least privilege, only giving users the permissions that\nthey require to perform their duties.
\nHarden your system: Minimize the attack surface, use strong passwords, and\nfollow best practices.
\nMonitor relevant sources such as the\nNIST National Vulnerability Database,\nNixOS Security Advisories,\nand\nNixOS Discourse Security\nSo you’ll know the latest CVEs and vulnerabilities in Linux and NixOS.
\nWhile not made for NixOS the\nlinPEAS Privilege Escalation Awesome Script\ngives you some useful info such as active capabilities and potential risks.
\nRemove unnecessary SUID binaries to reduce the attack surface.
\nUse after Free/Double free:
\nUse-After-Free (UAF) is a type of software vulnerability that occurs in\nmemory unsafe languages (C C++) when a program continues to use a memory\nlocation after it has been freed or deallocated.
\nDouble free: is a flaw where a program frees the same memory block twice\nusing free() or delete, leading to undefined behavior and potential\nexploitation.
Mitigation techniques include the use of hardened allocators such as\nhardened_malloc, which improve memory management to detect and prevent UAF and\ndouble-free bugs. Recent versions of glibc also incorporate built-in checks to\ncatch double frees.
Unauthorized Access:
\nUnauthorized access is the entry or use of your system, networks, or data by\nindividuals without permission. It’s a common way for adversaries to exfiltrate\ndata, execute malicious code, and cause damage.
\nProtections against Unauthorized Access
\nStrong Passwords, MFA, and robust Secrets management. In 2025, 22% of breaches\ninvolved stolen credentials overall; in basic web app attacks, 88% used stolen\ncredentials.\n–StrongDM data-breach-statistics
\nClose unused ports with a Firewall
\nEncrypt data in transit and at rest
\nWatch your Logs, and deploy intrusion detection systems such as AIDE.
\nSQL Injection CWE, SQL\ninjection is the most common critical web application vulnerability.
\nMisconfiguration
\nWith many new users trying NixOS, misconfiguration is common and an easy way\nfor an attacker to gain control over your system.
\nIt is recommended to start slowly and try to ensure that you understand your\nconfiguration. Avoid copy-pasting config files that you don’t understand yet.
\nZero Day Exploits:
\nThe term “Zero-Day” refers to a security vulnerability or flaw that is unknown\nto the software developers or security teams, meaning they have had zero days to\ncreate a patch or fix for it. This term is often associated with concepts such\nas Vulnerabilities, Exploits, and Threats, and it’s important to distinguish\namong them:
\nA Zero-Day Vulnerability is a previously undiscovered security weakness or\nflaw in software that malicious actors can exploit.
\nA Zero-Day Exploit describes the specific method or technique attackers\nuse to take advantage of that vulnerability to compromise a system.
\nA Zero-Day Attack happens when malicious actors launch an attack using a\nzero-day exploit before the software vendor has had a chance to patch or fix\nthe vulnerability.
\nProject Zero’s 0day spreadsheet.\nYou’ll see that a majority of zero-days are Memory Corruption bugs.
\nBegin with NixOS’s minimal installation image. This gives you a base system with\nonly essential tools and no extras that could introduce vulnerabilities.
\nNixOS’s declarative model makes auditing the installed packages and services\neasy, do so regularly.
\nEncryption is the process of using an algorithm to scramble plaintext data into\nciphertext, making it unreadable except to a person who has the key to decrypt\nit.
\nData at rest is data in storage, such as a computer’s or a servers hard\ndisk.
\nData at rest encryption (typically hard disk encryption), secures the\ndocuments, directories, and files behind an encryption key. Encrypting your data\nat rest prevents data leakage, physical theft, unauthorized access, and more as\nlong as the key management scheme isn’t compromised.
\nThe\nNSA, CISA, and NIST warn\nthat nation-state actors are likely stockpiling encrypted data now, preparing\nfor a future when quantum computers could break today’s most widely used\nencryption algorithms. Sensitive data with long-term secrecy needs is\nespecially at risk.
\nThis is a wake-up call to use the strongest encryption available today and to\nplan early for post-quantum security.
\nNIST First 3 Post-Quantum Encryption Standards\nOrganizations and individuals should prepare to migrate cryptographic systems\nto these new standards as soon as practical.
\nThey chose\nFour Quantum-Resistant Cryptographic Algorithms\nwarning that public-key cryptography is especially vulnerable and widely used\nto protect digital information.
\nUse LUKS encryption to protect your data at rest, the following guide is a\nminimal disko encrypted installation:\nEncrypted Install
\nNixpkgs cooldowns, this\nis a great addition after all of the AUR compromises. “nixpkgs-weekly still updates once a\nweek, but deliberately introduces a seven-day “cooldown” period, updating to a\nnew revision of Nixpkgs released by upstream only after seven days have elapsed.\nThis introduces a buffer period where major vulnerabilities or attacks can be\nidentified prior to it arriving in our users’ hands.“
\nCheckout cooldowns.dev for more info on cooldowns.
\n\n\nThe 2025 Edgescan study examined full-stack applications and found that\none-third contained critical or severe vulnerabilities, putting them at risk.\nOver 45% of large enterprises leave unresolved vulnerabilities for more than a\nyear. This shows the necessity of containing your apps in sandboxes when\npossible.\n–edgescan Vulnerability Report
\n
\n\n⚠️ For system security it is strongly advised to not install\nproprietary,\nnon-freedom software.\nInstead, use of\nFree Software is\nrecommended –Kicksecure
\n
# configuration.nix\nnixpkgs.config.allowUnfree = false;\nTo explicitly disable it for flakes:
\n# ...snip...\npkgs = import nixpkgs {\n system = \"x86_64-linux\";\n config = {\n allowUnfree = false;\n };\n};\n# ...snip...\nMost users don’t fully understand that running any software without sandboxing\ngives it unrestricted access to their user data and system resources. There is a\nwidespread lack of awareness that Linux apps generally run with the full\npermissions of the user. It’s easy to overlook the fact that “trusted source”\ndoesn’t mean “safe to run uncontained”. –summarized from kicksecure docs
\nPre-Install Recommendations
\nWhen installing software, first check\nsearch.nixos, and follow the Homepage\nlink to ensure that said package is maintained.
For example, when I search for doas, and go to the\nHomepage link, I can see that the most\nrecent commit was made 3 years ago. For certain software this might not be an\nissue but doas isn’t one of them.
Looking at the sudo-rs\nHomepage I can see that it\nwas updated yesterday (11-19-25) and might be a better alternative. It’s\nmaintained and written in a memory safe language.
For critical apps like sudo, you should also check for vulnerabilities in said\nsoftware. If you did so for sudo-rs, you’d see\nCVE-2025-64170 and see that\nit’s been patched. You can then look at the\nsudo-rs package.nix\nto ensure that the versions match. (As of 11-20-25 they match).
nixpkgs-unstable Security Overview
\nnixpkgs-unstable tracks the master branch of the Nixpkgs repo and is\nconstantly updated.
This branch gets security updates faster, patching vulnerabilities faster.
\nSince it’s a rolling-release, packages are less thoroughly tested. This\nincreases the risk of new, undiscovered bugs or regressions. Some of which\ncould have security implications.
\nThe packages are generally the most recent upstream versions, which is\nimportant for security-sensitive software like browsers and kernels, as old\nversions may have publicly known, unpatched vulnerabilities.
\nAs the name states, nixpkgs-unstable is less stable and an update is more\nlikely to cause your system to fail to build due to breaking changes in Nix\nexpressions.
I personally use unstable for everything, but I don’t mind having to fix\nissues that arise.
\nStable (e.g., nixos-24.05) Security Overview
Stable Nixpkgs channels correspond to point release (e.g., released every 6\nmonths) and are supported for a limited period (typically one month past the\nnext release).
\nStable channels generally only receive conservative bug and security fixes.\nMajor version bumps for features are typically avoided to maintain “stability\nagainst deliberate changes”, which means you won’t get the latest upstream\nfeatures or general bug fixes.
\nWhile critical security updates are backported quickly, updates for less\ncritical packages may be slower or not happen at all if they require a\nsignificant refactoring or version bump.
\nStable channels are generally more stable, meaning updates are less likely to\nintroduce breaking changes to your configuration or system environment.
\nMany packages will be older versions. If a critical security vulnerability\nrequires a major upstream version update (which is often avoided in a stable\nchannel), the maintainers must backport the patch, a process which can\nintroduce its own set of risks and delays.
\nWhat should you use?
\nThe primary security trade-off is between patching speed for known\nvulnerabilities and stability/exposure to new bugs:
\nChoose unstable if you prioritize getting the latest security fixes\n(especially for end-user apps like browsers) as soon as they are available\nupstream, accepting a higher risk of non-security-related system breakage or\nnew, undiscovered bugs.
Choose stable if you prioritize system predictability and stability, relying\non dedicated backports for critical vulnerabilities, while accepting that\nnon-critical security and bug fixes will be delayed or absent until the next\nmajor release.
A common hybrid approach is to use the stable channel as the base for the OS\nand selectively pin specific packages from unstable to ensure they receive\nrapid security updates.
With flakes it’s easy to add both stable and unstable as flake inputs and\naccess each with some simple logic.
{\n description = \"NixOS configuration with two or more channels\";\n\n inputs = {\n nixpkgs.url = \"github:NixOS/nixpkgs/nixos-25.05\";\n nixpkgs-unstable.url = \"github:NixOS/nixpkgs/nixos-unstable\";\n };\n\n outputs =\n { nixpkgs, nixpkgs-unstable, ... }:\n {\n nixosConfigurations.\"your-host\" = nixpkgs.lib.nixosSystem {\n modules = [\n {\n nixpkgs.overlays = [\n (final: prev: {\n unstable = nixpkgs-unstable.legacyPackages.${prev.system};\n # use this variant if unfree packages are needed:\n # unstable = import nixpkgs-unstable {\n # inherit prev;\n # system = prev.system;\n # config.allowUnfree = true;\n # };\n })\n ];\n }\n ./configuration.nix\n ];\n };\n };\n}\nconfiguration.nix.Now you can specify which packages are to be installed with which channel like\nso:
\n# configuration.nix\n{ pkgs, ... }:\n{\n environment.systemPackages = [\n pkgs.firefox\n pkgs.unstable.helix\n ];\n # ...\n}\nReplacing sudo with run0
\n\n\nThe point here is to avoid using the setuid binary (
\nsudo),run0is a\nwrapper oversystemd-runwhich speaks over Inter-process Communication\nMechanisms (IPC) to PID1 which is considered safer than running a setuid\nbinary. We separate our daily user from administration tasks and authenticate\nthrough our admin account. This reduces the attack surface by removing sudo as\nwell as reduces the risk of local privilege escalation.
IPC is the mechanism that allows processes to communicate. There are two\nmethods of IPC, shared memory and message passing. An OS can implement both.
\nPID 1 is the first userspace process the kernel starts (the init system),\nwhich becomes the ancestor and reaper of all other processes; because it runs\nas root, is always present, and controls the system lifecycle, any bugs or\ndesign issues in PID 1 have outsized security impact and can translate into\nsystem-wide compromise or denial of service.
\nUsing run0 removes of these classes of\nattacks
The following lists some of the downsides\nkicksecure vs secureblue
\nrun0 is not a SUID, it asks the service manager to invoke a command or shell\nunder the target user’s UID. The target command is invoked in an isolated exec\ncontext, 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\nlow-privilege user to execute a program with the permissions of the file’s\nowner, which is most often the powerful root user.
\nFor granting limited, controlled privilege escalation to apps, the primary\nchoices are broadly between traditional setuid/setgid permissions and more\nmodern Linux capabilities. Jump to Capabilities
\n\nUse the following command to find all SUID binaries:
\nsudo find / -perm -4000 -type f -ls 2>/dev/null\nThe setuid permission is dangerous because it creates a privilege escalation\npathway that can be exploited for malicious purposes.
Temporary Root Access: When a file has the setuid bit set and is owned by\nroot, any user who executes that program instantly and temporarily gains the\nfull power of the root user while the program runs.
If a setuid program (such as passwd, or sudo) contain a security flaw,\nsuch as a buffer overflow (Common in C) or improper input validation, an\nattacker can exploit the flaw.
Since the program is running with root privileges, the attacker can execute\nshell code or commands with root access, completely compromising the entire\nsystem.
\nNormally the root user (UID 0) gets unrestricted access to almost everything on\nthe entire system.
\nI rebuild/update way too often to completely separate the accounts and allow no\nadmin tasks for my daily user. That may be a better option for servers, etc.
\nCreate an admin user for administrative tasks and remove your daily user from\nthe wheel group, and disable the sudo, su, and pkexec SUIDs:
(Edited: 2026-02-01): Changed from disabling the setuid bits to disabling the\nwrapper entirely. Caught by SuperSandro2000
{ config, pkgs, lib }:\n{\nusers.users.admin = {\n isNormalUser = true;\n description = \"System administrator\";\n extraGroups = [ \"wheel\" ]; # wheel = sudo\n # run `mkpasswd --method=yescrypt` and replace \"changeme\" w/ the result\n initialHashedPassword = \"changeme\"; # change with `passwd admin` later\n openssh.authorizedKeys.keys = [\n # (optional) paste your SSH public key here\n # \"ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI...\"\n ];\n };\n users.groups.admin = {};\n users.mutableUsers = false;\n\n # --------------------------------------------------------------------\n # 2. Existing daily user – remove from wheel, keep everything else\n # --------------------------------------------------------------------\n users.users.daily = {\n isNormalUser = true;\n description = \"Daily driver account\";\n extraGroups = lib.mkForce [ \"networkmanager\" \"audio\" \"video\" ]; # keep useful groups\n initialHashedPassword = \"changeme\";\n # Remove `wheel` by *not* listing it (mkForce overrides any default)\n };\n users.groups.daily = {};\n\nsecurity = {\n# alias sudo = 'run0'\nrun0.enableSudoAlias = true;\npolkit.enable = true;\n# Disable sudo\nsudo.enable = false;\nwrappers = {\n su.enable = lib.mkForce false;\n sudoedit.enable = lib.mkForce false;\n sg.enable = lib.mkForce false;\n fusermount.enable = lib.mkForce false;\n fusermount3.enable = lib.mkForce false;\n pkexec.setuid = lib.mkForce false;\n newgrp.setuid = lib.mkForce false;\n newgidmap.setuid = lib.mkForce false;\n newuidmap.setuid = lib.mkForce false;\n # `mount` Needed for `fileSystems.options`\n # mount.enable = lib.mkForce false;\n # Optional: if you disable mount, disable umount as well\n # umount.enable = lib.mkForce false;\n};\n# Or hyprlock, required for swaylock to accept your password\npam.services.swaylock = {\n text = ''\n auth include login\n account include login\n password include login\n session include login\n '';\n };\n};\nThe security.wrappers... removes the setuid bit making the commands unusable\nremoving the SUID vulnerabilities for su and pkexec. You can find the other\nSUID wrappers in /run/wrappers/bin/, such as fusermount and more.
SUID’s that can be disabled:
\numount: Allows unprivileged users to unmount devices listed in your fstab.
mount: Same as above but for mounting. It is recommended to set\nfileSystems.\"/boot\".options = [ \"fmask=0077\" \"dmask=0077\" ]; this won’t work\nwithout 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\nfilesystems. Can be disabled if you don’t use FUSE (e.g., Appimages, etc.)
newuidmap, newgidmap: Used for user namespace creation (Often used for\nunprivileged containers). (Disable if you don’t use unprivileged\ncontainers/namespaces)
Never Disable:
\nunix_chkpwd: This is a core PAM helper to securely check user passwords\nagainst the root-readable /etc/shadow.Check again which SUID binaries are active:
\nsudo find / -perm -4000 -type f -ls 2>/dev/null\n# Example\n-rwsr-xr-x root root /run/wrappers/bin/fusermount\n ^-- This 's' means setuid bit is set\nls -la /run/wrappers/bin/\n# Or\nfind /run/wrappers -perm -4000 -ls\nOnly enable the wrappers you actually use!
\nYou will have to use run0 to authenticate your daily user, for example:
run0 nixos-rebuild switch --flake .\nSince run0 doesn’t cache results and nixos-rebuild calls on Polkit 3 times,\nso on every rebuild, you will be asked for your password 3 times which isn’t\nideal. I found the following workaround that will only ask for your password\nonce.
Add the following to your configuration.nix, replacing user-name with your\nusername:
security.polkit.extraConfig = ''\n polkit.addRule(function(action, subject) {\n if (subject.user == \"user-name\") {\n if (action.id.indexOf(\"org.nixos\") == 0) {\n polkit.log(\"Caching admin authentication for single NixOS operation\");\n return polkit.Result.AUTH_ADMIN_KEEP;\n }\n }\n });\n '';\nCreate a zsh function for easy access:
\n# zsh.nix\n#...snip...\ninitContent = ''\n fr() {\n run0 nixos-rebuild switch --flake \"/home/$USER/flake#\"$(hostname)\n }\n'';\nNeedless to say, this is less secure but much more convenient than entering your\npassword 3 times on every single rebuild.
\nWithout the pam settings for swaylock, it won’t accept your password to log\nback in.
run0 Usage Example
\nWhen you are in a privileged shell, run0 changes the color of the background\nto red to remind you of this.
Example creating a user:
\nrun0
adduser admin
usermod -aG wheel admin
passwd admin
exit
reboot
This is just an example, since we manage our users declaratively the user\ncreated would be discarded on the next rebuild because of the\nusers.mutableUsers = false; setting. You could of course change this to true\nto manage your users imperatively but I don’t recommend it.
One way to help get rid of setuid binaries is to replace them with capabilities.\nI personally only remove the SUID bit and don’t try to replace with capabilities\nas of now. You can still use the commands from security.wrappers such as\nrun0 su -.
Capabilities provide a subset of what is available to root to a process. This\nbreaks up root privileges into smaller units that can independently grant access\nto processes. This reduces the full set of privileges, decreasing the risk of\nexploitation.
\n(This is just an example):
\n{\n # a setuid root program\n doas =\n { setuid = true;\n owner = \"root\";\n group = \"root\";\n source = \"${pkgs.doas}/bin/doas\";\n };\n\n # a setgid program\n locate =\n { setgid = true;\n owner = \"root\";\n group = \"mlocate\";\n source = \"${pkgs.locate}/bin/locate\";\n };\n\n # a program with the CAP_NET_RAW capability\n ping =\n { owner = \"root\";\n group = \"root\";\n capabilities = \"cap_net_raw+ep\";\n source = \"${pkgs.iputils.out}/bin/ping\";\n };\n}\nList the highest capability number for your kernel with:
\ncat /proc/sys/kernel/cap_last_cap\n# Output:\n40\nList available Linux capabilities:
\ncapsh --print\nList processes:
\nps\n# Example Output\nPID TTY TIME CMD\n8063 pts/1 02 zsh\ncat /proc/8063/status | grep Cap\n# Output\nCapInh: 0000000800000000\nCapPrm: 0000000000000000\nCapEff: 0000000000000000\nCapBnd: 000001ffffffffff\nCapAmb: 0000000000000000\ncapsh --decode=000001ffffffffff\n# Output\n0x000001ffffffffff=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\ncap_net_raw: Allows the program to use raw and unbuffered network sockets,\nwhich is what ping and mtr-packet need to send ICMP packets.
cap_sys_admin: Grants a variety of system administration operations, including\nthe ability to perform FUSE mounts. This is a powerful capability, but it’s\nstill more restrictive than full root SUID.
+ep: This is crucial. It stands for:\ne (Effective): The set of capabilities actually used by the process when\nrunning.
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\nprivilege, significantly reducing the attack surface compared to traditional\nSUID binaries.
\nImpermanence, especially when using a tmpfs as the root filesystem, provides\nseveral significant security benefits. The core principle is that impermanence\ndefeats persistence, a fundamental goal for any attacker.
When you use a root-as-tmpfs setup on NixOS, the boot process loads the entire\noperating system from the read-only Nix store into a tmpfs in RAM. The mutable\ndirectories, such as /etc and /var, are then created on this RAM disk. When\nthe system is shut down, the tmpfs is wiped, leaving the on-disk storage\nuntouched and secure.
This means you get a fresh, secure boot every time, making it much harder for an\nattacker to maintain a presence on your system.
\nEncrypted BTRFS Impermanence Guide\nOnly follow this guide if you also followed the encrypted disko install,\nimpermanence is designed to be destructive and needs to match your config\nexactly.
\nThis is implementing the GrapheneOS/secureblue NTS chrony settings to NixOS:
\n{ config\n, ...\n}:\n{\n services.chrony = {\n enable = true;\n enableNTS = true;\n servers = [\n \"server time.cloudflare.com iburst nts\"\n \"server ntppool1.time.nl iburst nts\"\n \"server nts.netnod.se iburst nts\"\n \"server ptbtime1.ptb.de iburst nts\"\n \"server time.dfm.dk iburst nts\"\n \"server time.cifelli.xyz iburst nts\"\n ];\n # havent worked out the kinks yet\n # extraConfig = ''\n # minsources 3\n # authselectmode require\n\n # # EF\n # dscp 46\n\n # driftfile /var/lib/chrony/drift\n # dumpdir /var/lib/chrony\n # ntsdumpdir /var/lib/chrony\n\n # leapseclist /usr/share/zoneinfo/leap-seconds.list\n # makestep 1.0 3\n\n # rtconutc\n\n # cmdport 0\n\n # noclientlog\n # '';\n };\n}\nEnsure NTS is being used with:
\nsudo chronyc -N authdata\nEnable a UEFI password or Administrator password where it requires\nauthentication in order to access the UEFI/BIOS.
\nSecure Boot helps ensure only signed, trusted kernels and bootloaders are\nexecuted at startup.
\nUseful Resources:
\nPractical Lanzaboote Secure Boot setup for NixOS:\nGuide:Secure Boot on NixOS with Lanzaboote
\nThe Kernel Self Protection Project:
\n\nGiven the kernel’s central role, it’s a frequent target for malicious actors,\nmaking robust hardening essential.
\nNixOS provides a hardened profile that applies a set of security-focused\nkernel and system configurations.
For flakes, you could do something like the following in your\nconfiguration.nix or equivalent to import hardened.nix and enable\nprofiles.hardened:
# configuration.nix\n{ pkgs, inputs, ... }: let\n modulesPath = \"${inputs.nixpkgs}/nixos/modules\";\n\nin {\n imports = [ \"${modulesPath}/profiles/hardened.nix\" ];\n\n}\nThere is a proposal to remove it completely that has gained ground, the\nfollowing thread discusses why:\nDiscourse Thread
\nPR #383438 Proposed removal\nPR.
\nCheck\nhardened.nix\nto see exactly what adding it enables to avoid duplicates and conflicts moving\non. I included this for completeness, the choice is yours if you want to use\nit or not.
\nSee which kernel you’re currently using with:
\n# show the kernel release\nuname -r\n# show kernel version, hostname, and architecture\nuname -a\nShow the configuration of your current kernel:
\nzcat /proc/config.gz\n# ...snip...\n#\n# Compression\n#\nCONFIG_CRYPTO_DEFLATE=m\nCONFIG_CRYPTO_LZO=y\nCONFIG_CRYPTO_842=m\nCONFIG_CRYPTO_LZ4=m\nCONFIG_CRYPTO_LZ4HC=m\nCONFIG_CRYPTO_ZSTD=y\n# end of Compression\n# ...snip...\nThe NixOS Manual\nstates that the default Linux kernel configuration should be fine for most\nusers.
\nThe Linux kernel is typically released under two forms: stable and long-term\nsupport (LTS). Choosing either has consequences, do your research.\nStable vs. LTS kernels
\n\nOR, you can choose the hardened kernel for a kernel that prioritizes\nsecurity over everything else.
\n\n\nExpect breakage when using the hardened kernel.
\nlinux-hardenedcompletely\ndisables\nunprivileged user namespaces, which\nare required for Flatpak, chromium-based browsers, and more.
The linuxPackages_latest_hardened attribute has been deprecated. If you want\nto use a hardened kernel, it is now recommended to use linux_hardened, which\nis aliased to linux_default.kernel.
You can find the latest available hardened kernel packages by searching\npkgs/top-level/linux-kernels.nix.
\nIt is recommended to use linux_hardened without specifying a version, such as:
boot.kernelPackages = pkgs.linuxPackages_hardened;\nlinux_hardened is aliased to the linux_default.kernel.
Note that this not only replaces the kernel, but also packages that are specific\nto the kernel version, such as NVIDIA video drivers. This also removes your\nability to use the .extend kernel attribute, they are only available to\nkernel package sets (e.g., linuxPackages_hardened)
You can inspect\nnixpkgs/pkgs/os-specific/linux/kernel/hardened/patches.json\nto see the metadata of the patches that are applied. You can then follow the\nlinks in the .json file to see the patch diffs.
A tool for checking the security hardening options of the Linux kernel:
\nenvironment.systemPackages = [ pkgs.kernel-hardening-checker ];\nsysctl is a tool that allows you to view or modify kernel settings and\nenable/disable different features.
Check all sysctl parameters against the kernel-hardening-checker\nrecommendations:
sudo sysctl -a > params.txt\nkernel-hardening-checker -l /proc/cmdline -c /proc/config.gz -s ./params.txt\nCheck the value of a specific parameter:
\nsudo sysctl -a | grep \"kernel.kptr_restrict\"\n# Output:\nkernel.kptr_restrict = 2\nCheck Active Linux Security Modules:
\ncat /sys/kernel/security/lsm\n# Output:\nFile: /sys/kernel/security/lsm\ncapability,landlock,yama,bpf,apparmor\nCheck Kernel Configuration Options:
\nzcat /proc/config.gz | grep CONFIG_SECURITY_SELINUX\nzcat /proc/config.gz | grep CONFIG_HARDENED_USERCOPY\nzcat /proc/config.gz | grep CONFIG_STACKPROTECTOR\nSince it is difficult to see exactly what enabling the hardened_kernel does.\nBefore rebuilding, you could do something like this to see exactly what is\nadded:
\nsudo sysctl -a > before.txt\nAnd after the rebuild:
\nsudo sysctl -a > after.txt\nAnd finally run a diff on them:
diff before.txt after.txt\nYou can also diff against after.txt for future changes to avoid duplicates,\nthis seems easier to me than trying to parse through the patches.
security = {\n protectKernelImage = true;\n lockKernelModules = false; # this breaks iptables, wireguard, and virtd\n\n # force-enable the Page Table Isolation (PTI) Linux kernel feature\n forcePageTableIsolation = true;\n\n # User namespaces are required for sandboxing.\n # this means you cannot set `\"user.max_user_namespaces\" = 0;` in sysctl\n allowUserNamespaces = true;\n\n # Disable unprivileged user namespaces, unless containers are enabled\n unprivilegedUsernsClone = config.virtualisation.containers.enable;\n allowSimultaneousMultithreading = true;\n}\nsysctl hardening settings further reinforce kernel-level protections. The\nhardened kernel includes security patches and stricter defaults, but it doesn’t\ncover all runtime tunables. Refer to the above commands to get a diff of the\nchanges.
boot.kernel.sysctl:\nRuntime parameters of the Linux kernel, as set by sysctl(8). Note that the\nsysctl parameters names must be enclosed in quotes. Values may be a string,\ninteger, boolean, or null.
\nCheck what each setting does sysctl-explorer
\nRefer to\nmadadaidans-insecurities#sysctl-kernel\nfor the following settings and their explainations.
\nAlso see the\nKernel Self Protection Projects sysctls
\n boot.kernel.sysctl = {\n \"fs.suid_dumpable\" = 0;\n # prevent pointer leaks\n \"kernel.kptr_restrict\" = 2;\n # restrict kernel log to CAP_SYSLOG capability\n \"kernel.dmesg_restrict\" = 1;\n # Note: certian container runtimes or browser sandboxes might rely on the following\n # restrict eBPF to the CAP_BPF capability\n \"kernel.unprivileged_bpf_disabled\" = 1;\n # should be enabled along with bpf above\n # \"net.core.bpf_jit_harden\" = 2;\n # restrict loading TTY line disciplines to the CAP_SYS_MODULE\n \"dev.tty.ldisk_autoload\" = 0;\n # prevent exploit of use-after-free flaws\n \"vm.unprivileged_userfaultfd\" = 0;\n # kexec is used to boot another kernel during runtime and can be abused\n \"kernel.kexec_load_disabled\" = 1;\n # Kernel self-protection\n # SysRq exposes a lot of potentially dangerous debugging functionality to unprivileged users\n # 4 makes it so a user can only use the secure attention key. A value of 0 would disable completely\n \"kernel.sysrq\" = 4;\n # disable unprivileged user namespaces, Note: Docker, NH, and other apps may need this\n # \"kernel.unprivileged_userns_clone\" = 0; # Set to 1 because it makes NH and other programs fail\n # This should be set to 0 if you don't rely on flatpak, NH, Docker, etc.\n \"kernel.unprivileged_userns_clone\" = 1;\n # restrict all usage of performance events to the CAP_PERFMON capability\n \"kernel.perf_event_paranoid\" = 3;\n\n # Network\n # protect against SYN flood attacks (denial of service attack)\n \"net.ipv4.tcp_syncookies\" = 1;\n # protection against TIME-WAIT assassination\n \"net.ipv4.tcp_rfc1337\" = 1;\n # enable source validation of packets received (prevents IP spoofing)\n \"net.ipv4.conf.default.rp_filter\" = 1;\n \"net.ipv4.conf.all.rp_filter\" = 1;\n\n \"net.ipv4.conf.all.accept_redirects\" = 0;\n \"net.ipv4.conf.default.accept_redirects\" = 0;\n \"net.ipv4.conf.all.secure_redirects\" = 0;\n \"net.ipv4.conf.default.secure_redirects\" = 0;\n # Protect against IP spoofing\n \"net.ipv6.conf.all.accept_redirects\" = 0;\n \"net.ipv6.conf.default.accept_redirects\" = 0;\n \"net.ipv4.conf.all.send_redirects\" = 0;\n \"net.ipv4.conf.default.send_redirects\" = 0;\n\n # prevent man-in-the-middle attacks\n \"net.ipv4.icmp_echo_ignore_all\" = 1;\n\n # ignore ICMP request, helps avoid Smurf attacks\n \"net.ipv4.conf.all.forwarding\" = 0;\n \"net.ipv4.conf.default.accept_source_route\" = 0;\n \"net.ipv4.conf.all.accept_source_route\" = 0;\n \"net.ipv6.conf.all.accept_source_route\" = 0;\n \"net.ipv6.conf.default.accept_source_route\" = 0;\n # Reverse path filtering causes the kernel to do source validation of\n \"net.ipv6.conf.all.forwarding\" = 0;\n \"net.ipv6.conf.all.accept_ra\" = 0;\n \"net.ipv6.conf.default.accept_ra\" = 0;\n\n ## TCP hardening\n # Prevent bogus ICMP errors from filling up logs.\n \"net.ipv4.icmp_ignore_bogus_error_responses\" = 1;\n\n # Userspace\n # restrict usage of ptrace\n \"kernel.yama.ptrace_scope\" = 2;\n\n # ASLR memory protection (64-bit systems)\n \"vm.mmap_rnd_bits\" = 32;\n \"vm.mmap_rnd_compat_bits\" = 16;\n\n # only permit symlinks to be followed when outside of a world-writable sticky directory\n \"fs.protected_symlinks\" = 1;\n \"fs.protected_hardlinks\" = 1;\n # Prevent creating files in potentially attacker-controlled environments\n \"fs.protected_fifos\" = 2;\n \"fs.protected_regular\" = 2;\n\n # Randomize memory\n \"kernel.randomize_va_space\" = 2;\n # Exec Shield (Stack protection)\n \"kernel.exec-shield\" = 1;\n\n ## TCP optimization\n # TCP Fast Open is a TCP extension that reduces network latency by packing\n # data in the sender’s initial TCP SYN. Setting 3 = enable TCP Fast Open for\n # both incoming and outgoing connections:\n \"net.ipv4.tcp_fastopen\" = 3;\n # Bufferbloat mitigations + slight improvement in throughput & latency\n \"net.ipv4.tcp_congestion_control\" = \"bbr\";\n \"net.core.default_qdisc\" = \"cake\";\n };\n\n\n❗ Note: The above settings are fairly aggressive and can break common\nprograms, read the comment warnings.
\n
boot.kernelParams can be used to set additional kernel command line arguments\nat boot time. It can only be used for built-in modules.
You can find the following settings in the\nBoot parameters section
\n# boot.nix\n boot.kernelParams = [\n # make it harder to influence slab cache layout\n \"slab_nomerge\"\n # enables zeroing of memory during allocation and free time\n # helps mitigate use-after-free vulnerabilaties\n \"init_on_alloc=1\"\n \"init_on_free=1\"\n # randomizes page allocator freelist, improving security by\n # making page allocations less predictable\n \"page_alloc.shuffel=1\"\n # enables Kernel Page Table Isolation, which mitigates Meltdown and\n # prevents some KASLR bypasses\n \"pti=on\"\n # randomizes the kernel stack offset on each syscall\n # making attacks that rely on a deterministic stack layout difficult\n \"randomize_kstack_offset=on\"\n # disables vsyscalls, they've been replaced with vDSO\n \"vsyscall=none\"\n # disables debugfs, which exposes sensitive info about the kernel\n \"debugfs=off\"\n # certain exploits cause an \"oops\", this makes the kernel panic if an \"oops\" occurs\n \"oops=panic\"\n # only alows kernel modules that have been signed with a valid key to be loaded\n # making it harder to load malicious kernel modules\n # can make VirtualBox or Nvidia drivers unusable\n \"module.sig_enforce=1\"\n # prevents user space code excalation\n \"lockdown=confidentiality\"\n # \"rd.udev.log_level=3\"\n # \"udev.log_priority=3\"\n ];\nThis is a thoughtful start to hardening boot parameters, there are more\nrecommendations in the guide.
\nKernel modules for hardware devices are generally loaded automatically by\nudev. You can force a module to be loaded via boot.kernelModules.
Hardening Modprobe
\nYou can use both extraModprobeConfig & blacklistedKernelModules to disable\ndifferent features. If you prefer, you can place these in the next section as\nwell.
boot.extraModprobeConfig = ''\n # firewire and thunderbolt\n install firewire-core /bin/false\n install firewire_core /bin/false\n install firewire-ohci /bin/false\n install firewire_ohci /bin/false\n install firewire_sbp2 /bin/false\n install firewire-sbp2 /bin/false\n install firewire-net /bin/false\n install thunderbolt /bin/false\n install ohci1394 /bin/false\n install sbp2 /bin/false\n install dv1394 /bin/false\n install raw1394 /bin/false\n install video1394 /bin/false\n'';\n# OR\n#boot.blacklistedKernelModules = [\n# \"firewire-core\"\n# # ... snip ...\n#];\nBlacklisting Kernel Parameters
\nBlacklisting unused kernel modules reduces the attack surface.
\nboot.blacklistedKernelModules:\nList of names of kernel modules that should not be loaded automatically by the\nhardware probing code.
\nYou can find the following settings in the\nBlacklisting Kernel Modules Section
\n boot.blacklistedKernelModules = [\n # Obscure networking protocols\n \"dccp\" # Datagram Congestion Control Protocol\n \"sctp\" # Stream Control Transmission Protocol\n \"rds\" # Reliable Datagram Sockets\n \"tipc\" # Transparent Inter-Process Communication\n \"n-hdlc\" # High-level Data Link Control\n \"ax25\" # Amateur X.25\n \"netrom\" # NetRom\n \"x25\" # X.25\n \"rose\"\n \"decnet\"\n \"econet\"\n \"af_802154\" # IEEE 802.15.4\n \"ipx\" # Internetwork Packet Exchange\n \"appletalk\"\n \"psnap\" # SubnetworkAccess Protocol\n \"p8023\" # Novell raw IEE 802.3\n \"p8022\" # IEE 802.3\n \"can\" # Controller Area Network\n \"atm\"\n # Various rare filesystems\n \"cramfs\"\n \"freevxfs\"\n \"jffs2\"\n \"hfs\"\n \"hfsplus\"\n \"udf\"\n\n # \"squashfs\" # compressed read-only file system used for Live CDs\n # \"cifs\" # cmb (Common Internet File System)\n # \"nfs\" # Network File System\n # \"nfsv3\"\n # \"nfsv4\"\n # \"ksmbd\" # SMB3 Kernel Server\n # \"gfs2\" # Global File System 2\n # vivid driver is only useful for testing purposes and has been the\n # cause of privilege escalation vulnerabilities\n # \"vivid\"\n ];\nAs with the kernelParameters above, there are more suggestions in the guide, I\nhave used the above parameters along with the commented out ones and had no\nissues.
Also see\nSecureBlue’s blacklist.conf\nfor more ideas.
\n\n\nThere is a performance cost to enabling a hardened memory allocator, and\nsome apps will not work without a workaround such as Firefox, Thunderbird,\nTorbrowser, LibreWolf, and ZenBrowser to name a few.
\n
With memory corruption bugs being the leading zero day category, it’s clearly\nsomething that you should be concerned with.
\nThe grapheneOS hardened_malloc is available for NixOS in two variants, add\neither to your configuration.nix or equivalent to apply them:
environment.memoryAllocator.provider = \"graphene-hardened\";: This is the\ndefault configuration template that has all normal optional security features\nenabled. It’s aggressive, you can expect app breakage and a performance cost.
environment.memoryAllocator.provider = \"graphene-hardened-light\";: The\nlight template disables the slap quarantines, write after free check, slot\nrandomization and raises the guard slab interval from 1 to 8 but leaves\nzero-on-free and slab canaries enabled. This version has solid performance\nand is still far more secure than the standard allocator.
libhardened_malloc.so is typically installed to\n/usr/local/lib/libhardened_malloc.so and referenced from /etc/ld.so.preload.
systemd is the core “init system” and service manager that controls how\nservices, daemons, and basic system processes are started, stopped and\nsupervised on modern Linux distributions, including NixOS. It provides a suite\nof basic building blocks for a Linux system as well as a system and service\nmanager 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\nimplimentation is deprecated.
\nBecause it launches and supervises almost all system services, hardening systemd\nmeans raising the baseline security of your entire system.
\nDisable coredumps:
\nsystemd.coredump.enable = false;\n# ➡️ Sets the kernel's resource limit (ulimit -c 0)\n security.pam.loginLimits = [\n {\n domain = \"*\"; # Applies to all users/sessions\n type = \"-\"; # Set both soft and hard limits\n item = \"core\"; # The soft/hard limit item\n value = \"0\"; # Core dumps size is limited to 0 (effectively disabled)\n }\n ];\nDisabling coredumps helps save space and improves security/privacy because when\na program fails, a coredump contains an exact copy of a programs running memory\nat the time of the crash. This can inadvertently expose sensitive data.
\nIf a program is handling private information when it crashes, the core dump file\ncould contain:
\nPasswords: Stored in memory before being sent or hashed.
\nEncryption Keys: Used for securing network connections.
\nPersonal Info: Chat messages, website forms, etc.
\nIt can give a minor performance upgrade and does reduce the attack surface. If a\nmalicious program were to gain access to your system, one of the first things it\nmight look for are core dump files to extract sensitive data. By disabling them,\nyou eliminate this potential source of information leakage.
\ndbus-broker is generally considered more secure and robust but isn’t the\ndefault as of yet.
dbus-broker is now the default, it’s faster and more reliable.
users.groups.netdev = {};\n services = {\n dbus.implementation = \"broker\";\n logrotate.enable = true;\n journald = {\n storage = \"volatile\"; # Store logs in memory\n upload.enable = false; # Disable remote log upload (the default)\n extraConfig = ''\n SystemMaxUse=500M\n SystemMaxFileSize=50M\n '';\n };\n };\ndbus-broker is more resilient to resource exhaustion attacks and integrates\nbetter with Linux security features.
Setting storage = \"volatile\" tells journald to keep log data only in memory.\nThere is a tradeoff though, If you need long-term auditing or troubleshooting\nafter a reboot, this will not preserve system logs.
upload.enable is for forwarding log messages to remote servers, setting this\nto false prevents accidental leaks of potentially sensitive or internal system\ninformation.
Enabling logrotate prevents your disk from filling with excessive\nlegacy/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:
\nsystemd-analyze security\n# or for a detailed view of individual services security posture\nsystemd-analyze security NetworkManager\nOptionally disable vulnerable services to reduce the attack surface, obviously\ndon’t disable what you need, or change your habits:
\nservices = {\n # mDNS/DNS-SD\n avahi.enable = false;\n # Geoclue (location services)\n geoclue2.enable = false;\n udisks2.enable = false;\n accounts-daemon.enable = false;\n };\n # Only needed for WWAN/3G/4G modems, otherwise it runs `mmcli` unnecessarily\n networking.modemmanager.enable = false;\n # Bluetooth has a long history of vulnerabilities\n hardware.bluetooth.enable = false;\n # Prefer manual upgrades on a hardened system\n system.autoUpgrade.enable = false;\nFurther reading on systemd:
\nThe following is a repo containing many of the Systemd hardening settings in\nNixOS format:
\n\nFor example, to harden bluetooth you could add the following to your\nconfiguration.nix or equivalent:
systemd.services = {\n bluetooth.serviceConfig = {\n ProtectKernelTunables = lib.mkDefault true;\n ProtectKernelModules = lib.mkDefault true;\n ProtectKernelLogs = lib.mkDefault true;\n ProtectHostname = true;\n ProtectControlGroups = true;\n ProtectProc = \"invisible\";\n SystemCallFilter = [\n \"~@obsolete\"\n \"~@cpu-emulation\"\n \"~@swap\"\n \"~@reboot\"\n \"~@mount\"\n ];\n SystemCallArchitectures = \"native\";\n };\n}\nAs you can see from above, you typically use the serviceConfig attribute to\nharden settings for systemd services.
systemd-analyze security bluetooth\n→ Overall exposure level for bluetooth.service: 3.3 OK 🙂\n{lib, ...}: {\n systemd.services = {\n # \"home-manager-jr\".after = [\"network-online.target\"];\n # \"home-manager-jr\".wantedBy = [\"multi-user.target\"];\n \"user@\".serviceConfig = {\n ProtectSystem = \"strict\";\n ProtectClock = true;\n ProtectHostname = true;\n ProtectKernelTunables = true;\n ProtectKernelModules = true;\n ProtectKernelLogs = true;\n ProtectProc = \"invisible\";\n PrivateTmp = true;\n PrivateNetwork = true;\n MemoryDenyWriteExecute = false;\n RestrictAddressFamilies = [\n \"AF_UNIX\"\n \"AF_NETLINK\"\n \"AF_BLUETOOTH\"\n ];\n RestrictNamespaces = true;\n RestrictRealtime = true;\n RestrictSUIDSGID = true;\n SystemCallFilter = [\n \"~@keyring\"\n \"~@swap\"\n \"~@debug\"\n \"~@module\"\n \"~@obsolete\"\n \"~@cpu-emulation\"\n ];\n SystemCallArchitectures = \"native\";\n };\n acpid.serviceConfig = {\n ProtectSystem = \"full\";\n ProtectHome = true;\n RestrictAddressFamilies = [\"AF_INET\" \"AF_INET6\"];\n SystemCallFilter = \"~@clock @cpu-emulation @debug @module @mount @raw-io @reboot @swap\";\n ProtectKernelTunables = true;\n ProtectKernelModules = true;\n };\n\n auditd.serviceConfig = {\n NoNewPrivileges = true;\n ProtectSystem = \"full\";\n ProtectHome = true;\n ProtectHostname = true;\n ProtectKernelTunables = true;\n ProtectKernelModules = true;\n ProtectControlGroups = true;\n ProtectProc = \"invisible\";\n ProtectClock = true;\n PrivateTmp = true;\n PrivateNetwork = true;\n PrivateMounts = true;\n PrivateDevices = true;\n RestrictNamespaces = true;\n RestrictRealtime = true;\n RestrictSUIDSGID = true;\n RestrictAddressFamilies = [\n \"~AF_INET6\"\n \"~AF_INET\"\n \"~AF_PACKET\"\n ];\n MemoryDenyWriteExecute = true;\n LockPersonality = true;\n SystemCallFilter = [\n \"~@clock\"\n \"~@module\"\n \"~@mount\"\n \"~@swap\"\n \"~@obsolete\"\n \"~@cpu-emulation\"\n ];\n SystemCallArchitectures = \"native\";\n CapabilityBoundingSet = [\n \"~CAP_CHOWN\"\n \"~CAP_FSETID\"\n \"~CAP_SETFCAP\"\n ];\n };\n\n cups.serviceConfig = {\n NoNewPrivileges = true;\n ProtectSystem = \"full\";\n ProtectHome = true;\n ProtectKernelModules = true;\n ProtectKernelTunables = true;\n ProtectKernelLogs = true;\n ProtectControlGroups = true;\n ProtectHostname = true;\n ProtectClock = true;\n ProtectProc = \"invisible\";\n RestrictRealtime = true;\n RestrictNamespaces = true;\n RestrictSUIDSGID = true;\n RestrictAddressFamilies = [\n \"AF_UNIX\"\n \"AF_NETLINK\"\n \"AF_INET\"\n \"AF_INET6\"\n \"AF_PACKET\"\n ];\n\n MemoryDenyWriteExecute = true;\n SystemCallFilter = [\n \"~@clock\"\n \"~@reboot\"\n \"~@debug\"\n \"~@module\"\n \"~@swap\"\n \"~@obsolete\"\n \"~@cpu-emulation\"\n ];\n SystemCallArchitectures = \"native\";\n LockPersonality = true;\n };\n\n NetworkManager.serviceConfig = {\n NoNewPrivileges = true;\n ProtectHome = true;\n ProtectKernelModules = true;\n ProtectKernelLogs = true;\n ProtectControlGroups = true;\n ProtectClock = true;\n ProtectHostname = true;\n ProtectProc = \"invisible\";\n PrivateTmp = true;\n RestrictRealtime = true;\n RestrictAddressFamilies = [\n \"AF_UNIX\"\n \"AF_NETLINK\"\n \"AF_INET\"\n \"AF_INET6\"\n \"AF_PACKET\"\n ];\n RestrictNamespaces = true;\n RestrictSUIDSGID = true;\n MemoryDenyWriteExecute = true;\n SystemCallFilter = [\n \"~@mount\"\n \"~@module\"\n \"~@swap\"\n \"~@obsolete\"\n \"~@cpu-emulation\"\n \"ptrace\"\n ];\n SystemCallArchitectures = \"native\";\n LockPersonality = true;\n };\n\n wpa_supplicant.serviceConfig = {\n NoNewPrivileges = true;\n ProtectSystem = \"strict\";\n ProtectHome = true;\n ProtectKernelModules = true;\n ProtectKernelLogs = true;\n ProtectControlGroups = true;\n ProtectClock = true;\n ProtectHostname = true;\n ProtectProc = \"invisible\";\n PrivateTmp = true;\n PrivateMounts = true;\n RestrictRealtime = true;\n RestrictAddressFamilies = [\n \"AF_UNIX\"\n \"AF_NETLINK\"\n \"AF_INET\"\n \"AF_INET6\"\n \"AF_PACKET\"\n ];\n RestrictNamespaces = true;\n RestrictSUIDSGID = true;\n MemoryDenyWriteExecute = true;\n SystemCallFilter = [\n \"~@mount\"\n \"~@raw-io\"\n \"~@privileged\"\n \"~@keyring\"\n \"~@reboot\"\n \"~@module\"\n \"~@swap\"\n \"~@resources\"\n \"~@obsolete\"\n \"~@cpu-emulation\"\n \"ptrace\"\n ];\n SystemCallArchitectures = \"native\";\n LockPersonality = true;\n CapabilityBoundingSet = \"CAP_NET_ADMIN CAP_NET_RAW\";\n };\n\n dbus.serviceConfig = {\n NoNewPrivileges = true;\n ProtectSystem = \"stric\";\n ProtectControlGroups = true;\n ProtectHome = true;\n ProtectHostname = true;\n ProtectKernelTunables = true;\n ProtectKernelModules = true;\n ProtectKernelLogs = true;\n PrivateMounts = true;\n PrivateDevices = true;\n PrivateTmp = true;\n RestrictSUIDSGID = true;\n RestrictRealtime = true;\n RestrictAddressFamilies = [\n \"AF_UNIX\"\n ];\n RestrictNamespaces = true;\n SystemCallErrorNumber = \"EPERM\";\n SystemCallArchitectures = \"native\";\n SystemCallFilter = [\n \"~@obsolete\"\n \"~@resources\"\n \"~@debug\"\n \"~@mount\"\n \"~@reboot\"\n \"~@swap\"\n \"~@cpu-emulation\"\n ];\n LockPersonality = true;\n IPAddressDeny = [\"0.0.0.0/0\" \"::/0\"];\n MemoryDenyWriteExecute = true;\n DevicePolicy = \"closed\";\n UMask = 0077;\n };\n\n nscd.serviceConfig = {\n ProtectClock = true;\n ProtectHostname = true;\n ProtectKernelTunables = true;\n ProtectKernelModules = true;\n ProtectKernelLogs = true;\n ProtectControlGroups = true;\n ProtectProc = \"invisible\";\n RestrictNamespaces = true;\n RestrictRealtime = true;\n MemoryDenyWriteExecute = true;\n LockPersonality = true;\n SystemCallFilter = [\n \"~@mount\"\n \"~@swap\"\n \"~@clock\"\n \"~@obsolete\"\n \"~@cpu-emulation\"\n ];\n SystemCallArchitectures = \"native\";\n CapabilityBoundingSet = [\n \"~CAP_CHOWN\"\n \"~CAP_FSETID\"\n \"~CAP_SETFCAP\"\n ];\n };\n bluetooth.serviceConfig = {\n ProtectKernelTunables = lib.mkDefault true;\n ProtectKernelModules = lib.mkDefault true;\n ProtectKernelLogs = lib.mkDefault true;\n ProtectHostname = true;\n ProtectControlGroups = true;\n ProtectProc = \"invisible\";\n SystemCallFilter = [\n \"~@obsolete\"\n \"~@cpu-emulation\"\n \"~@swap\"\n \"~@reboot\"\n \"~@mount\"\n ];\n SystemCallArchitectures = \"native\";\n };\n systemd-rfkill.serviceConfig = {\n ProtectSystem = \"strict\";\n ProtectHome = true;\n ProtectKernelTunables = true;\n ProtectKernelModules = true;\n ProtectControlGroups = true;\n ProtectClock = true;\n ProtectProc = \"invisible\";\n ProcSubset = \"pid\";\n PrivateTmp = true;\n MemoryDenyWriteExecute = true;\n NoNewPrivileges = true;\n LockPersonality = true;\n RestrictRealtime = true;\n SystemCallArchitectures = \"native\";\n UMask = \"0077\";\n IPAddressDeny = \"any\";\n };\n systemd-machined.serviceConfig = {\n NoNewPrivileges = true;\n ProtectSystem = \"strict\";\n ProtectHome = true;\n ProtectClock = true;\n ProtectHostname = true;\n ProtectKernelTunables = true;\n ProtectKernelModules = true;\n ProtectKernelLogs = true;\n ProtectProc = \"invisible\";\n PrivateTmp = true;\n PrivateMounts = true;\n PrivateUsers = true;\n PrivateNetwork = true;\n RestrictNamespaces = true;\n RestrictRealtime = true;\n RestrictSUIDSGID = true;\n RestrictAddressFamilies = [\"AF_UNIX\"];\n MemoryDenyWriteExecute = true;\n SystemCallArchitectures = \"native\";\n };\n systemd-udevd.serviceConfig = {\n NoNewPrivileges = true;\n ProtectSystem = \"strict\";\n ProtectHome = true;\n ProtectKernelLogs = true;\n ProtectControlGroups = true;\n ProtectClock = true;\n ProtectProc = \"invisible\";\n RestrictNamespaces = true;\n CapabilityBoundingSet = \"~CAP_SYS_PTRACE ~CAP_SYS_PACCT\";\n };\n nix-daemon.serviceConfig = {\n NoNewPrivileges = true;\n ProtectControlGroups = true;\n ProtectKernelModules = true;\n PrivateMounts = true;\n PrivateTmp = true;\n PrivateDevices = true;\n RestrictSUIDSGID = true;\n RestrictRealtime = true;\n RestrictNamespaces = [\"~cgroup\"];\n RestrictAddressFamilies = [\n \"AF_UNIX\"\n \"AF_NETLINK\"\n \"AF_INET6\"\n \"AF_INET\"\n ];\n CapabilityBoundingSet = [\n \"~CAP_SYS_CHROOT\"\n \"~CAP_BPF\"\n \"~CAP_AUDIT_WRITE\"\n \"~CAP_AUDIT_CONTROL\"\n \"~CAP_AUDIT_READ\"\n \"~CAP_SYS_PTRACE\"\n \"~CAP_SYS_NICE\"\n \"~CAP_SYS_RESOURCE\"\n \"~CAP_SYS_RAWIO\"\n \"~CAP_SYS_TIME\"\n \"~CAP_SYS_PACCT\"\n \"~CAP_LINUX_IMMUTABLE\"\n \"~CAP_IPC_LOCK\"\n \"~CAP_WAKE_ALARM\"\n \"~CAP_SYS_TTY_CONFIG\"\n \"~CAP_SYS_BOOT\"\n \"~CAP_LEASE\"\n \"~CAP_BLOCK_SUSPEND\"\n \"~CAP_MAC_ADMIN\"\n \"~CAP_MAC_OVERRIDE\"\n ];\n SystemCallErrorNumber = \"EPERM\";\n SystemCallArchitectures = \"native\";\n SystemCallFilter = [\n \"~@resources\"\n \"~@module\"\n \"~@obsolete\"\n \"~@debug\"\n \"~@reboot\"\n \"~@swap\"\n \"~@cpu-emulation\"\n \"~@clock\"\n \"~@raw-io\"\n ];\n LockPersonality = true;\n MemoryDenyWriteExecute = false;\n DevicePolicy = \"closed\";\n UMask = 0077;\n };\n systemd-journald.serviceConfig = {\n NoNewPrivileges = true;\n ProtectProc = \"invisible\";\n ProtectHostname = true;\n PrivateMounts = true;\n };\n };\n}\nLynis is a security auditing tool for systems based on UNIX like Linux, macOS,\nBSD, and others.–lynis repo
\nchkrootkit was removed as it is unmaintained and archived upstream.
Installation:
\nenvironment.systemPackages = [\npkgs.lynis\npkgs.clamav\npkgs.aide\n ];\nAIDE is an intrusion detection system (IDS) that will notify us whenever it\ndetects that a potential intrusion has occurred. When a system is compromised,\nattackers typically will try to change file permissions and escalate to the root\nuser account and start to modify system files, AIDE can detect this.
\nTo set up AIDE on your system follow these steps:
\naide.conf:sudo mkdir -p /var/lib/aide && cd /var/lib/aide/\nsudo hx aide.conf\nAdd the following content to /var/lib/aide/aide.conf:
# aide.conf\n# Example configuration file for AIDE.\n\n@@define DBDIR /var/lib/aide\n\n# The location of the database to be read.\ndatabase_in=file:@@{DBDIR}/aide.db.gz\n\n# The location of the database to be written.\n#database_out=sql:host:port:database:login_name:passwd:table\n#database_out=file:aide.db.new\ndatabase_out=file:@@{DBDIR}/aide.db.new.gz\n\n# Whether to gzip the output to database\ngzip_dbout=yes\n\nlog_level=info\n\nreport_url=file:/var/log/aide/aide.log\nreport_url=stdout\n#report_url=stderr\n#NOT IMPLEMENTED report_url=mailto:root@foo.com\n#NOT IMPLEMENTED report_url=syslog:LOG_AUTH\n\n# These are the default rules.\n#\n#p: permissions\n#i: inode:\n#n: number of links\n#u: user\n#g: group\n#s: size\n#b: block count\n#m: mtime\n#a: atime\n#c: ctime\n#S: check for growing size\n#md5: md5 checksum\n#sha1: sha1 checksum\n#rmd160: rmd160 checksum\n#tiger: tiger checksum\n#haval: haval checksum\n#gost: gost checksum\n#crc32: crc32 checksum\n#R: p+i+n+u+g+s+m+c+md5\n#L: p+i+n+u+g\n#E: Empty group\n#>: Growing logfile p+u+g+i+n+S\n\n# You can create custom rules like this.\n\nNORMAL = R+b+sha512\n\nDIR = p+i+n+u+g\n\n# Next decide what directories/files you want in the database.\n\n/boot NORMAL\n/bin NORMAL\n/sbin NORMAL\n/lib NORMAL\n/opt NORMAL\n/usr NORMAL\n/root NORMAL\n\n# Check only permissions, inode, user and group for /etc, but\n# cover some important files closely.\n/etc p+i+u+g\n!/etc/mtab\n/etc/exports NORMAL\n/etc/fstab NORMAL\n/etc/passwd NORMAL\n/etc/group NORMAL\n/etc/gshadow NORMAL\n/etc/shadow NORMAL\n\n/var/log p+n+u+g\n\n# With AIDE's default verbosity level of 5, these would give lots of\n# warnings upon tree traversal. It might change with future version.\n#\n#=/lost\\+found DIR\n#=/home DIR\nCreate the logfile:
\nsudo mkdir -p /var/log/aide\nsudo touch /var/log/aide/aide.log\n/etc/aide.db.newsudo aide --config /var/lib/aide/aide.conf --init\n.new:sudo mv /var/lib/aide/aide.db.new.gz /var/lib/aide/aide.db.gz\nls /var/lib/aide/\naide.conf aide.db.gz\nsudo aide --check --config /var/lib/aide/aide.conf\nStart timestamp: 2025-09-05 09:50:07 -0400 (AIDE 0.19.2)\nAIDE found NO differences between database and filesystem. Looks okay!!\nsudo aide --update --config /var/lib/aide/aide.conf\nUnfortunately, AIDE doesn’t automatically replace the old database so you have\nto rename the new one again:
\nsudo mv /var/lib/aide/aide.db.new.gz /var/lib/aide/aide.db.gz\nAnd finally check again:
\nsudo aide --check --config /var/lib/aide/aide.conf\n{pkgs, ...}: {\n environment.systemPackages = with pkgs; [\n clamav\n ];\n services.clamav = {\n # Enable clamd daemon\n daemon.enable = true;\n updater.enable = true;\n updater.frequency = 12; # Number of database checks per day\n scanner = {\n enable = true;\n # 4:00 AM\n interval = \"*-*-* 04:00:00\";\n scanDirectories = [\n \"/home\"\n \"/var/lib\"\n \"/tmp\"\n \"/etc\"\n \"/var/tmp\"\n ];\n };\n };\n}\nLynis Usage:
\nsudo lynis show commands\n# Output:\nCommands:\nlynis audit\nlynis configure\nlynis generate\nlynis show\nlynis update\nlynis upload-only\n\nsudo lynis audit system\n# Output:\n Lynis security scan details:\n\n Hardening index : 79 [############### ]\n Tests performed : 234\n Plugins enabled : 0\n\n Components:\n - Firewall [V]\n - Malware scanner [V]\n\n Scan mode:\n Normal [V] Forensics [ ] Integration [ ] Pentest [ ]\n\n Lynis modules:\n - Compliance status [?]\n - Security audit [V]\n - Vulnerability scan [V]\nThe “Lynis hardening index” is an overall impression on how well a system is\nhardened. However, this is just an indicator on measures taken - not a\npercentage of how safe a system might be. A score over 75 typically indicates\na system with more than average safety measures implemented.
\nLynis will give you more recommendations for securing your system as well.
\nIf you use clamscan, create the following log file:
sudo touch /var/log/clamscan.log\nExample cron job for clamav & aide:
{pkgs, ...}: {\n services.cron = {\n enable = true;\n # messages.enable = true;\n systemCronJobs = [\n # Every day at 2:00 AM, run clamscan as root and append output to a log file\n \"0 2 * * * root ${pkgs.clamav}/bin/clamscan -r /home >> /var/log/clamscan.log\"\n \"0 11 * * * ${pkgs.aide}/bin/aide --check --config /var/lib/aide/aide.conf\"\n ];\n };\n}\nClamAV usage:
\nYou can run clamav manually with:
# Recursive Scan:\nsudo clamscan -r ~/home\n\n\nYou only need either the individual
\npkgs.clamavwith the cron job OR the\nclamd-daemonmodule.clamdscanis for software integration and\nuses a different user that doesn’t have permission to scan your files. You can\nuseclamdscan --fdpass /path/to/scanto pass the necessary file permissions.\nclamdscanruns in the background, you can watch it withtop.
\n\nSecurity information: Changing SSH configuration settings can\nsignificantly impact the security of your system(s). It is crucial to have a\nsolid understanding of what you are doing before making any adjustments. Avoid\nblindly copying and pasting examples, including those from this Wiki page,\nwithout conducting a thorough analysis. Failure to do so may compromise the\nsecurity of your system(s) and lead to potential vulnerabilities. Take the\ntime to comprehend the implications of your actions and ensure that any\nchanges made are done thoughtfully and with care. –NixOS Wiki
\n
\n\nChoose one, either
\nssh-agentorgpg-agent
ssh-keygen, this is recommended unless\nyou have a good reason for not using it.OR
\ngpg-agent (which acts as your SSH agent). Complex, and\nharder to understand in my opinion.My setup caused conflicts when enabling programs.ssh.startAgent so I chose\ngpg-agent personally.
There are situations where you are required to use one or the other like for\nheadless CI/CD environments, ssh-keygen is required.
Further reading:
\nThe ed25519 algorithm is significantly faster and more secure when compared to\nRSA. You can also specify the key derivation function (KDF) rounds to\nstrengthen protection even more.
For example, to generate a strong key for GitHub:
\nssh-keygen -t ed25519 -a 32 -f ~/.ssh/id_ed25519_github_$(date +%Y-%m-%d) -C \"SSH Key for GitHub\"\n-t is for type
-a 32 sets the number of KDF rounds. The standard is usually good enough,\nadding extra rounds can make it harder to brute-force.
-f is for filename
First of all, if you don’t use SSH don’t enable it in the first place. If you do\nuse SSH, it’s important to understand what that opens you up to.
\nThe following are some recommendations from Mozilla on OpenSSH:
\n\nThe following OpenSSH setup is based on the above guidelines with strong\nalgorithms, and best practices: (EDITED: 10-07-25 to follow best-practices on\npost-quantum crypto)
\n{config, ...}: {\n config = {\n services = {\n fail2ban = {\n enable = true;\n maxretry = 5;\n bantime = \"1h\";\n # ignoreIP = [\n # \"172.16.0.0/12\"\n # \"192.168.0.0/16\"\n # \"2601:881:8100:8de0:31e6:ac52:b5be:462a\"\n # \"matrix.org\"\n # \"app.element.io\" # don't ratelimit matrix users\n # ];\n\n bantime-increment = {\n enable = true; # Enable increment of bantime after each violation\n multipliers = \"1 2 4 8 16 32 64 128 256\";\n maxtime = \"168h\"; # Do not ban for more than 1 week\n overalljails = true; # Calculate the bantime based on all the violations\n };\n };\n openssh = {\n enable = true;\n settings = {\n PasswordAuthentication = false;\n PermitEmptyPasswords = false;\n PermitTunnel = false;\n UseDns = false;\n KbdInteractiveAuthentication = false;\n X11Forwarding = config.services.xserver.enable;\n MaxAuthTries = 3;\n MaxSessions = 2;\n ClientAliveInterval = 300;\n ClientAliveCountMax = 0;\n AllowUsers = [\"your-user\"];\n TCPKeepAlive = false;\n AllowTcpForwarding = false;\n AllowAgentForwarding = false;\n LogLevel = \"VERBOSE\";\n PermitRootLogin = \"no\";\n KexAlgorithms = [\n # Post-Quantum: https://www.openssh.org/pq.html\n \"mlkem768x25519-sha256\"\n \"sntrup761x25519-sha512\"\n \"curve25519-sha256@libssh.org\"\n \"ecdh-sha2-nistp521\"\n \"ecdh-sha2-nistp384\"\n \"ecdh-sha2-nistp256\"\n \"diffie-hellman-group-exchange-sha256\"\n ];\n Ciphers = [\n \"aes256-gcm@openssh.com\"\n \"aes128-gcm@openssh.com\"\n # stream cipher alternative to aes256, proven to be resilient\n # Very fast on basically anything\n \"chacha20-poly1305@openssh.com\"\n # industry standard, fast if you have AES-NI hardware\n \"aes256-ctr\"\n \"aes192-ctr\"\n \"aes128-ctr\"\n ];\n Macs = [\n # Combines the SHA-512 hash func with a secret key to create a MAC\n \"hmac-sha2-512-etm@openssh.com\"\n \"hmac-sha2-256-etm@openssh.com\"\n \"umac-128-etm@openssh.com\"\n \"hmac-sha2-512\"\n \"hmac-sha2-256\"\n \"umac-128@openssh.com\"\n ];\n };\n # These keys will be generated for you\n hostKeys = [\n {\n path = \"/etc/ssh/ssh_host_ed25519_key\";\n type = \"ed25519\";\n }\n ];\n };\n };\n };\n}\nTCP port 22 (ssh) is opened automatically if the SSH daemon is enabled\n(services.openssh.enable = true;)
Much of the SSH hardening settings came from\nryanseipp’s secure-ssh Guide\nwith some additions of my own.
\nFail2Ban is an intrusion prevention software framework. It’s designed to prevent\nbrute-force attacks by scanning log files for suspicious activity, such as\nrepeated failed login attempts.
\nAs of 26.05, reaction was added to nixpkgs.\n“A daemon that scans program outputs for repeated patterns, and takes action.”\nIt labels itself as a more modern alternative to fail2ban, implemented in Rust.\nThe initial rust commit was authored May 20, 2024 and it has not received an\nexternal security audit yet. Worth checking out, probably not a primary\nrecommendation yet.
\nOpenSSH is the primary tool for secure remote access for NixOS. Enabling it\nactivates the OpenSSH server on the system, allowing incoming SSH connections.
\nThe above configuration is a robust setup for securing an SSH server by:
\nPreventing brute-force attacks with Fail2Ban
\nEliminating password authentication in favor of more secure SSH keys
\nRestricting user access and preventing root login
\nDisabling potentially risky forwarding features (tunnel, TCP, agent)
\nEnforce the use of strong, modern cryptographic algorithms for all SSH\ncommunications.
\nEnhanced logging for better auditing.
\nFurther Reading:
\nNever store secrets in plain text in repositories. Use something like\nsops-nix, which lets you keep encrypted\nsecrets under version control declaratively.
\nAnother option is agenix
\n\nProtect your secrets, the following guide is on setting up Sops on NixOS:\nSops Encrypted Secrets
\nTo enable the Linux Audit Daemon (auditd) and define a very basic rule set,\nyou can use the following NixOS configuration. This example demonstrates how to\nlog every program execution (execve) on a 64-bit architecture.
# modules/security/auditd-minimal.nix (or directly in configuration.nix)\n{\n # start as early in the boot process as possible\n boot.kernelParams = [\"audit=1\"];\n security.auditd.enable = true;\n security.audit.enable = true;\n security.audit.rules = [\n # Log all program executions on 64-bit architecture\n \"-a exit,always -F arch=b64 -S execve\"\n ];\n}\naudit=1 Enables auditing at the kernel level very early in the boot process.\nWithout this, some events could be missed.
security.auditd.enable = true; Ensures the auditd userspace daemon is\nstarted.
While often enabled together, security.audit.enable specifically refers to\nenabling the NixOS module for audit rules generation.
execve (program executions)
This is just a basic configuration, there is much more that can be tracked.
\nIt’s important to protect your USB ports to prevent BadUSB attacks, data\nexfiltration, unauthorized device access, malware injection, etc.
\nTo get a list of your connected USB devices you can use lsusb from the\nusbutils package.
lsusb\nTo list the devices recognized by USBGuard, run:
\nsudo usbguard list-devices\nChange your-user to your username:
# usbguard.nix\n{\n config,\n pkgs,\n lib,\n ...\n}: let\n inherit (lib) mkIf;\n cfg = config.custom.security.usbguard;\nin {\n options.custom.security.usbguard = {\n enable = lib.mkEnableOption \"usbguard\";\n };\n\n config = mkIf cfg.enable {\n services.usbguard = {\n enable = true;\n IPCAllowedUsers = [\"root\" \"your-user\"];\n # presentDevicePolicy refers to how to treat USB devices that are already connected when the daemon starts\n presentDevicePolicy = \"allow\";\n rules = ''\n # allow `only` devices with mass storage interfaces (USB Mass Storage)\n allow with-interface equals { 08:*:* }\n # allow mice and keyboards\n # allow with-interface equals { 03:*:* }\n\n # Reject devices with suspicious combination of interfaces\n reject with-interface all-of { 08:*:* 03:00:* }\n reject with-interface all-of { 08:*:* 03:01:* }\n reject with-interface all-of { 08:*:* e0:*:* }\n reject with-interface all-of { 08:*:* 02:*:* }\n '';\n };\n\n environment.systemPackages = [pkgs.usbguard];\n };\n}\nThe above settings can be found in\nRedHat UsbGuard
\nThe only allow rule is for devices with only mass storage interfaces\n(08:*:*) i.e., USB Mass storage devices, devices like keyboards and mice\n(which use interface class 03:*:*) implicitly not allowed.
The reject rules reject devices with a suspicious combination of interfaces. A\nUSB drive that implements a keyboard or a network interface is very suspicious,\nthese reject rules prevent that.
The presentDevicePolicy = \"allow\"; allows any device that is present at daemon\nstart up even if they’re not explicitly allowed. However, newly plugged in\ndevices must match an allow rule or get denied implicitly.
The presentDevicePolicy should be one of: # one of \"apply-policy\"(default,\nevaluate the rule set for every present device), \"block\", \"reject\", \"keep\"\n(keep whatever state the device is currently in), or \"allow\", which is used in\nthe example.
There is also the\nusbguard-notifier
\nAnd enable it with the following in your configuration.nix or equivalent:
# configuration.nix\nimports = [\n ./usbguard.nix\n];\ncustom.security.usbguard.enable = true;\n\n\n❗ If you are ever unsure about a setting that you want to harden and think\nthat it could possibly break your system you can always use a specialisation\nreversing the action and choose it’s generation at boot up. For example, to\nforce-reverse the above settings you could:
\n\n# configuration.nix\nspecialisation.no-usbguard.configuration = {\n services.usbguard.enable = lib.mkForce false;\n};\n\n
\n- This is a situation where I recommend this, it’s easy to lock yourself out\nof your keyboard, mouse, etc. when trying to configure this.
\n
Further Reading:
\n\n\nI have moved to
\nrun0for authentication which is included by default with\nsystemd. It’s actually a symlink to the existingsystemd-runtool. It\nbehaves like a securesudoalternative: it spawns a transient service under\nPID 1 for privilege escalation, without relying on SUID (set user ID)\nbinaries.
\n\nthe Nixpkgs version of
\ndoas,OpenDoas\nis unmaintained and hasn’t been updated in 3 to 4 years. If you don’t like\nrun0, consider usingsudo-rs. I’m leaving this here for now, may remove it\nin the future to not promote using unmaintained software, you’ve been warned.
SUID = “Set User ID”: When a binary has the SUID bit set, it runs with the\nprivileges of the file’s owner (often root). There is a long history of\nvulnerabilities with SUID binaries.
\nFor a more minimalist version of sudo with a smaller codebase and attack\nsurface, consider doas. Replace userName with your username:
# doas.nix\n{\n lib,\n config,\n pkgs, # Add pkgs if you need to access user information\n ...\n}: let\n cfg = config.custom.security.doas;\nin {\n options.custom.security.doas = {\n enable = lib.mkEnableOption \"doas\";\n };\n\n config = lib.mkIf cfg.enable {\n # Disable sudo\n security.sudo.enable = false;\n\n # Enable and configure `doas`.\n security.doas = {\n enable = true;\n extraRules = [\n {\n # Grant doas access specifically to your user\n users = [\"userName\"]; # <--- Only give access to your user\n # persist = true; # Convenient but less secure\n # noPass = true; # Convenient but even less secure\n keepEnv = true; # Often necessary\n # Optional: You can also specify which commands they can run, e.g.:\n # cmd = \"ALL\"; # Allows running all commands (default if not specified)\n # cmd = \"/run/current-system/sw/bin/nixos-rebuild\"; # Only allow specific command\n }\n ];\n };\n\n # Add an alias to the shell for backward-compat and convenience.\n environment.shellAliases = {\n sudo = \"doas\";\n };\n };\n}\nYou would then import this into your configuration.nix and enable/disable it\nwith the following:
# configuration.nix\n\nimports = [\n ./doas.nix\n];\n\ncustom.security.doas.enable = true;\n\n\n[!NOTE]: Many people opt for the less secure
\ngroups = [\"wheel\"];in the\nabove configuration instead ofusers = [\"userName\"];to give wider access,\nthe choice is yours.
\n\n❗️ Critics such as madaidan say that Firejail worsens security by acting as a\nprivilege escalation hole. Firejail requires the executable to be setuid,\nmeaning it runs with root privileges.This is risky because any vulnerability\nin Firejail can lead to privilege escalation. This combined with many\nconvenience features and complicated command line flags leads to a large\nattack surface.
\n
I haven’t personally tried\nnix-bwrapper myself yet, but it’s\nanother sandboxing option that looks interesting. Bubblewrap is known for\nhaving a more minimal design and smaller attack surface.
\nnix-bubblewrap is another option.
\n\n\nRunning untrusted code is never safe, sandboxing cannot change this.\n–Arch Wiki
\n
# firejail.nix\n{\n pkgs,\n lib,\n ...\n}: {\n programs.firejail = {\n enable = true;\n wrappedBinaries = {\n # Sandbox a web browser\n librewolf = {\n executable = \"${lib.getBin pkgs.librewolf}/bin/librewolf\";\n profile = \"${pkgs.firejail}/etc/firejail/librewolf.profile\";\n };\n # Sandbox a file manager\n thunar = {\n executable = \"${lib.getBin pkgs.xfce.thunar}/bin/thunar\";\n profile = \"${pkgs.firejail}/etc/firejail/thunar.profile\";\n };\n # Sandbox a document viewer\n zathura = {\n executable = \"${lib.getBin pkgs.zathura}/bin/zathura\";\n profile = \"${pkgs.firejail}/etc/firejail/zathura.profile\";\n };\n };\n };\n}\nwrappedBinaries is a list of applications you want to run inside a sandbox.\nOnly the apps in the wrappedBinaries attribute set will be automatically\nfirejailed when launched the usual way.
Other apps may be started manually using firejail <app>, or added to\nwrappedBinaries if you want automatic sandboxing, just make sure the profile\nexists.
To inspect which profiles are available, after rebuilding go to /nix/store/, I\nused Yazi to search for /firejail and followed it to firejail/etc, where the\nprofiles are.
There are many flags and options available with firejail, I suggest checking out\nman firejail.
There are comments explaining what’s going on in:\nfirejail/package.nix
\nFirejail is a SUID program that reduces the risk of security breaches by\nrestricting the running environment of untrusted applications using\nLinux namespaces and\nseccomp-bpf–Firejail Security Sandbox
\nIt provides sandboxing and access restriction per application, much like what\nAppArmor/SELinux does at a kernel level. However, it’s not as secure or\ncomprehensive as kernel-enforced MAC systems (AppArmor/SELinux), since it’s a\nuserspace tool and can potentially be bypassed by privilege escalation exploits.
\n\n\nYou cannot effectively use Firejail with Flatpak apps because of how\ntheir sandboxing technologies operate. Flatpak also won’t work with the\nhardened kernel because they require unprivileged user namespaces which the\nhardened kernel completely disables.
\n
Flatpak permissions & What they Do\nReference this while setting permissions with Flatseal, many apps come with\nmore permissions than they need to function effectively breaking the sandbox.
\nPortals\nprovide mediated, user-controlled access to host resources outside the\nsandbox, so apps don’t need broad blanket permissions.
\nApps that don’t have a flatpak equivalent can be further hardened with\nbubblewrap independently but bubblewrap is not needed on Flatpak apps.
\nBecause of this limited native MAC (Mandatory Access Control) support on NixOS,\nusing Flatpak is often a good approach to get sandboxing and isolation for many\nGUI apps.
\nFlatpak bundles runtimes and sandbox mechanisms that provide app isolation\nindependently of the host system’s AppArmor or SELinux infrastructure. This\ncan improve security and containment for GUI applications running on NixOS\ndespite the system lacking full native MAC coverage.
\nFlatpak apps benefit from sandboxing through bubblewrap, which isolate apps\nand restrict access to user/home and system resources.
\nAdd Flatpak with the FlatHub repository for all users:
\nservices.flatpak.enable = true;\n systemd.services.flatpak-repo = {\n wantedBy = [ \"multi-user.target\" ];\n path = [ pkgs.flatpak ];\n script = ''\n flatpak remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo\n # Only apps that are verified\n # flatpak remote-add --if-not-exists --subset=verified flathub-verified https://flathub.org/repo/flathub.flatpakrepo\n '';\n };\nxdg = {\n portal = {\n enable = true;\n extraPortals = [ pkgs.xdg-desktop-portal-gtk ];\n config.common.default = [ \"gtk\" ];\n };\n};\n# Disables screencopy\nsystemd.user.services.\"xdg-desktop-portal-wlr\" = {\n enable = false;\n};\nflake.nix:inputs = {\n flatpaks.url = \"github:in-a-dil-emma/declarative-flatpak/latest\";\n};\n# flatpak.nix\n{\n pkgs,\n inputs,\n ...\n}: {\n imports = [\n inputs.flatpaks.nixosModules.default\n ];\n services.flatpak = {\n enable = true;\n remotes = {\n \"flathub\" = \"https://dl.flathub.org/repo/flathub.flatpakrepo\";\n # \"flathub-beta\" = \"https://dl.flathub.org/beta-repo/flathub-beta.flatpakrepo\";\n };\n packages = [\n \"flathub:app/org.mozilla.firefox//stable\"\n \"flathub:app/com.bitwarden.desktop//stable\"\n # \"flathub-beta:app/org.kde.kdenlive/x86_64/stable\"\n # \":${./foobar.flatpak}\"\n \"flathub:/root/testflatpak.flatpakref\"\n ];\n overrides = {\n # note: \"global\" is a flatpak thing\n # if you ever ran \"flatpak override\" without specifying a ref you will know\n \"global\".Context = {\n filesystems = [\n \"home\"\n ];\n sockets = [\n \"!wayland\"\n \"!fallback-x11\"\n ];\n };\n \"org.mozilla.Firefox\" = {\n Environment = {\n \"MOZ_ENABLE_WAYLAND\" = 1;\n };\n Context.sockets = [\n \"!wayland\"\n \"!fallback-x11\"\n # \"x11\"\n ];\n };\n };\n };\n xdg.portal = {\n enable = true;\n extraPortals = [\n pkgs.xdg-desktop-portal-gtk\n ];\n config = {\n common.default = [\"gtk\"];\n };\n };\n}\n\n\nI got the above configuration to build successfully, one of the hardening\nsteps I took isn’t allowing either app to launch. I’ll update once I find\nwhich setting it is exactly. (01-13-26)
\n
Then you can either find apps through FlatHub or on\nthe cmdline with flatpak search <app>. Flatpak is best used for GUI apps, some\nCLI apps can be installed through it but not all.
There is also nix-flatpak, which\nenables you to manage your flatpaks declaratively.
\nFlatseal is GUI\nutility that enables you to review and modify permissions from your Flatpak\napps. Many apps by default come with smart-card support, X11 & Wayland\nsupport, and more, disabling unnecessary permissions is recommended.
\nWarehouse provides\na simple UI to control complex Flatpak options, no cmdline required.
\nI have heard that it is not recommended to use Flatpak browsers because in order\nfor flatpak to work it has to disable some of the built-in browser sandboxing\nwhich can reduce security. I haven’t found any examples of Flatpak browsers\nbeing exploited but it’s something to keep in mind.
\nAppArmor is available on NixOS, but is still in a somewhat experimental and\nevolving state. There are only a few profiles that have been adapted to NixOS,\nsee here\nDiscourse on default-profiles\nWhich guides you here\napparmor/includes.nix\nwhere you can see some of the abstractions and tunables to follow progress.
\nSELinux: Experimental, not fully integrated, recent progress for\nadvanced/curious users; expect rough edges and manual intervention if you want\nto try it. Most find SELinux more complex to configure and maintain than\nAppArmor.
\nThis isn’t meant to be a comprehensive guide, more to get people thinking about\nsecurity on NixOS.
\nSee the following guide on hardening networking:
\n\nnix-mineral (Community Project)For users seeking a more comprehensive and opinionated approach to system\nhardening beyond the built-in hardened profile, the community project\nnix-mineral offers a declarative\nNixOS module.
nix-mineral aims to apply a wide array of security configurations, focusing on\ntweaking kernel parameters, system settings, and file permissions to reduce the\nattack surface.
nix-mineral is a community-maintained project\nand is not officially part of the Nixpkgs repository or NixOS documentation.\nIts development status is explicitly stated as “Alpha software,” meaning it\nmay introduce stability issues or unexpected behavior.For detailed information on nix-mineral’s capabilities and current status,\nrefer directly to its\nGitHub repository.
neal.codes vulnerability scan script:
\nnix-shell -p grype sbomnix --run '\n sbomnix /run/current-system --csv /dev/null --spdx /dev/null --cdx sbom.cdx.json;\n grype sbom.cdx.json\n'\nGovernment Resources 1st 6 come from gentoo’s Security_Handbook)
\nThe Austrailian Cyber Security Centre’s Informational Security Manual (ISM)
\nThe Australian Government’s Protective Security Policy Framework (PSPF)
\nThe Australian Cyber Security Centre’s Protect Yourself page
\nThe UK Government’s Information Security Policy Framework (ISF)
\nThe US National Institute of Standards and Technology’s Cybersecurity page
\nSTIGs are configuration standards developed by the Defense Information Systems\nAgency (DISA) to secure systems and software for the U.S. Department of\nDefense (DoD). They are considered a highly authoritative source for system\nhardening.There are recommendations for hardening all kinds of software in the\nStig Viewer
\nbentopdf: looks interesting, haven’t\nchecked it out yet though.
\n![](\"https://saylesss88.github.io/images/gruv9.png\")
\nThis explanation is based on insights from Infinisil, a prominent figure in the\nNix community, to help clarify the concept of top-level attributes within NixOS\nmodules.
\n\n\n[!NOTE] “top-level attributes” here refers to the attributes at the top level\nof a module file (imports, options, config), not to be confused with\n
\nsystem.build.toplevel, which is the final system derivation everything\nbuilds toward.
To understand why top-level module attributes matter, it helps to first\nunderstand what they’re ultimately building toward: system.build.toplevel, the\nfinal derivation that represents your entire NixOS system.
system.build.toplevelIn a NixOS system, everything is built from a single “system derivation.” The\ncommand 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\n'<nixpkgs/nixos>' file (which is essentially ./default.nix within the\nNixpkgs repository).
This system attribute is specifically the NixOS option system.build.toplevel\n. Think of system.build.toplevel as the very top of the configuration\nhierarchy for your entire NixOS system. Almost every setting you configure\neventually influences this top-level derivation, often through a series of\nintermediate steps.
Options in NixOS are not isolated; they often build upon each other.
\nHere’s an example of how a high-level option can lead down to a low-level system\nconfiguration:
\nservices.nginx.enable = true;.systemd.services.nginx.systemd.units.\"nginx.service\".environment.etc.\"systemd/system\".result/etc/systemd/system/nginx.service\nwithin the final system.build.toplevel derivation.So, how do these options get processed and turned into the final system\nconfiguration? That’s the job of the NixOS module system, located in the\n./lib directory of Nixpkgs (specifically in modules.nix, options.nix, and\ntypes.nix).
Interestingly, the module system isn’t exclusive to NixOS; you can use it to\nmanage option sets in your own Nix projects.
\nHere’s a simplified example of using the module system outside of NixOS:
\nlet\n systemModule = { lib, config, ... }: {\n options.toplevel = lib.mkOption {\n type = lib.types.str;\n };\n\n options.enableFoo = lib.mkOption {\n type = lib.types.bool;\n default = false;\n };\n\n config.toplevel = ''\n Is foo enabled? ${lib.boolToString config.enableFoo}\n '';\n };\n\n userModule = {\n enableFoo = true;\n };\n\nin (import <nixpkgs/lib>).evalModules {\n modules = [ systemModule userModule ];\n}\nYou can evaluate the config.toplevel option from this example using:
nix-instantiate --eval file.nix -A config.toplevel\nThe module system processes a set of “modules” through these general steps:
\nImporting Modules: It recursively finds and includes all modules\nspecified in imports = [ ... ]; statements.
Declaring Options: It collects all option declarations defined using\noptions = { ... }; from all the modules and merges them. If the same option\nis declared in multiple modules, the module system handles this (details\nomitted for simplicity).
Defining Option Values: For each declared option, it gathers all the\nvalue assignments (defined using config = { ... }; or directly at the top\nlevel if no options or config are present) from all modules and merges\nthem according to the option’s defined type.
\n\n[!NOTE] Option evaluation is lazy, meaning an option’s value is only computed\nwhen it’s actually needed. It can also depend on the values of other options.
\n
Top-Level Attributes in a Module: imports, options, and config
Within a NixOS module (the files that define parts of your system configuration)\n, the attributes defined directly at the top level of the module’s function have\nspecific meanings:
\nimports: This attribute is a list of other module files to include. Their\noptions and configurations will also be part of the evaluation.
options: This attribute is where you declare new configuration options. You\ndefine their type, default value, description, etc., using functions like\nlib.mkOption or lib.mkEnableOption.
config: This attribute is where you assign values to the options that have\nbeen 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\nyour module, any other attributes that are not option declarations must be moved\ninside the config attribute.
Let’s look at an example of what not to do:
\n{ pkgs, lib, config, ... }:\n{\nimports = [];\n\n# Defining an option at the top level\n\noptions.mine.desktop.enable = lib.mkEnableOption \"desktop settings\";\n\n# This will cause an error because 'environment' and 'appstream'\n\n# are not 'options' and 'config' is also present at the top level.\n\nenvironment.systemPackages =\nlib.mkIf config.appstream.enable [ pkgs.git ];\n\nappstream.enable = true;\n}\nThis will result in the error:\nerror: 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\nenvironment.systemPackages and appstream.enable inside the config attribute:
{ pkgs, lib, config, ... }:\n{\nimports = [];\n\n# Defining an option at the top level\n\noptions.mine.desktop.enable = lib.mkEnableOption \"desktop settings\";\n\nconfig = {\nenvironment.systemPackages =\nlib.mkIf config.appstream.enable [ pkgs.git ];\n\n appstream.enable = true;\n\n};\n}\nNow, Nix knows that you are declaring an option (options.mine.desktop.enable)\nand then setting values for other options (environment.systemPackages,\nappstream.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,\nthen any attributes you define directly at the top level are implicitly treated\nas being part of the config.
For example, this is valid:
\n{ pkgs, lib, config, ... }:\n{\nenvironment.systemPackages =\nlib.mkIf config.appstream.enable [ pkgs.git ];\n\nappstream.enable = true;\n}\nNix will implicitly understand that environment.systemPackages and\nappstream.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\nsection, the config = { environment.systemPackages = ... }; part will still\nfunction correctly, assuming the option it’s referencing (appstream.enable in\nthis case) is defined elsewhere (e.g., in an imported module).
Understanding the nuances of top-level attributes within NixOS modules,\nparticularly imports, options, and config, is fundamental to structuring\nand managing your system’s configuration effectively. As we’ve seen, the module\nsystem provides a powerful and declarative way to define and evaluate system\nsettings, ultimately contributing to the construction of the\nsystem.build.toplevel derivation that represents your entire NixOS\nenvironment.
The concepts of option declaration and value assignment, along with the crucial\nrule of organizing non-option attributes under the config attribute when\noptions is present, provide a clear framework for building modular and\nmaintainable configurations.
Now that we have a solid grasp of how NixOS modules are structured and how they\ncontribute to the final system derivation, it’s a natural next step to explore\nthe tangible results of these configurations: the software and system components\nthemselves. These are built and managed by a core concept in Nix, known as\nderivations.
\nIn the next chapter,\nPackage Definitions Explained\nwe will shift our focus from the abstract configuration to the concrete software\npackages. We will learn how Nix uses package definitions to create\nderivations, which are the actual build plans that produce the software we use\non our NixOS systems. This will bridge the gap between configuring your system\nand understanding how the software within it is managed.
\n", "date_published": "2026-05-31T00:00:00+00:00", "author": { "name": "saylesss87@proton.me (saylesss88)" } }, { "id": "https://saylesss88.github.io/vcs/practical_jj.html", "url": "https://saylesss88.github.io/vcs/practical_jj.html", "title": "Practical Jujutsu", "content_html": "This post assumes basic understanding of Git and GitHub.
\nI’ve spent enough time hovering between the familiarity of Git and the potential\nof Jujutsu. It’s time to move past a ‘primitive’ workflow. By truly mastering\none of these tools, I want to turn version control from a chore into a way to\nprecisely navigate my development stages and build a history that future\ncontributors can actually follow.
\nJJ simplifies keeping a linear history and makes it easy to break down big\nchanges into smaller atomic changes.
\n\n\n\n\n<header>\n<BLANK LINE>\n<body>\n<BLANK LINE>\n<footer>\n\n
\n- The
\nheaderis mandatory.- The
\nbodyis mandatory for all commits except “doc” type commits.- The
\nfooteris optional
An atomic commit is a single unit of work that cannot be broken down further\nwithout losing its meaning.
\nOne commit should do one thing.
\nIf you had to “undo” that commit later, would it break unrelated features? If\n“Yes,” it’s not atomic.
\nIf you find a bug, you can pinpoint the exact 10 lines of code that caused it.\nIn jj, the split -i and commit -i commands are the ultimate tools for\n“atomizing” a messy afternoon of coding.
A linear history is a straight line of commits without “merge bubbles” (those\ncriss-crossing lines you see in Git logs when people use git merge).
\nEvery commit has exactly one parent and one child.
\nIt reads like a story. You can follow the evolution of the project from bottom\nto top without getting lost in a maze of branches.
\njj defaults to a rebase-heavy workflow. Instead of “merging” your work and\ncreating a mess, you are constantly “sliding” your changes on top of the\nlatest work, keeping that line perfectly straight.
You can even insert a commit anywhere in your history with jj new -A\n(--insert-after), and jj new -B (--insert-before) and JJ will rebase every\nchild in the history.
Use jj show -r <revision> to see a diff of the changes made at that Change ID,\nand trivially craft it with jj edit -r <revision>.
Let’s learn about jj by using it to version control a system Nix Flake.
\n\n“One of the first things to wrap your head around when first coming to Jujutsu\nis its approach to its revisions and revsets, i.e. “sets of revision”.\nRevisions are the fundamental elements of changes in Jujutsu, not “commits” as\nin Git. Revsets are then expressions in a functional language for selecting a\nset of revisions.”\n–Chris Krycho jj init
\n
| 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,\njj squash all default to it. Bookmarks like main are just labels - move\nthem explicitly with jj bookmark set.
See\nzerowidths jj-tips-and-tricks,\nfor a more intuitive --interactive workflow (The git add -p Hunk-wise\nstyle).
It’s helpful to grasp a few Git concepts to fully understand some of the\nbenefits and strengths of jujutsu. I highly suggest reading\nW3Tutorials.net How to Compare Working Copy, Staging Copy, and Committed Copy of a File in Git,\nit covers most of the concepts that make understanding jj easier.
The Working Copy is the version of the file you’re actively editing in\nyour filesystem. It’s the “live” version you see in your text editor or IDE.\n–W3Tutorials.net
\n\n\n“Unlike most other VCSs, Jujutsu will automatically create commits from the\nworking-copy contents when they have changed. Most
\njjcommands you run will\ncommit the working-copy changes if they have changed. The resulting revision\nwill replace the previous working-copy revision.”
In Git, HEAD is a pointer (usually to a branch like main), and that branch\npoints to the current commit.
In jj, the working copy @ is itself the current commit. Bookmarks like main\nsimply point at other commits in the graph, so your working copy is often a\nchild 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\nFetching into new repo in \"/home/jr/projects/nix-snake\"\nremote: Enumerating objects: 88, done.\nremote: Total 88 (delta 38), reused 78 (delta 30), pack-reused 0 (from 0)\nbookmark: main@origin [new] tracked\nSetting the revset alias `trunk()` to `main@origin`\nWorking copy (@) now at: s f143a1da (empty) (no description set)\nParent commit (@-) : l 3b759dfe main | feat: fix clippy lints & optimize\nAdded 12 files, modified 0 files, removed 0 files\nHint: Running `git clean -xdf` will remove `.jj/`!\nmain@origin bookmark is automatically tracked with\na revset alias of trunk().\n\nNOTE: My jj commands show the shortest possible IDs because of the setting:
\n\nprograms.jujutsu.settings = {\n template-aliases = {\n \"format_short_change_id(id)\" = \"id.shortest()\";\n };\n};\n
Running jj st & jj log:
❯ jj st\nThe working copy has no changes.\nWorking copy (@) : s f143a1da (empty) (no description set)\nParent commit (@-): l 3b759dfe main | feat: fix clippy lints & optimize\n\n❯ jj log\n@ s sayls8@proton.me 2026-03-21 16:31:59 f143a1da\n│ (empty) (no description set)\n◆ l sayls8@proton.me 2026-01-29 16:50:51 main 3b759dfe\n│ feat: fix clippy lints & optimize\n~\nTo show all ancestors of the most recent commit, s in this case:
jj log -r ::s\nThe @ indicates the working-copy commit. The first ID on a line (e.g. “s”\nabove) is the change ID. The second ID is the commit ID (“f143a1da”). You can\ngive either ID to commands that take revisions as arguments.
jj log defaults to the ui.default-revset setting, or\n@ | ancestors(immutable_heads().., 2) | heads(immutable_heads()) if it’s not\nset. (A revset)
jj commands default to operating on the working copy, @. jj undo, undoes\nyour 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,\nbuilding a stack of changes. Until you push those changes, you can continue to\njump around and edit them with jj edit. Once you push those changes to a\nremote, they then become immutable.
You don’t have to merge Change A into Change B, because Change B is\nalready built on top of Change A. It inherits every line of code from the\nfloors below it.
In Git, the working copy is the files on disk; changes only become part of the\nnext commit when you stage them in the index with git add. In Jujutsu, the\nworking copy is the current commit: your edits live in a “working copy commit”\n(@), which jj automatically updates from the files on disk, and there is no\nseparate staging area.
When you’re ready to push to GitHub, make sure you know where your changes are.\nIn the example above, the working copy is empty, so to push I’d run\njj bookmark set main -r @- to point the main bookmark at the latest changes,\nthen jj git push.
jj git push: By default, pushes tracking bookmarks pointing to\nremote_bookmarks(remote=<remote>)..@. Use --bookmark to push specific\nbookmarks. Use --all to push all bookmarks. Use --change to generate\nbookmark 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\ninstead run jj bookmark set main -r @, followed by jj git push. Once you\nunderstand 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\nyou have uncommitted changes, it pushes those.
If your Working Copy (@) is empty , and main is on the Parent (@-), it\npushes the parent.
In the above example, if I remove the config argument to the\nconfiguration.nix and remove a few comments, then run jj diff:
![\"jj](\"https://saylesss88.github.io/../images/jj-diff.png\")
The squash workflow would benefit especially from jj diff. It’s like\nsaying “take the diff I’m looking at right now and bake it directly into the\nparent”.
A change is a commit that can evolve while keeping a stable identifier,\nthe change ID.
\nIt’s helpful to use\nConventional Commits, a set of\nrules for creating an explicit commit history.
\nCommit message standard syntax:
\n<type>[optional scope]: <description>\n\n[optional body]\n\n[optional footer(s)]\nExample:
\nfeat: implement dendretic pattern for boot module\nUseful Utils
\nThere is a new project that helps you create conventional commits for jj,\njj-commit.
\ncommitlint-rs can be used as a Git\nhook on push to enforce conventional commits.
\nsemantic-release\nautomates the whole package release workflow.
\nUsing Tags
\nTags are just named pointers to commits. Create one pointing to your latest\nchange:
\njj st\nThe working copy has no changes.\nWorking copy (@) : ysrlmzlt 7d093162 (empty) (no description set)\nParent commit (@-): wmuwoply ea03805e chore: add 'release version' to justfile\njj tag set v0.1.5 --revision @-\njj git push --tags\ncargo publish\nWhen you publish next, create a new tag v0.1.6.
The simple order:
\nWrite code, commit, jj git push as normal (many times)
When ready to release:
\nCargo.toml to 0.1.6jj git pushjj tag set v0.1.6 --revision @-jj git push --tag v0.1.6 # This only pushes the tag, not the commit againcargo publishThat’s it. Tags only appear at step 2, once per release.
\nOne tag per release, on the commit you publish. Everything in between is just\nnormal commits with no tags involved.
\nYou can also use -dev tags between releases. Right after the release, set your\nversion in your Cargo.toml to 0.1.7-dev and that will make clear which\ncommit’s haven’t been published yet.
Initialize and colocate the repository:
\n❯ mkdir learn-jj\n\n ~/projects\n❯ cd learn-jj\n\n\n ~/projects/learn-jj\n❯ nix flake new . -t github:nix-community/home-manager#nixos\nwrote: \"/home/jr/projects/learn-jj/flake.nix\"\n\n ~/projects/learn-jj ✗\n❯ jj git init --colocate\nInitialized repo in \".\"\nHint: Running `git clean -xdf` will remove `.jj/`!\n\n learn-jj main [?]\n❯ jj git remote add origin git@github.com:sayls8/learn-jj.git\n\n learn-j main [?]\n❯ jj bookmark create main -r @\nDone importing changes from the underlying Git repo.\nCreated 1 bookmarks pointing to l bd3847c0 main | (no description set)\n\n learn-jj refs/jj/root [!]\n❯ jj bookmark track main --remote=origin\nStarted tracking 1 remote bookmarks.\nLet’s give it our current change a description:
\n❯ jj desc -m \"chore: Initialize system flake\"\nWorking copy (@) now at: l 743b170d main* | chore: Initialize system flake\nParent commit (@-) : z 00000000 (empty) (no description set)\nIn this example, the Parent commit is the root commit. The root commit is a\nvirtual commit at the root of every repository. It has a commit ID consisting of\nall ’0’s (00000000...) and a change ID consisting of all ’z’s (zzzzzzzz...).\nIt can be referred to in revsets by the function root().
With this workflow, your working copy is typically at your current change.
\nJJ treats the working copy as a commit rather than having an index like Git.
\nIf we wanted to push right now we could with jj git push (or equivalently\njj git push --bookmark main), but let’s first learn a bit more about how jj\nworks.
Let’s say we’re done with the current change and we’re ready to make it\nimmutable and start a new change:
\n❯ jj new -m \"chore: change username & hostname in flake.nix\"\nWorking copy (@) now at: p 6524f35a (empty) chore: change username & hostname in flake.nix\nParent commit (@-) : l 743b170d main* | chore: Initialize system flake\nAs stated above, jj commands default to the working copy. So jj new is the\nsame as jj new -r @. By running jj new repeatedly, we build a linear stack\nwhere each change is a child of the previous one. When we’re ready to ‘check\nin’ our work, we don’t merge; we simply move the main bookmark to our\ncurrent position and push.
jj new main (or any other Change ID). This creates a sibling\nchange. Our previous stack isn’t “lost”; it stays exactly where it was in\nthe graph, waiting to be described, rebased, or merged later.Now our Working copy @ is at an (empty) change with the description\n“chore: change username & hostname in flake.nix”.
As you can see, running jj new, does not move the main bookmark. This is\nthe hardest part to grasp when coming from Git IMO. Let’s make some more\nchanges to hammer this home.
I’ve added my hostname and username to the flake.nix template, let’s make them\na part of the permanent record.
I create a minimal configuration.nix, check my status and notice that I forgot\nto run jj new -m \"feat: create minimal configuration.nix\". Let’s see how to\nrecover from this and keep our commits atomic.
jj split -i\ny for the changes related to\nusername and hostname. After you pass on what you don’t want in this change\nand press y on what you do want, your $EDITOR will open with your previous\ncommit message. Save it and another commit message will open up in $EDITOR,\nthis is whatever you didn’t press y on i.e., the configuration.nix\nchanges, just give the second set of changes a different description and\nyou’re all set.Another cool thing about jj is that you can add a description whenever you\nwant. Running jj desc -m \"add configuration.nix\" doesn’t finalize your commit\nlike it does with Git. So, you can put the description first, last, or in the\nmiddle of a current change with no issue. The equivalent command to\ngit commit -m \"message\" is jj commit -m \"message\" && jj new
Let’s see what the jj split -i command left us with:
❯ jj\nWorking copy changes:\nA configuration.nix\nWorking copy (@) : m b3cc09db feat: create minimal configuration.nix\nParent commit (@-): p cddde3b4 chore: change username & hostname in flake.nix\njj show -r @-\nAnd our log:
❯ jj log\n@ m sayles8@proton.me 2026-03-15 13:43:31 b3cc09db\n│ feat: create minimal configuration.nix\n○ p sayls8@proton.me 2026-03-15 13:41:19 cddde3b4\n│ chore: change username & hostname in flake.nix\n○ l sayls8@proton.me 2026-03-15 13:37:29 main* 743b170d\n│ chore: Initialize system flake\n◆ z root() 00000000\nAs you can see, main* is all the way back at change l. Let’s move our main\nbookmark to our current Working copy.
❯ jj bookmark set main -r @\nMoved 1 bookmarks to m b3cc09db main* | feat: create minimal configuration.nix\n❯ jj log\n@ m sayls8@proton.me 2026-03-15 13:43:31 main* b3cc09db\n│ feat: create minimal configuration.nix\n○ p sayls8@proton.me 2026-03-15 13:41:19 cddde3b4\n│ chore: change username & hostname in flake.nix\n○ l sayls8@proton.me 2026-03-15 13:37:29 743b170d\n│ chore: Initialize system flake\n◆ z root() 00000000\n❯ jj git push\nChanges to push to origin:\n Add bookmark main to b3cc09dba32c\ngit: Enumerating objects: 9, done.\ngit: Counting objects: 100% (9/9), done.\ngit: Delta compression using up to 16 threads\ngit: Compressing objects: 100% (7/7), done.\ngit: Writing objects: 100% (9/9), 1.99 KiB | 1019.00 KiB/s, done.\ngit: Total 9 (delta 1), reused 0 (delta 0), pack-reused 0 (from 0)\nremote: Resolving deltas: 100% (1/1), done.\nWarning: The working-copy commit in workspace 'default' became immutable, so a new commit has been created on top of it.\nWorking copy (@) now at: u 551e83ad (empty) (no description set)\nParent commit (@-) : m b3cc09db main | feat: create minimal configuration.nix\n❯ jj log\n@ u sayls8@proton.me 2026-03-15 13:47:27 551e83ad\n│ (empty) (no description set)\n◆ m sayls8@proton.me 2026-03-15 13:43:31 main b3cc09db\n│ feat: create minimal configuration.nix\nNotice jj log now shows main instead of main*, indicating that main\nand origin@main are in sync!
Also notice the ◆ next to the m change, this indicates that this change is\nnow 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\nhave pulled. You can still force-edit if you need to but it’s jjs way of\nsaying, “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\nforgot anything.
If something isn’t being picked up by jj try running jj st and check again.\nRunning any jj command updates the Working copy.
Since when running jj git push jj automatically creates a new commit on top\nof 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\nnetworking.hostId required by ZFS, if I wanted to be a stickler about atomic\ncommits I’d run jj split -i again but it’s fine by me to make 2 small changes\nto get the flake to pass the check.
The last section left me with:
\n❯ jj st\nWorking copy changes:\nM configuration.nix\nA flake.lock\nA hardware-configuration.nix\nA home.nix\nWorking copy (@) : u e57a7a39 feat: add minimal home.nix\nParent commit (@-): m b3cc09db main | feat: create minimal configuration.nix\nLet’s push what we have:
\n❯ jj bookmark set main -r @\nMoved 1 bookmarks to u e57a7a39 main* | feat: add minimal home.nix\n\n learn-jj HEAD [!]\n❯ jj git push\nChanges to push to origin:\n Move forward bookmark main from b3cc09dba32c to e57a7a39957a\ngit: Enumerating objects: 8, done.\ngit: Counting objects: 100% (8/8), done.\ngit: Delta compression using up to 16 threads\ngit: Compressing objects: 100% (6/6), done.\ngit: Writing objects: 100% (6/6), 1.98 KiB | 1.98 MiB/s, done.\ngit: Total 6 (delta 1), reused 0 (delta 0), pack-reused 0 (from 0)\nremote: Resolving deltas: 100% (1/1), completed with 1 local object.\nWarning: The working-copy commit in workspace 'default' became immutable, so a new commit has been created on top of it.\nWorking copy (@) now at: y 53e8a3d9 (empty) (no description set)\nParent commit (@-) : u e57a7a39 main | feat: add minimal home.nix\n❯ jj st\nThe working copy has no changes.\nWorking copy (@) : y 53e8a3d9 (empty) (no description set)\nParent commit (@-): u e57a7a39 main | feat: add minimal home.nix\nGreat, just what we need, an empty change! Let’s describe what we plan on doing:
\njj desc -m \"refactor: restructure flake to multi-host layout in hosts/magic\"\nNow we create a new change on top of this one:
\n❯ jj new\nWorking copy (@) now at: w 43195106 (empty) (no description set)\nParent commit (@-) : y c66bc991 (empty) refactor: restructure flake to multi-host layout in hosts/magic\nNow we make our changes to the descriptionless Working copy and squash our\nchanges into the parent commit.
mkdir -p hosts/magic\njj st\nThe working copy has no changes.\nWorking copy (@) : w 43195106 (empty) (no description set)\nParent commit (@-): y c66bc991 (empty) refactor: restructure flake to multi-host layout in hosts/magic\nAhh, jj doesn’t pick up empty directories…
mv configuration.nix home.nix hosts/magic\n jj st\nWorking copy changes:\nR {configuration.nix => hosts/magic/configuration.nix}\nR {home.nix => hosts/magic/home.nix}\nWorking copy (@) : w 8c49fc64 (no description set)\nParent commit (@-): y c66bc991 (empty) refactor: restructure flake to multi-host layout in hosts/magic\nR = Renamed. jj is pretty clever here. Since I moved the files but their\ncontents stayed the same, jj detected that I didn’t just “delete” one file\nand “add” a new one, I actually moved an object from point A to point B.\njj shows R {home.nix => hosts/magic/home.nix} means it is\nkeeping the history of that file intact. If you were to look at the log for\nhosts/magic/home.nix later, jj would know to look back into the history\nof the old home.nix as well.I’m happy with the changes so far:
\n❯ jj squash\nWorking copy (@) now at: k 41deb985 (empty) (no description set)\nParent commit (@-) : y 2bee669a refactor: restructure flake to multi-host layout in hosts/magic\nw disappeared and y is no longer empty? That’s because\nwe squashed the changes from our Working copy into the parent commit!Let’s look at what we have:
\n❯ jj st\nThe working copy has no changes.\nWorking copy (@) : k 41deb985 (empty) (no description set)\nParent commit (@-): y 2bee669a refactor: restructure flake to multi-host layout in hosts/magic\nSince the working copy is at an (empty) change, it wouldn’t make sense to push\nit. We have to move our bookmark to the parent commit, and then push!
❯ jj bookmark set main -r @-\nMoved 1 bookmarks to y 2bee669a main* | refactor: restructure flake to multi-host layout in hosts/magic\n❯ jj git push\nChanges to push to origin:\n Move forward bookmark main from e57a7a39957a to 2bee669ac276\ngit: Enumerating objects: 5, done.\ngit: Counting objects: 100% (5/5), done.\ngit: Delta compression using up to 16 threads\ngit: Compressing objects: 100% (3/3), done.\ngit: Writing objects: 100% (4/4), 452 bytes | 452.00 KiB/s, done.\ngit: Total 4 (delta 1), reused 0 (delta 0), pack-reused 0 (from 0)\nremote: Resolving deltas: 100% (1/1), completed with 1 local object.\nThis was the biggest Aha moment I had. It makes perfect sense that you wouldn’t\nwant to push a change that changes nothing. Since we squashed the contents of\nthe Working copy into @-, that is where we need main to point.
I have an alias:
\n la = [\n \"log\"\n \"-r\"\n \"all()\"\n ];\nYou can also list all commits with:
\njj log -r ::\n# or\njj log r 'all()'\nLet’s check out our full history so far:
\n❯ jj la\n@ k sayls8@proton.me 2026-03-15 14:30:43 41deb985\n│ (empty) (no description set)\n◆ y sayls8@proton.me 2026-03-15 14:30:43 main 2bee669a\n│ refactor: restructure flake to multi-host layout in hosts/magic\n◆ u sayls8@proton.me 2026-03-15 14:07:28 e57a7a39\n│ feat: add minimal home.nix\n◆ m sayls8@proton.me 2026-03-15 13:43:31 b3cc09db\n│ feat: create minimal configuration.nix\n◆ p sayls8@proton.me 2026-03-15 13:41:19 cddde3b4\n│ chore: change username & hostname in flake.nix\n◆ l sayls8@proton.me 2026-03-15 13:37:29 743b170d\n│ chore: Initialize system flake\n◆ z root() 00000000\nTextbook linear history. Every single commit has exactly one parent, forming a\nsingle, unbroken chain from the root() up to the current working copy.
The diamonds ◆ show that everything from y down is now part of the\npermanent record (pushed to the remote).
In Git, achieving this usually requires git add, git commit --amend, or an\ninteractive rebase. In jj, you just worked in the working copy and pushed, the\ntool handled the “shaping” of the history for you.
Bookmarks are named pointers to revisions (just like branches are in Git). You\ncan move them without affecting the target revision’s identity. – Jujutsu docs
\nBranches are just multiple “changes” with the same parent.
\nList all available bookmarks
\n❯ jj bookmark list --all\nfeat1 (deleted)\n @origin: xo 9067e7b7 mangowc flake-parts module\nmain: s b250e6ed testing the push-on-new non working bs\n @git: s b250e6ed testing the push-on-new non working bs\n @origin (behind by 2 commits): o 65e79e4b jj bookmarks push-on-new\nHint: 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.\nEvery time you run jj git push, jj automatically runs jj new main for you\nbecause the working copy becomes immutable after the push.
Show heads of all anonymous branches:
\njj log -r 'heads(all())'\nTo visualize an anonymous branch, Steve’s Jujutsu tutorial does a great job of\ndisplaying this:
\n\n ┌───┐ ┌───┐\n ┌───┤ F ◄─┤ G │\n │ └───┘ └───┘\n │\n ┌───┐ ┌───┐ ┌─▼─┐ ┌───┐ ┌───┐\n │ A ◄──┤ B ◄──┤ C ◄─┤ D ◄─┤ E │\n └───┘ └───┘ └───┘ └───┘ └───┘\n\nHere, we’d say that F and G are two changes that are “on a branch,” because\nit looks like they’re branching off from D and E.\nSteves Jujutsu tutorial What is a branch conceptually?
The above sentence confused me a bit. F and G are described as branching\n“off” of the line containing D and E. However, in the literal graph\nstructure, they diverge from C.
Since F and D both point to C, they are “siblings”. Because no other\ncommits 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.\nSince E and G are both visible and unmerged, we have two “anonymous branches”\ncurrently active.
\nThe output of jj log -r 'heads(all())' with the above example, would yield:
○ G\n│\n~\n│\n○ E\n│\n~\nG and E are the heads of the anonymous branches.Start at an empty change:
\n❯ jj log\n@ p saylesss87@proton.me 2026-03-24 18:05:54 6469af06\n│ (no description set)\nGive the current change a description:
\njj desc -m \"refactor(waybar): waybar flake-parts module\"\n❯ jj log\n@ p saylesss87@proton.me 2026-03-24 18:06:31 627d846c\n│ refactor(waybar): waybar flake-parts module\n○ yl saylesss87@proton.me 2026-03-24 17:55:00 56d13161\n│ refactor(foot): foot flake-parts module\nTo create a branch we need 2 changes with the same parent, our current changes\nparent is yl so let’s make our new change off of that:
❯ jj new yl -m \"chore: add better documentation to README\"\nWorking copy (@) now at: v 4697897a (empty) chore: add better documentation to README\nParent commit (@-) : yl 56d13161 refactor(foot): foot flake-parts module\nAdded 1 files, modified 1 files, removed 1 files\nLet’s check out our log to see our anonymous branches:
\n❯ jj\n@ v saylesss87@proton.me 2026-03-24 18:12:04 4697897a\n│ (empty) chore: add better documentation to README\n│ ○ p saylesss87@proton.me 2026-03-24 18:06:31 627d846c\n├─╯ refactor(waybar): waybar flake-parts module\n○ yl saylesss87@proton.me 2026-03-24 17:55:00 56d13161\n│ refactor(foot): foot flake-parts module\nWe can see that p branches off from yl, let’s make this change before\nswitching to the other branch.
❯ jj st\nWorking copy changes:\nM README.md\nWorking copy (@) : v 23d94e56 chore: add better documentation to README\nParent commit (@-): yl 56d13161 refactor(foot): foot flake-parts module\n# This effectively moves the working copy to the other \"branch\"\n❯ jj edit p\nWorking copy (@) now at: p 627d846c refactor(waybar): waybar flake-parts module\nParent commit (@-) : yl 56d13161 refactor(foot): foot flake-parts module\nAdded 1 files, modified 2 files, removed 1 files\n\n\nIn Git, you
\ncheckouta branch name; injj, you just move your working copy\n(@) to whichever commit you want to build on.
I’ve added the new flake-parts module and deleted the old home-manager style\nmodule:
\n❯ jj st\nWorking copy changes:\nD home/waybar.nix\nM hosts/magic/home.nix\nA parts/waybar.nix\nWorking copy (@) : p 627d846c refactor(waybar): waybar flake-parts module\nParent commit (@-): yl 56d13161 refactor(foot): foot flake-parts module\nLet’s add another change on this branch to solidify these concepts:
\n❯ jj new -m \"refactor(nh): nh flake-parts module\"\nWorking copy (@) now at: n ac086b55 (empty) refactor(nh): nh flake-parts module\nParent commit (@-) : p 627d846c refactor(waybar): waybar flake-parts module\nAnd our log to show that this branch has grown:
\n❯ jj log\n@ n saylesss87@proton.me 2026-03-24 18:22:12 ac086b55\n│ (empty) refactor(nh): nh flake-parts module\n○ p saylesss87@proton.me 2026-03-24 18:06:31 627d846c\n│ refactor(waybar): waybar flake-parts module\n│ ○ v saylesss87@proton.me 2026-03-24 18:17:51 23d94e56\n├─╯ chore: add better documentation to README\n○ yl saylesss87@proton.me 2026-03-24 17:55:00 56d13161\n│ refactor(foot): foot flake-parts module\nNow, let’s first merge the README branch into this one. We are worried about the\nheads of the anonymous branches right now:
\n❯ jj log -r 'heads(all())'\n@ n saylesss87@proton.me 2026-03-24 18:22:12 ac086b55\n│ (empty) refactor(nh): nh flake-parts module\n~\n\n○ v saylesss87@proton.me 2026-03-24 18:17:51 23d94e56\n│ chore: add better documentation to README\nA merge is a new change that has more than one parent. With JJ, you make a\nchange with jj new. We can see that we need to make a change with both n and\nv as parents from the log output above:
❯ jj new n v -m \"feat: merge in README docs\"\nWorking copy (@) now at: yn a923db65 (empty) feat: merge in README docs\nParent commit (@-) : n ac086b55 (empty) refactor(nh): nh flake-parts module\nParent commit (@-) : v 23d94e56 chore: add better documentation to README\nAdded 0 files, modified 1 files, removed 0 files\n❯ jj log\n@ yn saylesss87@proton.me 2026-03-24 18:28:47 a923db65\n├─╮ (empty) feat: merge in README docs\n│ ○ v saylesss87@proton.me 2026-03-24 18:17:51 23d94e56\n│ │ chore: add better documentation to README\n○ │ n saylesss87@proton.me 2026-03-24 18:22:12 ac086b55\n│ │ (empty) refactor(nh): nh flake-parts module\n○ │ p saylesss87@proton.me 2026-03-24 18:06:31 627d846c\n├─╯ refactor(waybar): waybar flake-parts module\n○ yl saylesss87@proton.me 2026-03-24 17:55:00 56d13161\n│ refactor(foot): foot flake-parts module\nThat messes up our perfectly linear history, let’s rebase instead.
\n❯ jj undo\nUndid operation: a74a45f02043 (2026-03-24 18:28:47) new empty commit\nRestored to operation: 848c180f2a04 (2026-03-24 18:22:12) new empty commit\nWorking copy (@) now at: n ac086b55 (empty) refactor(nh): nh flake-parts module\nParent commit (@-) : p 627d846c refactor(waybar): waybar flake-parts module\nAdded 0 files, modified 1 files, removed 0 files\nRebase is your tool for changing the ‘parent’ of a commit. If you have two\nparallel features (siblings) and you decide one should follow the other (linear\nstack), you rebase the second feature onto the first.
\n❯ jj rebase -r v -o n\nRebased 1 commits to destination\nNow our history is back to being completely linear:
\n❯ jj log\n○ v saylesss87@proton.me 2026-03-24 18:30:36 8101b0dd\n│ chore: add better documentation to README\n@ n saylesss87@proton.me 2026-03-24 18:22:12 ac086b55\n│ (empty) refactor(nh): nh flake-parts module\n○ p saylesss87@proton.me 2026-03-24 18:06:31 627d846c\n│ refactor(waybar): waybar flake-parts module\n○ yl saylesss87@proton.me 2026-03-24 17:55:00 56d13161\n│ refactor(foot): foot flake-parts module\nTo move a stack of changes, use jj rebase -s [Source] -d [Destination]. If you\nwant to move a feature to the very tip of your main line, destination is main.\nIf you want to chain features together, destination is the previous feature’s\nhead.
Pay attention to where @ is while rebasing, to continue on this linear stack\nI’ll have to run jj new v.
So far all the examples assumed you are the only person touching this repo. For\ncollaboration (GitHub / GitLab PRs, code review, etc.), the mental model is:
\nGitHub only understands branches and commits.
\nJujutsu gives you changes and bookmarks.
\nYou use jj git push to translate your clean JJ history into a Git branch\nthat others can review.
A simple pattern that works well for feature branches and PRs:
\nmainMake sure main is up to date and your working copy is clean:
\njj git fetch\njj edit main\njj st\nYou should see an (empty) working copy with main as the parent.
In JJ, you don’t “checkout” a branch, you create a new change and (optionally)\ngive it a bookmark name:
\n# Create a new change on top of main and start working there\njj new main -m \"feat: add magic host\"\n\n# Optionally create a bookmark that GitHub will see as a branch\njj bookmark create feature/magic-host -r @\njj new main makes a sibling of any in‑progress work and starts a fresh\nchange on top of main.
The bookmark feature/magic-host is what will become the Git branch name when\nyou push.
Work in your normal JJ style:
\n# edit files\njj st\njj split -i\njj desc -m \"feat: add magic host\"\njj new\n# more changes, more desc/split/squash, etc.\nAll of this is still local, fully mutable history.
\nWhen you’re happy with the stack you want to send for review, move the bookmark\nto the tip:
\n# If your working copy @ is the commit you want reviewed:\njj bookmark set feature/magic-host -r @\n\n# If you used the squash workflow and @ is empty:\njj bookmark set feature/magic-host -r @-\nRule of thumb:
\nIf jj st shows actual changes or a non‑empty description at @, use @.
If @ is (empty) because you squashed into the parent, use @-.
Now push just like before, but your feature bookmark will become a branch on the\nremote:
\njj git push\nThis will:
\nUpdate origin/feature/magic-host to point at the same commit as your local\nfeature/magic-host.
Leave main alone until you explicitly move and push it.
On GitHub/GitLab:
\nYou’ll see a branch named feature/magic-host.
Open a PR from feature/magic-host into main as usual.
If a reviewer asks for changes:
\njj edit feature/magic-host\nMake your edits, split/squash/reword history freely.
\nMove the bookmark to the new tip and push again:
\njj bookmark set feature/magic-host -r @\njj git push\nGitHub will show the PR updating in place, but you got to reshuffle history\nlocally without git rebase -i pain.
“I just want a one‑off PR, no named bookmark”
\nIf you don’t care about a persistent bookmark and just want a quick “one‑shot”\nPR from whatever you’re currently working on:
\nMake sure your stack is in the shape you want.
\nPut main on the top of that stack:
\n# Working copy @ is the tip you want:\njj bookmark set main -r @\n# Or equivalently `jj bookmark set main` since commands default to the working copy\njj git push\nThis is essentially the same pattern we already use in the “squash workflow,”\nbut applied with the mental model: “move the bookmark people care about (main\nor a feature name) to the commit I want them to review, then push.”
You may want to change up how you work depending on your requirements…
\nYou use a tower when your changes build on top of each other.
\nmain → Feature A → Feature B → Feature C
Use it when you are refactoring a Nix module (Feature A), and then you need to\nuse that new module to configure your desktop (Feature B). You literally\ncannot do B without A.
\nThe Collaborative Benefit: You can push the entire stack. Your teammates see the\nlogical progression of your thought process. They can review “Feature A” while\nyou are already working on “Feature C.”
\njj new main) You use jj new main when you are\nworking on independent ideas that have nothing to do with each other.main → Fix-Helix-Keys\nmain → Update-Nix-Channel
main → New-Wallpaper-Script
When to use it: You’re in the middle of a massive system refactor, but you\nsuddenly notice your Helix C-p bind is broken. You don’t want the Helix fix to\nbe “trapped” behind the refactor.
\nThe Collaborative Benefit: Isolation. If your “System Refactor” is buggy and\ntakes three days to fix, you can still jj git push the “Helix Fix” to main\nimmediately because it’s a direct child of main. It isn’t “waiting” for the\nother commits.
Fixing Divergent Branches
\njj makes it easy to fix divergent branches with jj forget.
As an example imagine this scenario:
\nOn your Laptop: You finish a feature and jj git push. Local main and\norigin/main are now at Revision B.
\nOn your Desktop: You forgot to pull. Local main is still at Revision A. You\nstart hacking and create Revision C.
\nThe 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\ndeletes the main* label on your Desktop so you can just fetch the “real” one\nfrom the Laptop/GitHub and rebase your new work (C) on top of it.
Your History is just a stack of diffs:
\njj 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
\nThe Scenario: You’re in the middle of a complex Rust feature (Change C), and\nyou realize a function in the base (Change A) needs to be public or renamed for\nthis to work.
\njj new A -m \"quick fix\" → Creates a new “slice” right after A.
Make your change.
\njj 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\nto manage your focus.
When you start a session, create a few empty changes:
\njj 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\ndoing. jj tracks the progress of each. No need to stash when jumping between\ntasks because of the working copy commit.
Breaking up your Current set of Changes into Atomic Commits: “The Atomic\nShredder” jj split
Often I’ll just keep working on a bug or feature until it works, not\nparticularly concerned about my VCS history. Let’s say I spent 3 hours hacking\non a project of mine to get a feature working and I touched 10 files. It works,\nbut the commit is a mess.
\nWith the gitpatch tool, jj split -i makes it simple to break down many\nchanges 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\nin @ into smaller changes. jj commit -i is ergonomically tuned for “push\nsome 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\nin history.
As a rule of thumb:
\nChanges in @ → use jj commit -i to peel off a clean piece, and also\njj squash -i to squash a subset of changes from the working copy into the\nparent commit.
Changes in @- (or earlier) → use jj split -i to rewrite that commit
In the early days of Flakes, users often ended up with a massive, monolithic\nflake.nix or a spaghetti-like web of manual imports. The Dendritic (Tree-like)\nPattern solves this by treating your filesystem as the source of truth, using\nflake-parts as the nervous system that routes code to the correct outputs.
IMO the flake-parts docs could do a lot better at explaining how to use it to\nconfigure your system. I’ll attempt to explain how to use it and why you might\nwant to.
While flake-parts provides the core structure for standard flake outputs, its\nreal power lies in its modular ecosystem. You can plug in opinionated modules to\ninstantly add specialized features to your system’s nervous system.
![\"Dendritic](\"https://saylesss88.github.io/../images/dendritic_nix.png\")
–flake = { ... }; block.flake):This is for things that are global and don’t change regardless of whether\nyou’re on a Mac, PC or ARM server.
\nExample: Your nixosConfigurations or homeConfigurations.
A NixOS configuration for a specific laptop is a single, static definition. It\ndoesn’t need to be “multiplied” by system types.
\nperSystem)perSystem is for things that must be built for a specific architecture.\n(e.g., devShells, packages, formatter)
x86_64 version of helix on an aarch64 (ARM) MacBook.Our nixosConfigurations don’t live in a system specific attribute so it goes\nunder flake instead of perSystem.
You can place everything in the same file:
\noutputs = inputs@{ flake-parts, ... }:\n # https://flake.parts/module-arguments.html\n flake-parts.lib.mkFlake { inherit inputs; } (top@{ config, withSystem, moduleWithSystem, ... }: {\n imports = [\n # Optional: use external flake logic, e.g.\n # inputs.foo.flakeModules.default\n ];\n flake = {\n # Put your original flake attributes here.\n };\n systems = [\n # systems for which you want to build the `perSystem` attributes\n \"x86_64-linux\"\n # ...\n ];\n perSystem = { config, pkgs, ... }: {\n # Recommended: move all package definitions here.\n # e.g. (assuming you have a nixpkgs input)\n # packages.foo = pkgs.callPackage ./foo/package.nix { };\n # packages.bar = pkgs.callPackage ./bar/package.nix {\n # foo = config.packages.foo;\n # };\n };\n });\nOr you can break it down into modules:
\n{\n inputs = {\n nixpkgs.url = \"github:nixos/nixpkgs/nixos-unstable\";\n flake-parts.url = \"github:hercules-ci/flake-parts\";\n };\n\n outputs = inputs @ { flake-parts, ... }:\n flake-parts.lib.mkFlake { inherit inputs; }\n {\n # Supported Systems\n systems = [ \"x86_64-linux\" \"x86_64-darwin\"];\n imports = [ ./devShell.nix ./package.nix ./nixos.nix ]\n };\n\n}\ndevShell.nix:
{\n perSystem = { pkgs, ...}: {\n devShells.default = pkgs.mkShell {\n packages = [ pkgs.ripgrep pkgs.fd ];\n };\n};\n}\npackage.nix:
{\n perSystem = { pkgs, ...}: {\n packages.myPackage = pkgs.myPackage;\n };\n}\nThis is the flake that I’m currently using to slowly adopt the dendritic\npattern, or not if I choose not to. Maybe making every single thing a flake\noutput isn’t necessary or the best idea, we’ll see. With this, you can use both\nregular NixOS/home-manager modules and NixOS/home-manager flake-parts modules.
\nScalability Toggle:
\nI have ++ (builtins.attrValues ...) set for both home-manager and NixOS\nwhere it automatically adds the inputs for files in the ~/flake/parts\ndirectory. This is fine for personal use where you want the custom modules\navailable everywhere instantly.
If the flake gets too big and you want more control just comment out those 2\nlines in the nixos.nix and start explicitly adding the inputs to your\nimports list. Now the parts/ directory will act like a library rather than\na Registry, you manually pick what you want for each host.
Example: Let’s call this ~/flake/flake.nix
# In this example the top-level configuration is a [`flake-parts`](https://flake.parts) one.\n# Therefore, every Nix file (other than this) is a flake-parts module.\n# https://github.com/mightyiam/dendritic/blob/master/example/flake.nix\n{\n # Declares flake inputs\n inputs = {\n flake-parts = {\n url = \"github:hercules-ci/flake-parts\";\n inputs.nixpkgs-lib.follows = \"nixpkgs\";\n };\n\n import-tree.url = \"github:vic/import-tree\";\n\n nixpkgs.url = \"github:nixos/nixpkgs/25.11\";\n };\n\n outputs =\n inputs:\n inputs.flake-parts.lib.mkFlake { inherit inputs; } {\n # This tells flake-parts which systems to generate outputs for\n systems = import inputs.systems;\n\n imports = [\n # Optional: use external flake logic, e.g.\n inputs.treefmt-nix.flakeModule\n # Import home-manager's flake module\n # The flake module defines flake.homeModules and flake.homeConfigurations options,\n # allowing them to be properly merged if they are defined in multiple modules\n inputs.home-manager.flakeModules.default\n ./nixos.nix\n ]\n ++ (inputs.import-tree ./parts).imports;\n\n hosts = {\n magic = {\n username = \"jr\";\n system = \"x86_64-linux\";\n };\n # Adding a second machine is now 4 lines of code:\n # secondary = { username = \"jr\"; system = \"aarch64-linux\"; };\n };\n\n perSystem =\n {\n system,\n ...\n }:\n {\n\n # Access pkgs with your specific config\n _module.args.pkgs = import inputs.nixpkgs {\n inherit system;\n config.allowUnfree = false;\n };\n };\n\n };\n}\n\n\n\n
import-treeis essentially a “smarter” version of thescanPathsfunction\nthat we’ll see later specifically designed forflake-parts. It ensures that\nevery file in./partsis treated as a module that themkFlakeengine can\ndigest.
Note, this example has more code than for example the dendritic nix repo has\nbecause it enables you to automatically import flake-parts modules as well as\nstandard NixOS and home-manager modules as you move to the new system/pattern.
And ~/flake/nixos.nix:
/**\n System Configuration Factory Module\n\n This module defines a custom schema for describing multiple NixOS hosts\n and automatically generates the corresponding `nixosConfigurations` flakes output.\n*/\n{\n inputs,\n self,\n lib,\n config,\n ...\n}:\nlet\n # Internal Library & Module Imports\n\n # Initialize a custom library using the project's internal lib and nixpkgs\n myLib = import \"${self}/lib/default.nix\" { inherit (inputs.nixpkgs) lib; };\n\n # Import entry points for global NixOS and Home Manager shared modules\n # `self` points to the root of the flake (requires passing `self` throuth specialArgs)\n nixosModules = import \"${self}/nixos\";\n homeManagerModules = import \"${self}/home\";\n\n # Shared Binary Cache Configuration\n caches = {\n nix.settings = {\n builders-use-substitutes = true;\n substituters = [ \"https://cache.nixos.org\" ];\n trusted-public-keys = [ \"cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDShjY=\" ];\n };\n };\nin\n{\n /**\n SCHEMA DEFINITION\n Defines the 'hosts' option, allowing us to declare system metadata\n (e.g., username, architecture) in a structured attribute set.\n */\n options.hosts = lib.mkOption {\n description = \"An attribute set of host definitions to be generated.\";\n type = lib.types.attrsOf (\n lib.types.submodule {\n options = {\n username = lib.mkOption {\n type = lib.types.str;\n default = \"jr\";\n description = \"Primary user account name for this host.\";\n };\n system = lib.mkOption {\n type = lib.types.str;\n default = \"x86_64-linux\";\n description = \"The target system architecture.\";\n };\n };\n }\n );\n };\n /**\n CONFIGURATION GENERATION\n Iterates through the 'config.hosts' defined above and maps them to\n actual 'nixosSystem' instances for the Flake output.\n */\n config.flake.nixosConfigurations = lib.mapAttrs (\n host: cfg:\n inputs.nixpkgs.lib.nixosSystem {\n # Pass global context and metadata into the module system\n specialArgs = {\n inherit\n inputs\n self\n host\n myLib\n ;\n inherit (cfg) username;\n };\n\n modules = [\n # 1. Project-wide NixOS logic\n nixosModules\n\n # 2. Host-specific hardware/system configuration file\n \"${self}/hosts/${host}/configuration.nix\"\n\n # 3. Home Manager NixOS module (allows configuring HM within NixOS)\n inputs.home-manager.nixosModules.home-manager\n\n # 4. Standardized cache settings defined in 'let' block\n caches\n\n # 5. Inline configuration for system-specific and user-specific settings\n {\n nixpkgs.hostPlatform = cfg.system;\n home-manager = {\n # By default, Home Manager uses a private pkgs instance that is configured\n # via the home-manager.users.<name>.nixpkgs options. To instead use the\n # global pkgs that is configured via the system level nixpkgs options, set\n useGlobalPkgs = true;\n # Install packages to /etc/profiles rather than $HOME/.nix-profile\n useUserPackages = true;\n # Dynamically import the user's home configuration based on host/username\n users.${cfg.username} = {\n imports = [\n (import \"${self}/hosts/${host}/home.nix\")\n ]\n # Automatically import `homeModules` in `./parts`\n # Comment out if you want to be explicit and add\n # e.g., inputs.self.homeModules.helix\n ++ (builtins.attrValues config.flake.homeModules);\n };\n\n extraSpecialArgs = {\n inherit\n inputs\n homeManagerModules\n myLib\n host\n ;\n inherit (cfg) username;\n };\n };\n }\n ]\n # Automatically import `nixosModules` in `./parts`\n ++ (builtins.attrValues config.flake.nixosModules);\n }\n ) config.hosts;\n}\nNow, any flake-parts module that we place in the ~/flake/parts/ directory\nwill be automatically imported with import-tree. The key here is that it has\nto 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\ndirectory. Just import it to the correct location and you’re good.
Example NixOS module for amd drivers ~/flake/parts/amd-drivers.nix:
{\n flake.nixosModules.amd-drivers =\n {\n lib,\n pkgs,\n config,\n ...\n }:\n with lib;\n let\n cfg = config.custom.amd-drivers;\n in\n {\n options.custom.amd-drivers.enable = mkEnableOption \"AMD GPU/CPU optimized for AM06 Pro\";\n\n config = mkIf cfg.enable {\n # Modern ROCm/HIP support\n systemd.tmpfiles.rules = [ \"L+ /opt/rocm/hip - - - - ${pkgs.rocmPackages.clr}\" ];\n services.xserver.videoDrivers = [ \"amdgpu\" ];\n\n hardware = {\n amdgpu.initrd.enable = true;\n\n graphics = {\n enable = true;\n enable32Bit = true;\n extraPackages = with pkgs; [\n rocmPackages.clr.icd # For OpenCL/Compute\n # Hardware Acceleration (Video Encoding/Decoding)\n libva\n libva-utils\n libva-vdpau-driver\n libvdpau-va-gl\n ];\n };\n\n cpu.amd.updateMicrocode = true;\n };\n\n boot = {\n kernelModules = [\n \"kvm-amd\"\n \"amdgpu\"\n ];\n kernelParams = [\n \"amd_pstate=active\" # Best for Ryzen 5000+ power management\n ];\n };\n\n boot.kernelPackages = pkgs.linuxPackages_latest;\n };\n };\n}\nNow, to enable this module, I’ll add this to my configuration.nix or\nequivalent:
{...}: {\n imports = [\n # Not necessary because of the `++ (builtins.attrValues config.flake.nixosModules)` in nixos.nix\n # for more control remove those lines and explicitly add:\n # inputs.self.nixosModules.amd-drivers\n ];\n\n custom = {\n amd-drivers.enable = true;\n };\n}\n# ---snip---\nExample home-manager module ~/flake/parts/fzf.nix:
{\n flake.homeModules.fzf =\n { lib, config, ... }:\n let\n cfg = config.custom.fzf;\n in\n {\n options.custom.fzf.enable = lib.mkEnableOption \"Enable fzf module\";\n\n config = lib.mkIf cfg.enable {\n programs.fzf = {\n enable = true;\n # colors = lib.mkForce { };\n\n defaultOptions = [\n \"--height 40%\"\n \"--reverse\"\n \"--border\"\n \"--color=16\"\n ];\n\n defaultCommand = \"rg --files --hidden --glob=!.git/\";\n };\n };\n };\n}\nAnd 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\n++ (builtins.attrValues config.flake.homeModules); in nixos.nix. Without\nthe automatic import, add inputs.self.homeModules.fzf to your imports list\nin your home.nix or equivalent.
If you don’t like the auto-import behavior, just delete or comment out that\nline, after that, the import statements become necessary.
~/flake/parts/shells/zsh.nix:
{\n flake.nixosModules.zsh =\n {\n pkgs,\n lib,\n config,\n username,\n ...\n }:\n let\n cfg = config.custom.zsh;\n in\n {\n options.custom.zsh = {\n enable = lib.mkEnableOption \"User zsh configuration\";\n };\n\n config = lib.mkIf cfg.enable {\n\n # 1. NixOS System-Level (The \"Foundation\")\n programs.zsh.enable = true;\n users.defaultUserShell = pkgs.zsh;\n environment.pathsToLink = [ \"/share/zsh\" ]; # Fixes completion for system packages\n\n # 2. Home Manager (User Configuration)\n home-manager.users.${username} = {\n programs.zsh = {\n enable = true;\n enableCompletion = true;\n completionInit = \"autoload -U compinit && compinit\";\n autosuggestion.enable = true;\n syntaxHighlighting.enable = true;\n oh-my-zsh = {\n package = pkgs.oh-my-zsh;\n enable = true;\n plugins = [\n \"git\"\n \"sudo\"\n \"rust\"\n \"fzf\"\n ];\n };\n profileExtra = ''\n if [ -z \"$DISPLAY\" ] && [ \"$XDG_VTNR\" = 1 ]; then\n exec mango\n fi\n # ---snip----\n}\n\n\nNOTE: Passing
\nusernamethroughspecialArgsis what makes this bridge work,\nyou can also just use your username.
This is what ~/flake/parts/shells/default.nix looks like, I had to explicitly\nadd myLib in a let statement to prevent infinite recursion:
{ lib, ... }:\nlet\n # prevents infinite recursion error\n myLib = import ../../lib { inherit lib; };\nin\n{\n # Now we can use it safely\n imports = myLib.scanPaths ./.;\n}\nEnable it in configuration.nix or equivalent:
custom.zsh.enable = true;\nlib/default.nix is just a function that automatically imports any .nix file,\nskipping default.nix:
{ lib, ... }:\n{\n # Returns a list of all .nix files and directories in a path,\n # skipping default.nix. Perfect for the 'imports' list.\n scanPaths =\n path:\n let\n content = builtins.readDir path;\n in\n map (name: path + \"/${name}\") (\n builtins.attrNames (\n lib.filterAttrs (\n name: type: (type == \"directory\") || (name != \"default.nix\" && lib.hasSuffix \".nix\" name)\n ) content\n )\n );\n\n relativeToRoot = lib.path.append ../.;\n}\nThe key here is wrapping the home-manager logic in\nhome-manager.users.${username} = {}, this effectively creates a home-manager\nsandbox enabling configuration of both in the same file.
\n\nNOTE: You can do this without
\nflake-partsalso but often wasn’t recommended\nbecause the files become a mess that’s hard to understand.
In the flake.nix, notice the inputs.treefmt-nix.flakeModule. Since a\nformatter is something that you would want to run on every system, you use the\nperSystem attribute.
Adding the inputs.treefmt-nix.flakeModule makes the treefmt options\navailable
~/flake/parts/treefmt.nix:
{\n perSystem = _: {\n treefmt = {\n projectRootFile = \"flake.nix\";\n\n programs = {\n deadnix.enable = true;\n statix.enable = true;\n keep-sorted.enable = true;\n nixfmt = {\n enable = true;\n # package = pkgs.nixfmt;\n };\n };\n\n settings = {\n global.excludes = [\n \"LICENSE\"\n \"README.md\"\n \".adr-dir\"\n \"nu_scripts\"\n \"*.{gif,png,svg,tape,mts,lock,mod,sum,toml,env,envrc,gitignore,sql,conf,pem,key,pub,py,narHash}\"\n \"Cargo.lock\"\n \"flake.lock\"\n \"justfile\"\n \".jj/*\"\n ];\n\n formatter = {\n nixfmt.priority = 1;\n statix.priority = 2;\n deadnix.priority = 3;\n };\n };\n };\n };\n}\n\n\nBy using
\nperSystem, yourtreefmtconfiguration is automatically available\nfor every architecture you support (x86, ARM, etc.), allowing you to run\nnix fmton any machine without rewriting the logic.
import-tree automatically imports this because it’s a flake-parts module &\nflake output.
Adding this flake input and flakeModule make the options available, they’re\nsimilar to NixOS’s devShell but not the same:
devshell.url = \"github:numtide/devshell\";\n~/flake/parts/dev-shell.nix:
{\n perSystem =\n { pkgs, system, ... }:\n {\n devshells.default = {\n name = \"nixos-dev\";\n\n packages = with pkgs; [\n nixfmt\n deadnix\n nixd\n nil\n nh\n nix-diff\n nix-tree\n helix\n git\n ripgrep\n jq\n tree\n ];\n\n # Message of the Day\n motd = ''\n {2}── NixOS Dev Shell ──────────────────────────────────────────{reset}\n {9} System: {reset} ${system}\n {2}──────────────────────────────────────────────────────────────{reset}\n '';\n\n commands = [\n {\n name = \"rebuild\";\n package = \"nh\";\n help = \"Run nh os switch on the current flake\";\n command = \"nh os switch .\";\n }\n {\n name = \"fmt\";\n package = \"nixfmt\";\n help = \"Format all nix files in the project\";\n command = \"nix fmt\";\n }\n ];\n };\n };\n}\nEnter devShell:
\ncd ~/flake\nnix develop\nI couldn’t get disko to bend to my will so I wrote the following bash script.\nThe script automates the steps in Graham Christensen’s\nErase your darlings
\nThe script below automates the “Erase Your Darlings” setup. It organizes your\ndata into three distinct “levels” of persistence:
\nThe Volatile (/): A ZFS dataset that is blank at boot. We take a\nsnapshot called @blank immediately after creation. In your NixOS\nconfiguration, you will set up a boot-time script to roll back to this @blank\nsnapshot, effectively “formatting” your root in milliseconds.
The Store (/nix): A separate dataset for the Nix store. This doesn’t\nneed to be wiped because Nix already manages its own integrity.
The Safe (/persist and /home): These datasets hold the things you\nactually care about—your SSH keys, browser profiles, and project files.
What this script automates
\nThis bash script handles the “Stage 0” heavy lifting. It will:
\nPartition your disk with an EFI boot partition and a LUKS2 encrypted\ncontainer.
\nInitialize a ZFS pool (rpool) with performance-optimized settings (like\nashift=12 and zstd compression).
Carve out the datasets required for an Impermanence setup.
\nMount the hierarchy into /mnt so nixos-generate-config can detect the\nspecialized ZFS layout.
\n\nWARNING: This is a destructive operation. Running this script will wipe\nthe target drive completely. Ensure you have backed up any existing data\nbefore proceeding.
\n
The script handles the partitioning, formatting, mounting, and lastly, runs\nnixos-generate-config --root /mnt. After running the script, edit the files\nin the repo matching your user and device. Finally, after you’re sure you\nhaven’t missed anything, run nixos-install.
export NIX_CONFIG='experimental-features = nix-command flakes'\ngit clone https://github.com/saylesss88/my-flake2.git\n\n\nWARNING: This is a destructive operation. Running this script will wipe\nthe target drive completely. Ensure you have backed up any existing data\nbefore proceeding.
\n
sudo chmod +x ./install.sh\nsudo bash ./install.sh\nnvme0n1 drive with no issues.# Get your UUID#\nsudo blkid /dev/YOUR_DISK > /tmp/blk.txt\n# Generate a hashed password\nmkpasswd -m yescrypt > /tmp/pass.txt\n# Generate a rand # for `networking.hostId`\nhead -c4 /dev/urandom | xxd -p > /tmp/rand.txt\nEdit flake.nix, configuration.nix, and replace the repos\nhardware-configuration.nix with your own.
Add neededForBoot to the home and persist datasets in the generated\nhardware-configuration.nix.
Example:
\n fileSystems.\"/home\" = {\n device = \"rpool/safe/home\";\n fsType = \"zfs\";\n neededForBoot = true;\n };\n\n fileSystems.\"/persist\" = {\n device = \"rpool/safe/persist\";\n fsType = \"zfs\";\n neededForBoot = true;\n };\n/mnt/etc/nixos/sudo mv ~/my-flake2 /mnt/etc/nixos/\nhost to your host name)sudo nixos-install --flake /mnt/etc/nixos/myflake2#host\nReboot. I typically run nixos-install with the minimal requirements,\nreboot, and then configure my window manager/DE.
After reboot, adjust permissions for your $USER:
sudo mkdir -p /persist/home/$USER\n# Set ownership for the persistent home directory\nsudo chown -R 1000:100 /persist/home/$USER\n\n# Ensure the home dataset itself is accessible\nsudo chmod 755 /home\nsudo chmod 755 /persist/home\n# Test file, should be gone after reboot\nsudo touch /etc/rollback-canary\nUncomment the import of the impermanence module in the configuration.nix.
Reboot, then check:
\nsudo ls /etc/rollback-canary\n\"/etc/rollback-canary\": No such file or directory (os error 2)What gets wiped?:
\nSince 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?:
\n/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
There are quite a few resources out there that share best practices, but no\nsingle unified place to find them all. I’m going to try to build on\nnix.dev’s Best practices, by doing some\nresearch as well as examining the code of some of the leaders in the NixOS\nworld. (Tweag, numtide, etc.)
\nI’ve added a flake.nix to the mdbook-nix-repl repo, you can add it as a\nflake input:
flake.nix:# flake.nix\n{\n inputs = {\n nixpkgs.url = \"github:nixos/nixpkgs/nixos-unstable\";\n\n mdbook-nix-repl.url = \"github:saylesss88/mdbook-nix-repl?dir=server\";\n };\n\n outputs = { self, nixpkgs, mdbook-nix-repl, ... }: {\n nixosConfigurations.magic = nixpkgs.lib.nixosSystem {\n system = \"x86_64-linux\";\n modules = [\n ./configuration.nix\n\n mdbook-nix-repl.nixosModules.default\n ];\n };\n };\n}\nconfiguration.nix:{ pkgs, ... }:\n{\n imports = [\n ];\n\n # This option is now provided by the module you imported from the flake\n custom.nix-repl-server = {\n enable = true;\n port = 8080;\n tokenFile = \"/etc/nix-repl-server.env\";\n };\n}\nNIX_REPL_TOKEN in theme/index.hbs, and add create file\n/etc/nix-repl-server.env:# Create the file with strict permissions (root read-only)\nsudo touch /etc/nix-repl-server.env\nsudo chmod 600 /etc/nix-repl-server.env\n\n# Edit it to add: NIX_REPL_TOKEN=your_token_from_index_hbs\nsudo vim /etc/nix-repl-server.env\nExpected format:
\nNIX_REPL_TOKEN=9deb7efadb74b9e962e7911bb5caf3b3fef275a1b915b526\nAll the following examples are interactive, press play to see the result.(The\nfollowing examples come directly from nix.dev)
rec {\n a = 1;\n b = a + 2;\n}\nUse this instead:
\nlet\n a = 1;\nin {\n a = a;\n b = a + 2;\n}\n\n\n💡 TIP Self-reference can be achieved by explicitly naming the attribute set:
\n
let\n argset = {\n a = 1;\n b = argset.a + 2;\n };\nin\n argset\n{ a = 1; b = 2; } // { b = 3; c = 4; }\nUpdates are shallow, names on the right take precidence:
\n{ a = { b = 1; }; } // { a = { c = 3; }; }\nlet pkgs = import <nixpkgs> {}; in\npkgs.lib.recursiveUpdate { a = { b = 1; }; } { a = { c = 3;}; }\nWhen creating the VM in virt-manager:
\nBefore clicking “Finish”, check the “Customize configuration before install”\nbox
\nIn the Overview section, change Firmware from BIOS to UEFI x86_64:\n/usr/share/edk2/ovmf/OVMF_CODE_4M.secboot.qcow2
Proceed with the NixOS installation as normal. For lanzaboote to build\nsuccessfully, I had to pin it to nixpkgs 25.05.
Known Issue: After running nixos-install and rebooting, the SATA CDROM\nsource path may be cleared. If the VM fails to boot, manually reselect the NixOS\nISO in the SATA settings and reboot.
The default configuration uses Microsoft’s pre-enrolled keys, which won’t trust\nyour custom-signed kernel. To enable custom key enrollment, you need to modify\nthe VM’s XML configuration.
\nOn your host, find your VM name:
\nvirsh -c qemu:///system list --all\nExample Output:
\n Id Name State\n---------------------------------\n - nixos-unstable shut off\n - nixos shut off\nEdit the VM configuration:
\nvirsh edit nixos-unstable\nMake the following changes to the <os> section:
enrolled-keys feature from yes to no:<feature enabled='no' name='enrolled-keys'/>\n<loader> and <nvram> lines. These conflict with\nlibvirt’s firmware autoselection when using enrolled-keys='no':<!-- DELETE THESE TWO LINES -->\n<loader readonly='yes' secure='yes' type='pflash' format='qcow2'>/usr/share/edk2/ovmf/OVMF_CODE_4M.secboot.qcow2</loader>\n<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>\nYour final <os> section should look like this:
<os firmware='efi'>\n <type arch='x86_64' machine='pc-q35-10.1'>hvm</type>\n <firmware>\n <feature enabled='no' name='enrolled-keys'/>\n <feature enabled='yes' name='secure-boot'/>\n </firmware>\n <boot dev='hd'/>\n</os>\n<serial> tag as a best practice <disk type='file' device='disk'>\n <driver name='qemu' type='qcow2' discard='unmap'/>\n <source file='/var/lib/libvirt/images/nixos-unstable-1.qcow2'/>\n <serial>disk01</serial>\n <target dev='vda' bus='virtio'/>\n <address type='pci' domain='0x0000' bus='0x04' slot='0x00' function='0x0'/>\n </disk>\nzpool import -d /dev/disk/by-id rpoolSave and exit the editor. Libvirt will now automatically create a new NVRAM file\nin Setup Mode (no keys enrolled).
\nAdd the impermanence flake input. I also had to pin lanzaboote to nixpkgs\n25.05 for lanzaboote to build successfully:
inputs = {\n impermanence.url = \"github:nix-community/impermanence\";\n nixpkgs.url = \"github:nixos/nixpkgs/nixos-unstable\";\n nixpkgs-stable.url = \"github:nixos/nixpkgs/nixos-25.05\";\n};\nAdd lanzaboote, if you don’t use unstable, you can obviously avoid the\noverlay:
{ pkgs, lib, inputs, ... }: {\n# configuration.nix\nnixpkgs.overlays = [\n (final: prev: {\n lanzaboote = (inputs.nixpkgs-stable.legacyPackages.${pkgs.system}.lanzaboote or prev.lanzaboote)\n })\n];\n\nenvironment.systemPackages = [ pkgs.sbctl ];\n\nboot.loader.systemd-boot.enable = lib.mkForce false;\n\nboot.lanzaboote = {\n enable = true;\n pkiBundle = \"/var/lib/sbctl\";\n};\n}\nAnd impermanence.nix:
{ inputs, lib, ... }: {\n imports = [\n inputs.impermanence.nixosModules.impermanence\n ];\n boot.initrd.postMountCommands = lib.mkAfter ''\n zfs rollback -r rpool/local/root@blank\n '';\n environment.persistence.\"/persist\" = {\n directories = [ \"/var/lib/sbctl\" \"/var/lib/nixos\" ];\n };\n fileSystems.\"/persist\" = {\n device = \"rpool/safe/persist\";\n fsType = \"zfs\";\n neededForBoot = true;\n };\n}\nAfter the XML changes, boot the VM and enter the firmware setup (press ESC\nduring boot).
\nNavigate to Device Manager → Secure Boot Configuration
\nSwitch to “Custom mode”, uncheck Attempt Secure Boot [ ], select “Reset\nSecure Boot Keys”, save with F10, and reboot.
\nEnroll the keys: sudo sbctl enroll-keys -m
Reboot: After enrolling the keys and rebooting, the system will automatically\nbe placed in “Standard mode”, and Attempt Secure Boot [x] selected. You do\nnot need to re-enter firmware setup mode.
\nVerify Secure Boot Status: bootctl status
I tested this on the libvirt stack with KVM, this should work on bare metal with\na few omissions.
\nThis saves a ton of typing…
\nBoot the minimal ISO
\nSet 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
git clone https://github.com/saylesss88/my-flake2.git\nI included a personally tested script that handles all of the steps up until you\nstart configuring the configuration.nix.
cd my-flake2\nsudo chmod +x install.sh\nsudo ./install.sh\nYou will be prompted to enter your disk, just enter the disk, not anything else,\nlike this:
\nvda\n# OR\nnvme0n1\nAfter the first script completes, there is a test.sh script that ensures\neverything is in order.
sudo chmod +x test.sh\nsudo ./test.sh\nZFS is an advanced filesystem, originally developed by Sun Microsystems in 05.
\nOpenZFS is a fork of the proprietary Oracle ZFS, it was forked over a decade\nago. Most of the code remains the same so you can check the\nOracle website for\ndocs and administration guides.
\nZFS is licensed under the\nCommon Development and Distribution License\n(CDDL). Because the CDDL is incompatible with the GPL,\nit is not possible\nfor ZFS to be included in the Linux Kernel. This requirement, however, does not\nprevent a native Linux kernel module from being developed and distributed by a\nthird party, as is the case with OpenZFS (previously\nnamed ZFS on Linux). –arch wiki
\n\n\nNOTE: This isn’t an attack on ZFS Native Encryption, I’m just presenting the\ninformation, the choice is yours. Unless you have a high threat model, ZFS\nnative encryption has many benefits such improved flexibility and\nauthentication.
\n
LUKS (Device Layer): LUKS operates on the block device (like\n/dev/nvme0n1). It knows nothing about files, folders, or datasets. It just\nsees a stream of bytes and scrambles them.
ZFS Native (Filesystem Layer): ZFS encryption operates at the Dataset\n(Filesystem) level. It is aware of the structure of your data.
\nNo matter how careful you are with ZFS Native encryption, these cannot be\nhidden:
\nThe 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)
\nThe Activity: The fact that something changed at a specific time (via\nsnapshot creation or used property changing)
\n\nBy using generic dataset names (e.g.,
\ndata/vol1instead of\ndata/mistress_photos) and automated snapshot schedules, you can strip the\nsemantic value from the exposed metadata. An attacker will see that you have\ndata and how much you have, but they won’t know what it is or which dataset is\nthe valuable one.
Sanitizing your ZFS usage (Mitigating risk):
\nBy following a few simple best practices you can mitigate most, if not all of\nthe risk depending on the situation.
\nUse generic IDs for dataset names, instead of tank/mistress_photos use\ntank/vol-A
Automate your snapshots to prevent traffic analysis
\nUse padding to mitigate size analysis, add dummy files to obfuscate the size\n(Can be tedious in ZFS). This is the hardest to mitigate, if this is a real\nthreat, use LUKS instead.
\nOpenZFS native encryption allows you to transparently encrypt data at rest\nwithin ZFS itself. It was initially released in May 2019, giving it much less\ntime to be scrutinized compared to LUKS (initial release in 2004).
\nOpenZFS Encryption operates at the dataset layer, not the disk layer, which\ncreates several critical security gaps that full-disk encryption (FDE) solutions\nlike LUKS completely avoid.
\nUnlike LUKS, which presents a “black box” of random noise to anyone without the\nkey, ZFS Native Encryption must leave certain structural elements visible to the\noperating system. This is a deliberate design choice that allows ZFS to perform\nmaintenance tasks (like scrubbing) on locked datasets without requiring the user\nto type in a password. (Depending on your threat model, this can be a deal\nbreaker).
\nExample: Threat Model where ZFS Native Encryption falls short compared to\nLUKS
\nThe Leak: ZFS snapshot names and creation times are visible in plaintext\n(zfs list -t snapshot)
The Threat Model: An adversary monitoring your backups or seizing your drive\ncan build a profile of your behavior without decrypting a single byte.
\nIf you claim to be asleep at 3AM, but zfs list shows snapshots being created\nor data changing size at 3:15 AM, your alibi is broken.
Or, say a whistleblower contacts a journalist. An adversary seizes the\njournalist’s laptop. They can’t read the files, but they see a new dataset\ngrew by exactly 5GB at the exact time the leak occured. Correlation = Guilt.
\nCompress & Encrypt:
\nIt’s actually a common misconception that LUKS prevents compression before\nencryption, both methods are able to do this.
\nZFS 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.
\nIntegrety and Authentication:
\nThis is the strongest architectural argument for ZFS Native.
\ndm-integrity, but it incurs a\nmassive performance penalty and is considered experimental for production\nuse.Use LUKS if:
\nYou can’t afford to leak metadata like dataset names or snapshot timestamps.\nLUKS makes the drive look like random noise.
\nYou require rock-solid stability. The ZFS-on-LUKS stack is very\n“battle-tested”.
\nUse ZFS Native Encryption if:
\nYou have “Untrusted” Offsite Backups: This is a really nice feature! You can\nzfs send -w your data to a friend’s server or a cloud VM. The remote host\ncannot mount or read your data because they never have the key, but they can\nstill scrub the pool and verify the data integrity.
You need granular control: ZFS Native Encryption allows you to for example,\nkeep your OS root unencrypted for fast booting/repair, but your /home\ndirectory encrypted.
You run many VMs/Containers: You can create a new encrypted dataset for a\nspecific project/client without repartitioning or creating loopback files.
\nYou want to verify data authenticity.
\nPractical ZFS is native encryption ready for production use?
\nWhen creating the VM, before clicking “Finish”, check the “Customize\nconfiguration before install” box and choose EFI Firmware > BIOS. You will\nwaste a bunch of time if you forget to do this!
\nOVMF_CODE.fd in my testing.Format your disk
\nsudo cfdisk /dev/vda\nsudo mkfs.fat -F32 /dev/vda1\nsudo cryptsetup luksFormat /dev/vda2\nsudo cryptsetup open /dev/vda2 cryptroot\nsudo zpool create \\\n -o ashift=12 \\\n -o autotrim=on \\\n -O acltype=posixacl \\\n -O canmount=off \\\n -O compression=zstd \\\n -O normalization=none \\\n -O relatime=on \\\n -O xattr=sa \\\n -O dnodesize=auto \\\n -O mountpoint=none \\\n rpool /dev/mapper/cryptroot\n# root (ephemeral)\nsudo zfs create -p -o canmount=noauto -o mountpoint=legacy rpool/local/root\nsudo zfs snapshot rpool/local/root@blank\n\n# nix store\nsudo zfs create -p -o mountpoint=legacy rpool/local/nix\n\n# persistent data\nsudo zfs create -p -o mountpoint=legacy rpool/safe/home\nsudo zfs create -p -o mountpoint=legacy rpool/safe/persist\nmountpoint=legacy means that systemd will take care of the mounting# 1. Mount root first\nsudo mount -t zfs rpool/local/root /mnt\n\n# 2. Create directories\nsudo mkdir -p /mnt/{nix,home,persist,boot}\n\n# 3. Mount ESP directly to /boot (simpler and safer for systemd-boot)\nsudo mount -t vfat -o umask=0077 /dev/vda1 /mnt/boot\n\n# 4. Mount other ZFS datasets\nsudo mount -t zfs rpool/local/nix /mnt/nix\nsudo mount -t zfs rpool/safe/home /mnt/home\nsudo mount -t zfs rpool/safe/persist /mnt/persist\nsudo nixos-generate-config --root /mnt\nexport NIX_CONFIG='experimental-features = nix-command flakes'\nnix-shell -p helix\nsudo blkid /dev/vda2\n# Copy the uuid\n# configuration.nix\n boot.initrd.luks.devices = {\n cryptroot = {\n device = \"/dev/disk/by-uuid/uuid#\";\n allowDiscards = true;\n preLVM = true;\n };\n };\nboot.initrd.luks.devices.\"cryptroot\".device = \"/dev/disk/by-uuid/<UUID-OF-PARTITION-2>\";\nconfiguration.nixhead -c4 /dev/urandom | xxd -p > /tmp/rand.txt\nCreate password file in a persistent location:
\nsudo mkdir -p /mnt/persist/etc/nixos-secrets/passwords\n\n #1) This is for `initialHashedPassword`\n # Read this in with `:r /tmp/pass.txt`\nmkpasswd --method=yescrypt > /tmp/pass.txt\nAfter first reboot, the above files will be placed directly under /persist/
(Edited 2026-01-18 use postMountCommands > postResumeCommands)
{ config, lib, pkgs, ... }:\n\n{\n # ------------------------------------------------------------------\n # 1. Boot loader – systemd-boot (UEFI only)\n # ------------------------------------------------------------------\n boot.loader = {\n systemd-boot = {\n enable = true;\n consoleMode = \"max\";\n editor = false;\n };\n efi = {\n canTouchEfiVariables = true;\n efiSysMountPoint = \"/boot\";\n };\n };\n\n # ------------------------------------------------------------------\n # 2. ZFS support see: https://openzfs.github.io/openzfs-docs/Getting%20Started/NixOS/index.html\n # ------------------------------------------------------------------\n boot.supportedFilesystems = [ \"zfs\" ];\n boot.zfs.devNodes = \"/dev/\"; # Critical for VMs\n # Not needed with LUKS\n boot.zfs.requestEncryptionCredentials = false;\n # systemd handles mounting\n systemd.services.zfs-mount.enable = false;\n\n services.zfs = {\n autoScrub.enable = true;\n # periodically runs `zpool trim`\n trim.enable = true;\n # autoSnapshot = true;\n };\n\n # ------------------------------------------------------------------\n # 3. LUKS\n # ------------------------------------------------------------------\n boot.initrd.luks.devices = {\n cryptroot = {\n # replace uuid# with output of UUID # from `sudo blkid /dev/vda2`\n device = \"/dev/disk/by-uuid/uuid#\";\n allowDiscards = true;\n preLVM = true;\n };\n };\n\n # ------------------------------------------------------------------\n # 4. Roll-back root to blank snapshot on **every** boot\n # ------------------------------------------------------------------\n # Uncomment after first reboot\n # boot.initrd.postMountCommands = lib.mkAfter ''\n # zfs rollback -r rpool/local/root@blank\n # '';\n\n # ------------------------------------------------------------------\n # 5. Basic system (root password, serial console for VM)\n # ------------------------------------------------------------------\n # Unique 8-hex hostId (run once in live ISO: head -c4 /dev/urandom | xxd -p)\n networking.hostId = \"a1b2c3d4\"; # <<<--- replace with your own value\n\n users.users.root.initialPassword = \"changeme\"; # change after first login\n\n boot.kernelParams = [ \"console=tty1\" ];\n\n # ------------------------------------------------------------------\n # Users\n # ------------------------------------------------------------------\n\n users.mutableUsers = false;\n\n # Change `your-user`\n users.users.your-user = {\n isNormalUser = true;\n extraGroups = [ \"wheel\" ];\n group = \"your-user\";\n # :r /tmp/pass.txt:\n initialHashedPassword = \"\";\n };\n\n # This enables `chown -R your-user:your-user`\n users.groups.your-user = { };\n\n # ------------------------------------------------------------------\n # (Optional) Helpful for recovery situations\n # ------------------------------------------------------------------\n # users.users.admin = {\n # isNormalUser = true;\n # description = \"admin account\";\n # extraGroups = [ \"wheel\" ];\n # group = \"admin\";\n # initialHashedPassword = \"Output of `:r /tmp/pass.txt`\";\n # };\n\n # users.groups.admin = { };\n # ------------------------------------------------------------------\n\n # ------------------------------------------------------------------\n # 6. (Optional) Enable SSH for post-install configuration\n # ------------------------------------------------------------------\n # services.openssh = {\n # enable = true;\n # settings.PermitRootLogin = \"yes\";\n #};\n\n # ------------------------------------------------------------------\n # 7. Mark /persist as needed for boot\n # ------------------------------------------------------------------\n fileSystems.\"/persist\".neededForBoot = true;\n}\nAfter reboot, you can uncomment:
\n boot.initrd.postMountCommands = lib.mkAfter ''\n zfs rollback -r rpool/local/root@blank\n '';\nUncomment the above script and test: (Don’t forget that the /etc directory\nwill be wiped, including your configuration.nix and\nhardware-configuration.nix!)
Configuration backup
\nsudo mkdir -p /persist/etc\nsudo cp /etc/nixos/hardware-configuration.nix /etc/nixos/configuration.nix /persist/etc/\nRollback Test
\nsudo touch /etc/rollback-canary\nsudo reboot\nIf the rollback is working, /etc/rollback-canary should be gone after reboot\n(while things in /persist remain).
NixOS ZFS boot support is broken for virtio drives without serial numbers.\nVirtio disks without serials don’t appear in /dev/disk/by-id, but ZFS boot logic\nonly tries to import pools from /dev/disk/by-id. The official OpenZFS NixOS\ndocumentation explicitly states: “If virtio is used as disk bus, power off the\nVM and set serial numbers for disk”
\nIn the <disk ...> block of your root disk add:
Add to .zshrc:
export LIBVIRT_DEFAULT_URI=\"qemu:///system\"\nvirsh list --all\nvirsh edit nixos-unstable\nIn the first <disk ... device='disk'> section (the one with target dev='vda'\nbus='virtio'), add a <serial> line, e.g.:
<disk type='file' device='disk'>\n <driver name='qemu' type='qcow2' discard='unmap'/>\n <source file='/var/lib/libvirt/images/nixos-unstable-1.qcow2' index='2'/>\n <backingStore/>\n <target dev='vda' bus='virtio'/>\n <serial>disk01</serial>\n <alias name='virtio-disk0'/>\n ...\n</disk>\nsops-nix README: Explicitly warns: “If you are using Impermanence, the key\nused for secret decryption … must be in a persisted directory, loaded early\nenough during boot.” It specifically cites activation timing as the reason this\nfails.
\nTypically the solution was to add neededForUsers = true; in your\n“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\nbaking the salted hash into the store. This is all that I’ve found that works so\nfar…
Without adding the <serial>disk01</serial> to the XML when you reboot, your\nsystem will hang before asking for your LUKS password.
Without clicking “Customize configuration before install” box and choosing EFI\nFirmware instead of the default BIOS, you will not be able to boot at all.\nThis seems to be the case for all custom disk layouts with NixOS on the\nlibvirt stack.
\nklarasystems OpenZFS: Security, Encryption, and Delegation Sept 2025
\nklarasystems Improving Replication Security with OpenZFS Delegation
\nYet another blog post inspired by\nerase your darlings
\nI only tested this within a VM although with a few small tweaks it should work\non bare metal. I used the libvirtd stack with KVM for this.
\n\n\n\nNOTE: This example doesn’t use encryption, it would be easy to add ZFS Native\nEncryption by changing the first
\nzpoolcommand. It’s good enough for most\npeople but does leak some metadata. I’ll add a LUKS example eventually which\nis more involved.
git clone https://github.com/saylesss88/my-flake2.git\nBoot the minimal ISO
\nSet 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.
\nLog in on the default TTY (usually Alt+F1).
\nSwitch to a second TTY by pressing Alt+F2.
\nLog in again (user nixos, no password default).
\nClone your repo in TTY2: git clone https://github.com/your/repo.
\nOpen the README with a pager: less repo/README.md.
\nSwitch back to TTY1 (Alt+F1) to execute commands.
\nToggle back and forth (Alt+F2 / Alt+F1) to read and type.
\nThe minimal ISO includes tmux in the package set, but it’s not installed in\nthe environment by default.
Run: nix run nixpkgs#tmux
Once inside tmux, split the screen vertically: Press Ctrl+b then %
\nIn the right pane, open the README: less repo/README.md
In the left pane, type the commands
\nSwitch panes with Ctrl+b then Left/Right Arrow
\nStart with a minimal ISO.
\nDownload Minimal (64-bit Intel-AMD)
\nChoose 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\nVirtio, with 3D accelleration disabled (causes mouse inversion).
\nWhen creating the VM, before clicking “Finish”, check the “Customize\nconfiguration before install” box and choose EFI Firmware > BIOS. You will\nwaste a bunch of time if you forget to do this!
\nOVMF_CODE.fd in my testing.Check out your layout:
\nsudo fdisk -l\nFormat your disk:
\nsudo cfdisk /dev/vda\nCreate a 1G EFI System first, then a Linux Filesystem with the remaining\nspace. I used (100G)
\nFor the following guide, you want /dev/vda1 to be your EFI System\npartition, and /dev/vda2 to be the Linux Filesystem partition.
sudo fdisk -l\nsudo mkfs.vfat -n EFI /dev/vda1\nzpool create \\\n -o ashift=12 \\\n -o autotrim=on \\\n -O acltype=posixacl \\\n -O canmount=off \\\n -O dnodesize=auto \\\n -O normalization=none \\\n -O relatime=on \\\n -O xattr=sa \\\n -O mountpoint=none \\\n rpool /dev/vda2\nzpool create -f \\\n -o ashift=12 \\\n -O encryption=aes-256-gcm \\\n -O keyformat=passphrase \\\n -O keylocation=prompt \\\n -O mountpoint=none \\\n -O acltype=posixacl \\\n -O compression=lz4 \\\n -O xattr=sa \\\n rpool /dev/vda2\nI just got impermanence working without encryption, I haven’t been able to test\nand iron out any quirks of this encryption method..
\n-p):# root (ephemeral – will be rolled back)\nzfs create -p -o canmount=noauto -o mountpoint=legacy rpool/local/root\n\n# blank snapshot (the “erase” target)\nzfs snapshot rpool/local/root@blank\n\nzfs create -p -o mountpoint=legacy rpool/local/boot\n# /nix – read-only store, must survive rollbacks\nzfs create -p -o mountpoint=legacy rpool/local/nix\n\n# persisted areas\nzfs create -p -o mountpoint=legacy rpool/safe/home\nzfs create -p -o mountpoint=legacy rpool/safe/persist\n/mnt:mount -t zfs rpool/local/root /mnt\n\nmkdir -p /mnt/{boot,boot/efi,nix,home,persist}\nmount -t vfat -o umask=0077 /dev/vda1 /mnt/boot/efi\nmount -t zfs rpool/local/nix /mnt/nix\nmount -t zfs rpool/safe/home /mnt/home\nmount -t zfs rpool/safe/persist /mnt/persist\n\n\nNote: By placing your Nix flake in
\n/home/user/nixos-config(which lives on\nrpool/safe/home), it persists naturally. You don’t need to add your\nconfiguration files to theenvironment.persistencemodule lists because the\nunderlying storage isn’t being wiped.
nixos-generate-config --root /mnt\n# edit /mnt/etc/nixos/configuration.nix (add ZFS + rollback + impermanence)\nQuick checklist to confirm that you’ve taken all of the necessary steps.
\n# 1. pool\nzpool create -o ashift=12 -o autotrim=on -O acltype=posixacl -O canmount=off \\\n -O dnodesize=auto -O normalization=formD -O relatime=on -O xattr=sa \\\n -O mountpoint=none rpool /dev/vda2\n\n# 2. datasets + snapshot\nzfs create -p -o canmount=noauto -o mountpoint=legacy rpool/local/root\nzfs snapshot rpool/local/root@blank\nzfs create -p -o mountpoint=legacy rpool/local/nix\nzfs create -p -o mountpoint=legacy rpool/safe/home\nzfs create -p -o mountpoint=legacy rpool/safe/persist\n# add a /boot dataset\nzfs create -p -o mountpoint=legacy rpool/local/boot\n\n# 3. mounts\nmount -t zfs rpool/local/root /mnt\nmkdir -p /mnt/{boot,boot/efi,nix,home,persist}\n\n# /boot on ZFS\nmount -t zfs rpool/local/boot /mnt/boot\n\n# ESP on /boot/efi\nmount -t vfat -o umask=0077 /dev/vda1 /mnt/boot/efi\n\nmount -t zfs rpool/local/nix /mnt/nix\nmount -t zfs rpool/safe/home /mnt/home\nmount -t zfs rpool/safe/persist /mnt/persist\nconfiguration.nixhead -c4 /dev/urandom | xxd -p > /tmp/rand.txt\nCreate password file in a persistent location:
\nsudo mkdir -p /mnt/persist/etc/nixos-secrets/passwords\n\n# 2) Create the password hash and write it to the persistent file\n# Replace \"your-password\" and \"your-user\"\nsudo sh -c 'mkpasswd -m yescrypt \"your-password\" > /mnt/persist/etc/nixos-secrets/passwords/your-user'\n\n# 3) Lock down permissions\nsudo chown root:root /mnt/persist/etc/nixos-secrets/passwords/your-user\nsudo chmod 600 /mnt/persist/etc/nixos-secrets/passwords/your-user\n/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\npostMountCommands instead of postResumeCommands) :
{ config, lib, pkgs, ... }:\n\n{\n # ------------------------------------------------------------------\n # 1. Boot loader – systemd-boot (UEFI only)\n # ------------------------------------------------------------------\n boot.loader = {\n systemd-boot = {\n enable = true;\n consoleMode = \"max\"; # Full 80×25 console in VM\n editor = false; # Security – no edit at boot\n };\n efi = {\n canTouchEfiVariables = true; # libvirt provides /sys/firmware/efi\n efiSysMountPoint = \"/boot/efi\"; # Our 1 GiB FAT32 partition\n };\n };\n\n # ------------------------------------------------------------------\n # 2. ZFS support\n # ------------------------------------------------------------------\n boot.supportedFilesystems = [ \"zfs\" ];\n boot.zfs.devNodes = \"/dev/\"; # Critical for VMs\n\n # Unique 8-hex hostId (run once in live ISO: head -c4 /dev/urandom | xxd -p)\n networking.hostId = \"a1b2c3d4\"; # <<<--- replace with your own value\n\n # ------------------------------------------------------------------\n # 3. Roll-back root to blank snapshot on **every** boot\n # ------------------------------------------------------------------\n# Uncomment after first reboot\n# boot.initrd.postMountCommands = lib.mkAfter ''\n# zfs rollback -r rpool/local/root@blank\n# '';\n\n # ------------------------------------------------------------------\n # 4. Basic system (root password, serial console for VM)\n # ------------------------------------------------------------------\n users.users.root.initialPassword = \"changeme\"; # change after first login\n boot.kernelParams = [ \"console=ttyS0,115200n8\" ];\n\n users.mutableUsers = false;\n\n users.users.your-user = {\n isNormalUser = true;\n extraGroups = [ \"wheel\" ];\n group = \"your-user\";\n # The location of `hashedPasswordFile` after first reboot\n hashedPasswordFile = \"/persist/etc/nixos-secrets/passwords/your-user\";\n };\n\n # This enables `chown -R your-user:your-user`\n users.groups.your-user = { };\n\n # ------------------------------------------------------------------\n # 5. (Optional) Enable SSH for post-install configuration\n # ------------------------------------------------------------------\n # services.openssh = {\n # enable = true;\n # settings.PermitRootLogin = \"yes\";\n #};\n\n # ------------------------------------------------------------------\n # 6. Mark /persist as needed for boot\n # ------------------------------------------------------------------\n fileSystems.\"/persist\".neededForBoot = true;\n}\nsudo nixos-install --root /mnt\nreboot\nCopy your system files to a persistent location before uncommenting the\nimpermanence script.
\nsudo mkdir -p /persist/etc\nsudo cp /etc/nixos/configuration.nix /etc/nixos/hardware-configuration.nix /persist/etc/\nNow, you can uncomment this block:
\n boot.initrd.postMountCommands = lib.mkAfter ''\n zfs rollback -r rpool/local/root@blank\n '';\nsudo touch /etc/rollback-canary\nsudo reboot\nIf the rollback is working, /etc/rollback-canary should be gone after reboot\n(while things in /persist remain).
What gets wiped?:
\nSince 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?:
\n/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?
\nSSH Host keys typically live in /etc/ssh. Since /etc is wiped, they\ndisappear. Store them in /persist/etc/ssh and tell NixOS to look there. (or\nsymlink them)
User Secrets (~/.config/sops): They live in /home so they’re safe.
After first reboot, I recommend setting up a flake in a persistent location such\nas /home/your-user/flake. Because subsequent reboots will wipe the /etc\ndirectory.
sudo mkdir /imperm_test\necho \"This should be Gone after Reboot\" | sudo tee /imperm_test/testfile\nsudo ls -l /imperm_test/testfile # Verify the file exists\nsudo cat /imperm_test/testfile # Verify content\nReboot and check again:
\nsudo ls -l /imperm_test/testfile # Verify the file no longer exists\nsudo cat /imperm_test/testfile # Verify content is missing\nsudo mkdir -p /persist/etc/ssh\nsudo ssh-keygen -t ed25519 -f /persist/etc/ssh/ssh_host_ed25519_key -N \"\"\nOR if you still have keys in /etc/ssh you want to keep just copy them to the\npersistent location:
sudo cp /etc/ssh/ssh_host_ed25519_key* /persist/etc/ssh/\nTell NixOS where to find them
\nservices.openssh = {\n hostKeys = [\n {\n path = \"/persist/etc/ssh/ssh_host_ed25519_key\";\n type = ed25519;\n }\n ];\n}\nAfter I initially get things working, I switch to sops-nix, the following\nguide works for this setup:\nsops-nix Guide
gpg-agent on NixOS\n\n⚠️ SECURITY WARNING: This guide involves sensitive cryptographic material.\nNever share your private key or passphrase. Backup your keys and handle\nthem with extreme care.
\n
![\"GnuPG\"](\"https://saylesss88.github.io/../images/gnupg.png\")
The gpg.fail is a write-up of real-world weaknesses in\nGPG/OpenPGP implementations and edge cases in the OpenPGP ecosystem—not the\nunderlying math of modern cryptography. The core idea is that signature\nverification needs two things: correct cryptography and confidence that the data\nyou think was verified is actually the same data the verifier processed, which\ncan break down when formats are complex and tooling is permissive or ambiguous.
\nMost of the hardening in this guide (offline primary key, subkeys, strict\npermissions, agent separation) is still worth doing because it protects your\nprivate key material and reduces the blast radius if a workstation is\ncompromised.
\nBut that kind of key hygiene doesn’t automatically protect you from OpenPGP\n“sharp edges” like ambiguous parsing rules, weird message constructions, or\nimplementation bugs because those problems happen at the message/format/tooling\nlayer, not the key-storage layer.
\nDon’t treat “Good signature” as the end of the story. Treat verification as\n“verify + inspect what was verified,” especially if the output will be\nconsumed by other tools or humans who may misinterpret it.
\nPrefer OpenPGP for narrow, well-understood tasks (verifying release artifacts,\nencrypting files) and be extra cautious when dealing with untrusted,\nattacker-controlled OpenPGP inputs that flow through multiple tools (mail\nclients, import pipelines, automation).
\nKeep GnuPG and related tooling updated; gpg.fail covers vulnerabilities that\ninclude classic implementation issues and not just “protocol design” pitfalls.
\nIf you’re writing automation around signature verification, ensure your pipeline\nclearly distinguishes:
\n“signature cryptographically valid” from
\n“the extracted/displayed message is exactly what was verified”. Some gpg.fail\nitems specifically call out cases where output does not make this distinction\nobvious enough to prevent misuse.
\nSome “hardening” choices can cause GPG to fail in ways that look mysterious but\nare just UI/agent integration problems (for example, No pinentry / “gpg\nfailed to sign the data” when the agent can’t prompt). If GPG signing/encryption\nsuddenly stops working, first confirm pinentry is configured correctly (via your\nservices.gpg-agent.pinentryPackage or gpg-agent.conf) and restart the agent\nwith gpgconf --kill gpg-agent then gpgconf --launch gpg-agent.
GnuPG is a complete and free implementation of the OpenPGP standard. It\nallows you to encrypt and sign your data and communications, has a versatile key\nmanagement system, and access modules for many kinds of public key directories.\nGnuPG (GPG), is a command line tool for secure communication.
\nPGP (Pretty Good Privacy) and GPG (GNU Privacy Guard). While distinct,\nthey are deeply interconnected and, for the rest of this section, I’ll use the\nterms interchangeably.
\nPGP was the original, groundbreaking software that brought robust public-key\ncryptography to the masses. It set the standard for secure email communication.\nHowever, PGP later became a commercial product.
\nTo provide a free and open-source alternative that anyone could use and inspect,\nGPG was created. Crucially, GPG is a complete implementation of the\nOpenPGP standard. This open standard acts as a universal language for encryption\nand digital signatures.
\nGnuPG uses a more complex scheme in which a user has a primary keypair and then\nzero or more additional subordinate keypairs.
\nSigning public keys with the corresponding private key is called self-signing,\nand a public key that has self-signed user IDs bound to it is called a\ncertificate.
\nWeb of Trust: Rather than validate every single key individually, you can\nrely on other factors such as if it has been signed by a key that you fully\ntrust or if it has been signed by three marginally trusted keys to validate\nkeys.
\ngpg-agent is a daemon to manage secret (private) keys independently from any\nprotocol. It is used as a backed for gpg and gpgsm as well as for a couple\nof other utilities. –man gpg-agent
There are numerous front-ends for gpg as well, i.e., GUI apps that simplify many\nof the commands and processes. Two that I touch on in this overview are\nseahorse and kleopatra.
E2ee requires that every sender and recipient does a one time preparation, which\ninvolves the generation of personal random numbers. Two such random numbers are\nnecessary, one will be called your secret key and another one will be called\nyour public key (together your personal key). These numbers are very big, they\nconsist of hundreds or thousands of digits.
\nA message can be encrypted using the recipients public key and can only be\ndecrypted with the matching private key. In other words, if you exchange\npublic keys with someone you both can encrypt messages that only the other\ncan decrypt with their own private key. You must never share the private\nkey or the private keys passphrase with anyone else.
\nWhat’s safe to share?
\nYour public key (used to encrypt files and verify signatures)
\nYour key ID (identifies your key, useful for sharing public keys or configs)
\nYour keys fingerprint gpg --fingerprint
What must never be shared?
\nYour private (secret) key, usually in your ~/.gnupg/private-keys-v1.d/\ndirectory. Usually called your private keyring. Your main goal should be\nthe protection of your private key.
Your passphrase for your private key. Even if someone is able to somehow\nget your private key, they need to break the passphrase to access it\nunencrypted. Protect this passphrase!
\nBest Practices
\nDon’t rely on the short KeyID, at least use long OpenPGP Key IDs (for example\n0xA1E6148633874A3D), they are 64 bits long and harder to spoof. Even better, use\nthe fingerprint.This is accomplished in the configuration with\nkeyid-format = \"0xlong\";, and with-fingerprint.
Always sign your public keys before you publish them to prevent man in the\nmiddle attacks and other modifications. When a subkey or userID is generated it\nis self-signed automatically, which is why you need to enter your password.
\nDon’t blindly trust keys from keyservers. You should verify the full key\nfingerprint with the owner over the phone if possible.
\n\nUse a strong primary key, don’t use 1024-bit DSA, 1024-bit RSA, or SHA-1 for\nsigning they are no longer recommended.
\nChoose an expiration date less than 2 years, you can add time if needed.\nRemember this date.
\nRotate your subkeys.
\nKeep your primary key offline, this ensures that it can’t be stolen by an\nattacker allowing him to create new identities. We accomplish this by creating\nsubkeys and only adding the subkeys keygrip and the subkeys default-key to our\nconfiguration keeping the primary key out of it.
Since we will be removing our primary key, even we won’t be able to create\nadditional keys so it’s important to think ahead and make all the keys you’ll\nneed. However, it is as easy as reimporting it to give yourself access again.
\nMany of these best practices come from the following guide:
\n\nHome Manager module with gpg-agent, gnupg, and pinentry-gnome3:
# gpg-agent.nix\n{\n config,\n lib,\n pkgs,\n ...\n}: {\n options = {\n custom.pgp = {\n enable = lib.mkEnableOption {\n description = \"Enable PGP Gnupgp\";\n default = false;\n };\n };\n };\n\n config = lib.mkIf config.custom.pgp.enable {\n services = {\n ## Enable gpg-agent with ssh support\n gpg-agent = {\n enable = true;\n enableSshSupport = true;\n enableZshIntegration = true;\n # pinentry is a collection of simple PIN or passphrase dialogs used for\n # password entry\n pinentryPackage = pkgs.pinentry-qt;\n };\n\n ## We will put our keygrip here\n gpg-agent.sshKeys = [];\n };\n home.packages = [pkgs.gnupg];\n programs = {\n gpg = {\n ## Enable GnuPG\n enable = true;\n\n # homedir = \"/home/userName/.config/gnupg\";\n settings = {\n # Default/trusted key ID (helpful with throw-keyids)\n # Example, you will put your own keyid here\n # Use `gpg --list-keys`\n # default-key = \"0x37ACBCDA569C5C44788\";\n # trusted-key = \"0x37ACBCDA569C5C44788\";\n # https://github.com/drduh/config/blob/master/gpg.conf\n # https://www.gnupg.org/documentation/manuals/gnupg/GPG-Configuration-Options.html\n # https://www.gnupg.org/documentation/manuals/gnupg/GPG-Esoteric-Options.html\n # Some Best Practices, stronger algos etc\n # Use AES256, 192, or 128 as cipher\n personal-cipher-preferences = \"AES256 AES192 AES\";\n # Use SHA512, 384, or 256 as digest\n personal-digest-preferences = \"SHA512 SHA384 SHA256\";\n # Use ZLIB, BZIP2, ZIP, or no compression\n personal-compress-preferences = \"ZLIB BZIP2 ZIP Uncompressed\";\n # Default preferences for new keys\n default-preference-list = \"SHA512 SHA384 SHA256 AES256 AES192 AES ZLIB BZIP2 ZIP Uncompressed\";\n # SHA512 as digest to sign keys\n cert-digest-algo = \"SHA512\";\n # SHA512 as digest for symmetric ops\n s2k-digest-algo = \"SHA512\";\n # AES256 as cipher for symmetric ops\n s2k-cipher-algo = \"AES256\";\n # UTF-8 support for compatibility\n charset = \"utf-8\";\n # Show Unix timestamps\n fixed-list-mode = \"\";\n # No comments in signature\n no-comments = \"\";\n # No version in signature\n no-emit-version = \"\";\n # Disable banner\n no-greeting = \"\";\n # Long hexidecimal key format\n keyid-format = \"0xlong\";\n # Display UID validity\n list-options = \"show-uid-validity\";\n verify-options = \"show-uid-validity\";\n # Display all keys and their fingerprints\n with-fingerprint = \"\";\n # Cross-certify subkeys are present and valid\n require-cross-certification = \"\";\n # Disable caching of passphrase for symmetrical ops\n no-symkey-cache = \"\";\n # Enable smartcard\n # use-agent = \"\";\n };\n };\n };\n };\n}\n\n\n🤔 Fun Fact: Elliot Alderson mentions encrypting Evil Corps files with 256 bit\nAES encryption ensuring that it’s impossible to break in
\neps1.9_zer0.daY.avi\nof Mr. Robot.
The default path is ~/.gnupg, if you prefer placing it in the ~/.config\ndirectory or elsewhere, uncomment the homedir line and change userName to\nyour username.
I use sway so pinentry-qt works for me, there is also the following options\nfor this attribute:
pinentry-tty
pinentry-gnome3
pinentry-gtk2
And more, research what you need and use the correct one.
\n\nEnable in your home.nix or equivalent:
# home.nix\n# ... snip ...\nimports = [\n ./gpg-agent.nix\n];\ncustom.pgp.enable = true;\n# ... snip ...\ngpg --full-generate-key can be used to generate a basic keypair.
gpg --expert --full-generate-key can be used for keys that require more\ncapabilities.
\n\n❗ NOTE: We will first generate our GPG primary key that is required to\natleast have sign capabilities, we will then derive subkeys from said primary\nkey and use them for signing and encrypting. It is recommended to generate a\nrevoke certificate right after creating your primary key.
\n
To generate your gpg primary key you can do the following:
\ngpg --full-generate-key\nChoose (10) (sign only)
Give it a name and description
\nGive it an expiration date, 1y is common
\nUse a strong passphrase or password
\nGive it a comment, I typically add the date
\nIf you see a warning about incorrect permissions, you can run the following:
\nchmod 700 ~/.gnupg\nchmod 600 ~/.gnupg/*\nVerify:
\nls -ld ~/.gnupg\n# Should show: drwx------\n\nls -l ~/.gnupg\n# Files should show: -rw-------\nmykey must be a key specifier, either the keyID of the primary keypair or any\npart of the user ID that identifies the keypair:
Replace mykeyID with the keyID of your primary key and store the cert in a\nsafe place:
gpg --output revoke.asc --gen-revoke mykeyID\nCreate a revocation certificate for this key? (y/N)\nPlease select the reason for the revocation:\n 0 = No reason specified\n 1 = Key has been compromised\n 2 = Key is superseded\n 3 = Key is no longer used\n Q = Cancel\n(Probably you want to select 1 here)\nYour decision?\nThe certificate will be output to a file revoke.asc. If the --output is\nommitted, the result will be placed on stdout.
Since it’s a short certificate, you can print a hardcopy and store it somewhere\nsafe. The cert shouldn’t be somewhere that others can access it since anyone\ncould publish the revoke cert and render the corresponding public key useless.
\nTo apply the revoke cert, import it:
\n\n\nNOTE: Only import the
\nrevoce.ascif you want to revoke (i.e., make it not\nwork anymore)
gpg --import revoke.asc\n# And optionally push the revoked key to public keyservers to notify others:\ngpg --keyserver keyserver.ubuntu.com --send-keys YOUR_KEYID\nAfter fixing, run gpg --list-keys --with-fingerprint, which lists your public\nkeys:
# Take note of your public key\ngpg --list-keys --with-fingerprint\n/home/jr/.gnupg/pubring.kbx\n---------------------------\npub ed25519/0x095782A1B124AF15 2025-08-23 [SCA] [expires: 2026-08-23]\nKey fingerprint = 5908 9C5B FEC8 0D75 FCB0 E206 0958 82C1 A124 CF15\nuid [ultimate] Jr (08-23-25) <sayls8@proton.me>\n0x095722B2A123CF15. We will use\nit for the command below.The warning should be gone.
\nNow we will generate 2 subkeys, 1 for encryption and 1 for authentication.
\ngpg --expert --edit-key 0x095722B2A123CF15\nWhen the screen opens, type addkey
Choose 11 (set your own capabilities) and add A (Authenticate) and type save\nto save and exit. Repeat this again and choose 12 ECC (encrypt only).
\n\n❗
\ngpg --edit-keyhas many more capabilities, after launching typehelp.
Add Keygrip of Authenticate Subkey to sshcontrol for gpg-agent
gpg --list-secret-keys --with-keygrip --keyid-format LONG\nCopy the keygrip of the subkey with Authenticate capabilities
\nAdd the keygrip number to your gpg-agent.sshKeys and rebuild, this adds an SSH\nkey to gpg-agent. This is for the SSH key functionality of gpg-agent, while\nthe key ID (default-key) is for GPG-specific operations like signing commits:
# gpg-agent.nix\ngpg-agent.sshKeys = [\"6BD11826F3845BC222127FE3D22C92C91BB3FB32\"];\nThe following article mentions the keygrip being computed from public elements\nof the key:
\n\nAdd the KeyId to your gpg-agent.nix, this declares your default-key to persist\nthrough rebuilds:
Copy the public key of the same subkey with Authenticate capabilities you will\nsee something like [SA] next to it for Sign and Authenticate:
# gpg-agent.nix\ngpg.settings = {\n # Replace with your own Subkeys KeyID `gpg --list-keys --keyid-format LONG`\n default-key = \"Ox37ACA569C5C44787\";\n trusted-key = \"Ox37ACA569C5C44787\";\n};\nThis key should be signed automatically, ensure that it is:
\ngpg --sign-key Ox37ACA569C5C44787\nRebuild, and check that everything is correct with:
\nssh-add -L\n# you should see something like:\nssh-ed25519 AABCC3NzaC1lZDI1NTE5ABBAIHyujgyCjjBTqIuFM3EMUSo6RGklmOXQW3uWRhWdJ1Mm (none)\n.gnupg contents.Add the following to your shell config:
\n# zsh.nix\n# ... snip ...\ninitContent = ''\n export GPG_TTY=$(tty)\n export SSH_AUTH_SOCK=$(gpgconf --list-dirs agent-ssh-socket)\n gpgconf --launch gpg-agent\n'';\n# ... snip ...\nRebuild and then restart gpg-agent if necessary:
gpgconf --kill gpg-agent\ngpgconf --launch gpg-agent\nTest, these should match:
\necho \"$SSH_AUTH_SOCK\"\n# output\n/run/user/1000/gnupg/d.wft5hcsny4qqq3g31c76534j/S.gpg-agent.ssh\n\ngpgconf --list-dirs agent-ssh-socket\n# output\n/run/user/1000/gnupg/d.wft5hcsny4qqq3g31c76834j/S.gpg-agent.ssh\nssh-add -L\n# Copy the entire following line:\nssh-ed25519 AABBC3NzaC1lZDI1NTE5AAAAIGXwhVokJ6cKgodYT+0+0ZrU0sBqMPPRDPJqFxqRtM+I (none)\n(none) because I left the comment field blank when creating the\nkey and doesn’t affect functionality.Then, in your server’s NixOS configuration (e.g., configuration.nix): Change\nyourUser to your username. This is how you grant access to a remote machine,\nand the public key from the GPG subkey is what’s added here, the output of\nssh-add -L:
users.users.yourUser = {\nopenssh = {\n authorizedKeys.keys = [\n # Replace with the output of `ssh-add -L`\n \"ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIGXwhVokJ6cKgodYT+0+0ZrU0sBqMPPRDPJqFxqRtM+I (none)\"\n ];\n};\n};\n\n\n❗ NOTE: Only the public key goes here, it’s safe to commit to version\ncontrol. If you prefer not to hardcode it in the config, you can reference it\nfrom a
\n.pubfile in your repo and read it with\nbuiltins.readFile ./mykey.pub
Rebuild your system and test an SSH connection into the server:
\nssh -p <your-port> user@hostname\n<your-port> is often 22 so it would be something like:ssh -p 22 bill@xps\nOnce you successfully sign in to SSH, it will ask you if you’re sure you trust\nthe remote server’s SSH host key. Once you type yes, it will automatically be\nused for tasks such as file decryption.
\n\n❗ NOTE: After you remove your primary key, you will no longer be able to\nderive subkeys from it or sign keys unless you re-import it.
\n
# extract the primary key\ngpg -a --export-secret-key sayls8@proton.me > secret_key\n# extract the subkeys, which we will reimport later\ngpg -a --export-secret-subkeys sayls8@proton.me > secret_subkeys.gpg\n# delete the secret keys from the keyring, so only subkeys are left\ngpg --delete-secret-keys sayls8@proton.me\nDelete this key from the keyring? (y/N) y\nThis is a secret key! - really delete? (y/N) y\n# reimport the subkeys\ngpg --import secret_subkeys.gpg\n# verify everything is in order\ngpg --list-secret-keys\n# remove the subkeys from disk\nrm secret_subkeys.gpg\nI recommend also keeping a .gpg version to make it easy to re-import your\nprimary 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\nwant to protect it for now, you can just use the encryption subkey that we\ncreated to encrypt secret_key with a passphrase:
gpg --list-keys --keyid-format LONG\nCopy the KeyID of the subkey with encrypt capabilities for the following\ncommand:
\n# Encrypting your secret key for yourself\ngpg --encrypt --recipient Ox37ACA569C5C44787 secret_key\nYou can check that the secret key material is missing with\ngpg --list-secret-keys, you should see sec# instead of sec.
gpg --list-secret-keys\n# Output:\nsec# ed25519/0x\n# ...snip...\nThe above set of commands are from the\nRiseUp Keep your primary key offline
\nPlug your own public key from gpg --list-keys in the following command:
gpg --armor --export <Public-Key>\nCopy the entire block from -----BEGIN PGP PUBLIC KEY BLOCK----- to\n-----END PGP PUBLIC KEY BLOCK-----
\n\n❗ You can also paste the above block into a public keyserver such as\n
\nkeys.openpgp.org. This allows others to find and use your key to encrypt\nmessages or verify your signatures. Many tools and users rely on public key\nservers to fetch keys automatically. You can also publish your revocation\ncertificates, which help others know if your key is compromised or revoked.\nThis can be a privacy concern as key servers publish (and keep) associated\nuser 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,\nNew GPG key and your all set.
# git.nix\n{...}: {\n programs.git = {\n enable = true;\n extraConfig = {\n commit.gpgsign = true;\n user.signingkey = \"0x0666C1A265F156\"\n };\n };\n}\nAfter this, you will be prompted for your Private Keys password on every commit.
\nIf you look at your commits on GitHub, after adding the GPG key and the above\nsettings to your git setup it will show your commits are Verified.
gpg --export-secret-keys --armor --output my-private-key-backup.gpg\nYour private keys will be encrypted with a passphrase into a .gpg file. Store\nthis backup in a secure location line an encrypted USB drive. This can prevent\nyou from losing access to your keys in the case of disk failure or accidents.
\nYou can export your public keys and publish them publicly if you choose:
\ngpg --export --armor --output my-public-keys.gpg\nNow if your keys ever get lost or corrupted, you can import these backups.
\nThe easy way to do this is with an app like Kleopatra, available as\npkgs.kdePackages.kleopatra. Kleopatra will automatically recognize your gpg\nkeys and enable you to easily encrypt messages by clicking the Notepad, typing\nyour message and clicking Sign/Encrypt Notepad. You can also choose to encrypt\nthe message with a password, where anyone that has the password can read the\nmessage.
Using the above and below methods enable you to encrypt any message for\nbasically any service and just copy past the encrypted text into the service for\nadded privacy.
\nEncrypting a whole directory is a bit more involved and requires using\ncompression.
\ngpg --list-keys --keyid-format LONG\nExample output, don’t use RSA keys:
\npub rsa4096/ABCDEF1234567890 2024-01-01 [SC]\nuid [ultimate] Your Name <you@example.com>\nsub rsa4096/1234567890ABCDEF 2024-01-01 [E]\nNotice 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\nin the example)
You can also use your email or name to refer to the key in most commands.
\nIn order to encrypt a document you must have the public keys of the intended\nrecipients.
\necho \"This file will be encrypted\" > file.txt\nEncrypting for yourself (using a key ID as recipient):
\ngpg --encrypt --recipient ABCDEF1234567890 file.txt\nls\n│ 7 │ file.txt │ file │ 28 B │ now │\n│ 8 │ file.txt.gpg │ file │ 191 B │ now │\nEncrypting for someone else with their email (public key identifier):
\ngpg --output file.gpg --encrypt --recipient jake@proton.me file.txt\nls\nfile.txt\nfile.gpg\ngpg --encrypt doesn’t modify the original file. It creates a new encrypted\nfile by default with gpg amended to the filename.
gpg --decrypt file.txt.gpg\ngpg: encrypted with cv25519 key, ID 0x4AC131B80CEC833E, created 2025-07-31\n \"GPG Key <sayls8@proton.me>\"\nThis file will be encrypted\nOr, to save the decrypted text to a file:
\ngpg --output decrypted_file.txt --decrypt file.txt.gpg\ncat decrypted_file.txt\n# Output\nFile: decrypted.txt\nThis file will be encrypted\nWhen you sign a document it is certified and timestamped. If after the doc is\nsigned, if the doc is further modified in any way the verification of the\nsignature will fail.
\nA signature is created using the private key of the signer, and verified with\nthe corresponding public key. For example, to verify Jakes signature you would\nuse Jake’s public key to see that the work indeed came from him and hasn’t been\nmodified since.
\nTo sign the above file.txt:
gpg output doc.sig --sign file.txt\n# To clearsign use:\ngpg --clearsign file.txt\n# For a detached signature use:\ngpg --output doc.sig --detach-sig file.txt\nYou will be prompted for your passphrase.
\nYou can either check the signature or check the signature and recover the\noriginal document.
\n# To only check:\ngpg --output doc --verify doc.sig\n# To verify and extract the document\ngpg --output doc --decrypt doc.sig\nEmail is inherently insecure, and email-based attacks remain one of the top\nvectors for data breaches. Encrypting your email protects your privacy by\nensuring that only the intended recipient can read it. Encrypting your emails\nwith PGP provides valuable security benefits but also has inherent limitations\nthat prevent it from being considered truly “secure communication” by modern\nstandards.
\n\nWhat its Good for:
\nConfidentiality, it prevents unauthorized third parties (like email providers\nor network eavesdroppers) from reading your email content.
\nIntegrity and authenticity: Digital signatures verify that the email genuinely\ncame from the claimed sender and hasn’t been altered in transit.
\nLong-term confidentiality: Encrypted emails stored on servers or devices\nremain protected even if the storage is later compromised. With companies like\nGmail giving you a “free” account, that usually means that you are the product\nand you should tread lightly.
\nTo securely communicate with someone never use email, use a dedicated service\nsuch as Threema, Signal or Brair. It’s hard to recommend any messaging service\nat the moment, always do your own research and stay informed on the companies\npolicies. Signal has taken some heat for the way it has implemented it’s\nMobileCoin. The biggest issue I’ve faced is getting other people to care or use\nthe same e2ee app.
\nWith Thunderbird you can go to settings, Privacy and Security, and scroll to the\nbottom where it says “End to End Encryption”, Click the Settings tab there,\nfinally click End-To-End Encryption on the left.
\nFrom there, you can click + Add Key next to your email address and either\ngenerate a new key through Thunderbird. If you use this, choose the Curve\nprotocol or whatever isn’t RSA.
Or import your own key which is definitely more secure since you’re not trusting\nsomeone else with your private key:
\ngpg --export --armor sayls8@gmail.com > publickey.asc\nThen select + Add Key and choose import your own, this didn’t work for me.\nWhat did work was to start composing an email and click on the OpenPGP button,\nGo to Key Manager, File, Import Public Key from a File and choose your\npublickey.asc. This way, only you have access to your private key.
Import your recipient’s public key
\nWhen you start composing an email, you’ll see that you need to resolve key\nissues if you don’t already have the recipients public key. Click Resolve, and\neither Discover Public Keys Online… or Import Public Keys From File…
Thunderbird has the option to use the OpenPGP Key Manager to view or manage\npublic keys of your correspondents.
\nIf you’re sending encrypted emails to someone you’ll need their public key,\nthere are a few methods of doing this just ensure you verify the Fingerprint\nwith the person your talking to.
\nExporting your public key means creating a copy of the public part of your\ncryptographic key pair that you can share with others.
\nFor example, say that Jake wants to send you his public key. First he has to\nexport his key:
\ngpg --output jake.gpg --export jake@proton.me\nThe key is exported in binary format, to export in ASCII-armored format use:
\ngpg --armor --export jake@proton.me\nNow, once he sends this to you, you’ll need to import and validate it:
\ngpg --import jake.gpg\nOnce the key is imported it should be validated. If you need to validate a key\nmanually, it is done by verifying the key’s fingerprint and then signing the key\nto certify it as a valid key.
\nCheck that it exists in your keychain:
\ngpg --list-keys\nYou should see Jakes key in the above list.
\nTo certify the key you need to edit it:
\ngpg --edit-key jake@proton.me\n# List the fingerprint\ngpg> fpr\n# once the fingerprint is verified with the owner, sign it\ngpg> sign\n# once signed, you can check the key to list signatures on it\ngpg> check\n\n\n❗ NOTE: You can use PGP to encrypt any message and paste it into any\nsoftware and send it. As long as only you and your recipient are the only\npeople to have the private keys, you will be the only people able to decrypt\nthe messages. Implementing this correctly is a good way to stop government\nmass surveillance.
\n
You should always make sure that you sign your public key before you publish it.\nWhen you distribute your public key, you’re distributing the public components\nof your master and subkeys as well as the user IDs. If unsigned, this is a\nsecurity risk because it’s possible for an attacker to tamper with it. The\npublic key can be modified by adding or substituting keys, or changing user IDs.
\nSigning the keys provides a web of trust, only the corresponding public key can\nbe used to verify the signature and ensure it hasn’t been modified. Since we are\nalready only using subkeys for public keys, they are automatically self-signed.
\ngpg --output ~/mygpg.key --armor --export your_email@address.com\nYou can then send this file to the other party.
\nYou can also use the GPG interface to upload your key to a key server:
\ngpg --list-keys your_email@address.com\nCopy the key ID for the following command, remember its on the pub line after\nthe /.
gpg --send-keys --keyserver pgp.mit.edu key_id\nThe key will be uploaded to the server and likely be distributed to other key\nservers around the world. This is why expiration dates are important, if your\nkey is lost or stolen, the damage window is limited to the expiration period.\nAlso remember, you can add more time even after the key has expired.
\n✔️ Click to Expand Example of verifying and signing the archlinux public key
\nFirst, download both the arch .iso and .sig files.
I tried a few different methods from https://archlinux.org/download/#checksums\nand the easiest by far was using Sequoia available in Nixpkgs as\npkgs.sequoia-sq:
Download the archlinux public key:
\nsq network wkd search pierre@archlinux.org --output release-key.pgp\n\nFound 2 certificates related to the query:\n\n - 3E80CA1A8B89F69CBA57D98A76A5EF9054449A5C\n - Pierre Schmitz <pierre@archlinux.org> (UNAUTHENTICATED)\n - created 2022-10-31 09:11:51 UTC\n - found via: WKD\n\n - 4AA4767BBC9C4B1D18AE28B77F2D434B9741E8AC\n - Pierre Schmitz <pierre@archlinux.de> (UNAUTHENTICATED)\n - created 2011-04-10 09:35:33 UTC\n - found via: WKD\n\nHint: To extract a particular certificate from release-key.pgp, use any of:\n\n $ sq cert export --keyring=release-key.pgp --cert=3E80CA1A8B89F69CBA57D98A76A5EF9054449A5C\n\n $ sq cert export --keyring=release-key.pgp --cert=4AA4767BBC9C4B1D18AE28B77F2D434B9741E8AC\nExport the chosen key to a .pgp file:
sq cert export --keyring=release-key.pgp --cert=3E80CA1A8B89F69CBA57D98A76A5EF9054449A5C > pierre-archlinux.pgp\nImport into your keychain:
\n gpg --import pierre-archlinux.pgp\ngpg: key 0x76A5EF9054449A5C: 9 signatures not checked due to missing keys\ngpg: key 0x76A5EF9054449A5C: public key \"Pierre Schmitz <pierre@archlinux.org>\" imported\ngpg: Total number processed: 1\ngpg: imported: 1\ngpg: marginals needed: 3 completes needed: 1 trust model: pgp\ngpg: depth: 0 valid: 3 signed: 0 trust: 0-, 0q, 0n, 0m, 0f, 3u\ngpg: next trustdb check due at 2026-08-23\nNow, you should see <pierre@archlinux.org> and his keys when you run\ngpg --list-keys
Finally, verify the signature:
\nsq verify --signer-file release-key.pgp --signature-file archlinux-2025.08.01-x86_64.iso.sig archlinux-2025.08.01-x86_64.iso\nAuthenticated signature made by 3E80CA1A8B89F69CBA57D98A76A5EF9054449A5C (Pierre Schmitz <pierre@archlinux.org>)\n\n1 authenticated signature.\nThis shows that the signature was made by the key with the ID\n3E80CA1A8B89F69CBA57D98A76A5EF9054449A5C (Pierre Schmitz).
GPG authenticated that the signature is valid and that the key used to sign is\ntrusted in our keyring.
\n1 authenticated signature confirms the files integrity and authenticity.
\nWe have successfully verified that the file was signed by Pierr’s official Arch\nLinux key and has not been tampered with.
\nSince the key has been verified we can now sign it. We will have to import our\nprimary key to do so since we are keeping it offline for safety.
\ngpg --import backup.gpg\nList your keys to get the arch keyID:
\ngpg --list-keys\n# ... snip ...\npub ed25519/0x76A5EF9054449A5C 2022-10-31 [SC] [expires: 2037-10-27]\n Key fingerprint = 3E80 CA1A 8B89 F69C BA57 D98A 76A5 EF90 5444 9A5C\nuid [ full ] Pierre Schmitz <pierre@archlinux.org>\nuid [ full ] Pierre Schmitz <pierre@archlinux.de>\nsub ed25519/0xD6D13C45BFCFBAFD 2022-10-31 [A] [expires: 2037-10-27]\nsub cv25519/0x7F56ADE50CA3D899 2022-10-31 [E] [expires: 2037-10-27]\nSign the key:
\ngpg --sign-key 0x76A5EF9054449A5C\nNow you can Export and publish the new public key and send it to a keyserver:
\ngpg --export --armor 0x76A5EF9054449A5C > archlinux-signed.asc\ngpg --send-keys 0x76A5EF9054449A5C\nThe more people that verify, sign, and re-export and publish their keys the\nbetter for the web of trust that gpg uses making the network more secure for\neveryone.
\ngpg --edit-key pierre@archlinux.org\ngpg> trust\nPlease decide how far you trust this user to correctly verify other users' keys\n(by looking at passports, checking fingerprints from different sources, etc.)\n\n 1 = I don't know or won't say\n 2 = I do NOT trust\n 3 = I trust marginally\n 4 = I trust fully\n 5 = I trust ultimately\n m = back to the main menu\n\nYour decision? 3\n# Output:\npub ed25519/0x76A5EF9054449A5C\n created: 2022-10-31 expires: 2037-10-27 usage: SC\n trust: marginal validity: full\nYou can see that the trust is marginal and validity is full.
![\"boxes\"](\"https://saylesss88.github.io/images/boxes.cleaned.png\")
NixOS containers are lightweight systemd-nspawn containers managed\ndeclaratively through your NixOS configuration. They allow you to run separate,\nminimal NixOS instances on the same machine, each with its own services,\npackages, and (optionally) network stack.
\n\n❗ NixOS’ containers do not provide full security out of the box (just like\ndocker). They do give you a separate chroot, but a privileged user (root) in a\ncontainer can escape the container and become root on the host system.\n–beardhatcode Declarative-Nixos-Containers
\n
Common Use Cases
\nIsolating services: Run a web server, database, or any service in its own\ncontainer, so it can’t interfere with the main system or other services
\nTesting and development: Try out new configurations, packages, or services\nin a sandboxed environment.
\nReproducible deployments: Because containers are defined declaratively,\nyou can reproduce the exact same environment anywhere.
\nRunning multiple versions of a service: For example, testing different\nversions of Git or HTTP servers side by side.
\nLet’s say you want to host your mdBook. You can define a NixOS container that\nruns only the necessary service, isolated from your main system:
\n{\n config,\n lib,\n ...\n}: {\n containers.mdbook-host = {\n autoStart = true;\n ephemeral = true;\n privateNetwork = false; # Use the hosts network\n\n bindMounts.\"/var/www/mdbook\" = {\n hostPath = \"/home/jr/nix-book/book\";\n isReadOnly = true;\n };\n\n config = {containerPkgs, ...}: {\n networking.useDHCP = lib.mkDefault true;\n\n services.httpd = {\n enable = true;\n adminAddr = \"yourEmail.com\";\n virtualHosts.\"localhost\" = {\n documentRoot = \"/var/www/mdbook\";\n serverAliases = [];\n };\n };\n\n networking.firewall.allowedTCPPorts = [80];\n environment.systemPackages = with containerPkgs; [];\n system.stateVersion = \"25.05\";\n };\n };\n}\nephemeral: 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\nNixOS system.
Mounts
\n bindMounts.\"/var/www/mdbook\" = {\n hostPath = \"/home/jr/nix-book/book\";\n isReadOnly = true;\n };\nThe bindMount settings above specify that /var/www/mdbook in the container\nshould 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\ncomplicated when you need HTTPD to have write privileges.
When you create and run a NixOS container like mdbook-host. NixOS stores the\ncontainer’s root filesystem and related container state data under:
ls /var/lib/nixos-containers/\n╭────────────╮\n│ empty list │ # It's empty because we set ephemeral to true\n╰────────────╯\nThis directory holds the container’s own filesystem image, including system\nfiles, installed packages, configuration, and any data internal to the\ncontainer.
\nnixos-container list\nmdbook-host\nsudo systemctl status container@mdbook-host\n Main PID: 32938 (systemd-nspawn)\n Status: \"Container running: Ready.\"\nTest HTTP server inside the container
\nWe configured Apache (httpd) to serve /var/www/mdbook at localhost
Let’s check if Apache is running:
\nsudo nixos-container run mdbook-host -- systemctl status httpd\n● httpd.service - Apache HTTPD\n Loaded: loaded (/etc/systemd/system/httpd.service; enabled; preset: ignored)\n Active: active (running) since Fri 2025-08-15 10:14:39 EDT; 2min 18s ago\nCheck the Bind Mount:
\nsudo nixos-container run mdbook-host -- ls -l /var/www/mdbook\nindex.html and any other files from ~/nix-book/bookTest the Web Server:
\ncurl http://localhost\nTest on the web, in your browser visit:
\nhttp://localhost/\nMake sure your book has the correct permissions to allow hostPath to read it:
sudo chmod -R o+rX ~/nix-book/book\nIf needed restart the container:
\nsudo nixos-container stop mdbook-host\nsudo nixos-container start mdbook-host\nEnsure that /var/www/mdbook is being populated:
sudo nixos-container run mdbook-host -- ls -l /var/www/mdbook\nYou should see an index.html and more
sudo nixos-container run mdbook-host -- systemctl status httpd\nenabled & active (running)Check the containers status:
\nsudo nixos-container status mdbook-host\nup\n~/nix-book/book on the host are\nimmediately reflected inside the container. This allows for:\nRapid iteration and testing of your books content without rebuilding
\nEasier debugging and fixing content or config issues on the fly.
\nTo remove /var/lib/nixos-containers/mdbook-host, you need to remove the\ncontainer configuration, rebuild, and then run the following commands to remove\nthe immutable sticky bits that prevent deletion.
# Forcibly remove all attributes\nsudo chattr -R -i mdbook-host/\nsudo rm -rf mdbook-host/\n\n\n\nIf you want to use
\nmdbook-nix-replcheck out the README, the following shows\nhow I tested locally before eventually adding aflake.nixto the repo\nstreamlining this for users of the project.
This documents how to work with a local Rust crate repository without a\nflake.nix for testing. The README above explains how to generate a token and\nuse the project, this is just for educational purposes if you wanted to\nimplement something similar:
nix-repl-server.nix, place this in the same dir as your\nconfiguration.nix:{\n config,\n lib,\n pkgs,\n inputs,\n ...\n}:\n\nlet\n cfg = config.custom.nix-repl-server;\n\n serverSource = inputs.mdbook-nix-repl + \"/server\";\n\n # 1. Build the binary using your package definition\n # serverPkg = pkgs.callPackage ./server-pkg.nix { };\n serverPkg = pkgs.callPackage ./server-pkg.nix {\n src = serverSource;\n };\n\n # 2. Build a minimal container image containing just the server + nix + deps\n nixReplImage = pkgs.dockerTools.buildLayeredImage {\n name = \"nix-repl-server\";\n tag = \"latest\";\n\n # dependencies needed at runtime inside the container\n contents = [\n serverPkg\n pkgs.nix\n pkgs.bashInteractive\n pkgs.cacert\n pkgs.tini\n pkgs.coreutils\n ];\n\n config = {\n Entrypoint = [\n \"${pkgs.tini}/bin/tini\"\n \"--\"\n ];\n Cmd = [ \"${serverPkg}/bin/nix-repl-server\" ];\n ExposedPorts = {\n \"8080/tcp\" = { };\n };\n # Important: Container must see 0.0.0.0 to receive traffic from host port mapping\n Env = [\n \"NIX_REPL_BIND=0.0.0.0\"\n \"NIX_CONFIG=experimental-features = nix-command flakes\"\n \"SSL_CERT_FILE=${pkgs.cacert}/etc/ssl/certs/ca-bundle.crt\"\n ];\n };\n };\nin\n{\n options.custom.nix-repl-server = {\n enable = lib.mkEnableOption \"nix-repl-server container\";\n port = lib.mkOption {\n type = lib.types.port;\n default = 8080;\n description = \"Host port to map to the container\";\n };\n tokenFile = lib.mkOption {\n type = lib.types.path;\n default = \"/etc/nix-repl-server.env\";\n description = \"Path to file containing NIX_REPL_TOKEN=...\";\n };\n };\n\n config = lib.mkIf cfg.enable {\n # Enable Podman backend\n virtualisation.podman.enable = true;\n virtualisation.oci-containers.backend = \"podman\";\n\n # The OCI container definition\n virtualisation.oci-containers.containers.nix-repl-server = {\n image = \"nix-repl-server:latest\";\n\n # This effectively \"loads\" the image into Podman on boot\n imageFile = nixReplImage;\n\n ports = [ \"127.0.0.1:${toString cfg.port}:8080\" ];\n\n # Inject the token safely at runtime (not in Nix store)\n environmentFiles = [ cfg.tokenFile ];\n\n extraOptions = [\n \"--cap-drop=ALL\"\n \"--security-opt=no-new-privileges\"\n \"--pull=never\" # Use the local loaded image\n ];\n };\n };\n}\nserver-pkg.nix, place this in the same dir as nix-repl-server.nix:{\n lib,\n rustPlatform,\n nix,\n pkg-config,\n openssl,\n makeWrapper,\n inputs,\n src,\n}:\n\nrustPlatform.buildRustPackage {\n pname = \"nix-repl-server\";\n version = \"0.1.0\";\n\n # Point this to your actual source root (where Cargo.toml is)\n # src = ./.;\n inherit src;\n\n # You must commit Cargo.lock for this to work\n # cargoLock.lockFile = ../../../mdbook-nix-repl/server/Cargo.lock;\n cargoLock.lockFile = \"${src}/Cargo.lock\";\n\n postPatch = ''\n cp Cargo.toml.inc Cargo.toml\n '';\n\n # Runtime dependencies (nix for evaluation)\n nativeBuildInputs = [\n pkg-config\n makeWrapper\n ];\n buildInputs = [ openssl ];\n\n doCheck = false;\n\n # Ensure 'nix' is available in the path if your binary calls Command::new(\"nix\")\n postInstall = ''\n wrapProgram $out/bin/nix-repl-server --prefix PATH : ${lib.makeBinPath [ nix ]}\n '';\n\n meta = with lib; {\n description = \"Secure Nix REPL server for mdbook-nix-repl\";\n platforms = platforms.linux;\n };\n}\nflake.nix, this URL leads to a Rust crate repo:inputs = {\n mdbook-nix-repl = {\n url = \"path:/home/jr/mdbook-nix-repl\";\n flake = false;\n };\n}\nconfiguration.nix:{ pkgs, inputs, ... }:\n{\n imports = [\n # Include the results of the hardware scan.\n ./hardware-configuration.nix\n ./users.nix\n ./nix-repl-server.nix\n ];\n\n custom.nix-repl-server = {\n enable = true;\n port = 8080; # Optional, defaults to 8080\n tokenFile = \"/etc/nix-repl-server.env\";\n };\n# --snip--\n\n\nNOTE: This example assumes you’re packaging a crate that’s already on\ncrates.io, or you’re packaging an existing Rust project for nixpkgs.
\n
Nixpkgs is a big repository, so it helps to start with a focused workflow:\ncreate a branch, add a package under pkgs/by-name/, build it, then open a PR.
NixOS/nixpkgs:git clone git@github.com:your-user/nixpkgs.git\ncd nixpkgs\ngit remote add upstream git@github.com:NixOS/nixpkgs.git\n(SSH avoids HTTPS helper issues)
\ngit fetch --unshallow --tags\ngit switch -c mdbook-rss-feed\nNew top-level packages should generally go under\npkgs/by-name/<2 letters>/<name>/package.nix (e.g.\npkgs/by-name/md/mdbook-rss-feed/package.nix). Packages in pkgs/by-name are\npicked up automatically and usually don’t require edits to all-packages.nix.
Start with rustPlatform.buildRustPackage and fetchCrate:
{\n lib,\n rustPlatform,\n fetchCrate,\n versionCheckHook,\n}:\nrustPlatform.buildRustPackage rec {\n pname = \"mdbook-rss-feed\";\n version = \"1.3.0\";\n\n src = fetchCrate {\n inherit pname version;\n hash = \"output of `nix hash convert` shown below\";\n };\n\n cargoHash = lib.fakeHash;\n\n nativeInstallCheckInuts = [\n versionCheckHook\n ];\n doInstallCheck = true;\n\n meta = {\n description = \"mdBook preprocessor that generates RSS, Atom, and JSON feeds\";\n mainProgram = \"mdbook-rss-feed\";\n homePage = \"https://crates.io/crates/mdbook-rss-feed\";\n license = lib.licenses.asl20;\n maintainers = [ lib.maintainers.sayls88 ];\n };\n}\nUse fetchCrate / crate2nix style workflow, or just prefetch the crates.io\ntarball:
nix-prefetch-url \\\n --unpack \\\n https://crates.io/api/v1/crates/mdbook-rss-feed/1.3.0/download\nThat prints a base32 hash: 0932843lknasdlfkm2lkdnflaknldvdsvser
Convert it to sri format:
\nnix hash convert --hash-algo sha256 --from nix32 --to sri 0932843lknasdlfkm2lkdnflaknldvdsvser\nThe above commands output looks like: sha256-...=
Put the resulting sha256-... into src.hash:
src = fetchCrate {\n inherit pname version;\n hash = \"sha256-...\";\n };\nIn the nixpkgs root (i.e., the nixpkgs directory), run:
nix-build -A mdbook-rss-feed\n# OR nix3 format\nnix build .#mdbook-rss-feed\nNix will fail with a message like:
\nhash mismatch\nspecified: sha256-....\ngot: sha256-1...\nCopy the got value into cargoHash, rebuild, and it should succeed.
Sanity check: from nixpkgs root :
./result/bin/mdbook-rss-feed --version\nEdit nixpkgs/maintainers/maintainer-list.nix add your user in alphabetical\norder:
your-handle = {\n email = \"you@example.com\";\n name = \"Your Name\";\n github = \"your-gh-handle\";\n githubId = 12345678;\n};\nIf you specify github, nixpkgs expects githubId too. You can get it from:\nhttps://api.github.com/users/<user>.
The nixpkgs maintainers prefer if you add the maintainer-list.nix as a\nseparate commit.
git commit -m \"maintainers: add <user>\"\nRun treefmt the nixpkgs way, from the repo root. Run this right before you push,\nmy editors formatter does something different with single entry lists than what\nNixpkgs wants:
\nnix develop --command treefmt\nnix fmt\nFrom the mdbook-rss-feed branch:
git fetch upstream --tags\ngit rebase upstream/master\nCommit and push your PR branch:
\nThen commit and push
\ngit commit -m \"mdbook-rss-feed: init at 1.3.0\"\n# First push\ngit push origin mdbook-rss-feed\n# Use `--force-with-lease` only if you rebased/amended and need to rewrite the PR branch.\n# git push --force-with-lease origin mdbook-rss-feed\n--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,\nthen retry.
Then commit and push
\ngit commit -m \"mdbook-rss-feed: init at 1.3.0\"\ngit push -u origin mdbook-rss-feed\nThen:
\nGo to GitHub -> your fork
\nClick “Compare & pull request” on the mdbook-rss-feed branch
Fill out the PR template (why useful, tested on x86_64-linux, etc.)
\nSubmit!
\nThe package will go through CI checks, and once green + approved by a\nmaintainer, it’ll land in nixpkgs.
\nYou’re bound to make mistakes, if you learn some Git basics it will help you\nquite a bit.
\nYou should avoid adding new commits for small fixes like typos, formatting, or\nminor adjustments requested in review. For substantial changes that add\nfunctionality, a new commit may be more appropriate.
\nSay that we pushed our PR and one of the maintainers gave us a suggested change,\n(they want us to follow conventions and remove a trailing period from our\npackages description for this example).
\nMake the edit locally (remove the trailing period in the file)
\nStage the change: git add pkgs/by-name/xx/your-package/package.nix (avoid\ngit add -A as it stages everything, which can accidentally include\nunrelated files)
Amend the commit: git commit --amend --no-edit(this preserves your original\ncommit message, if you want to change the commit message use\ngit commit --amend)
Force push: git push --force-with-lease (This is safer than just using\n--force because it will fail if someone else has pushed commits to your\nbranch that you don’t have locally)
Alternative for Multiple Commits
\nInteractive rebase is useful when your PR has several “WIP” commits (or you\nadded a small review fix as a separate commit) and you want to present a cleaner\nhistory before merge.
\nYou can use interactive rebase to squash all your would be small fix commits\ninto a single commit they belong to.
\nAvoid squashing if the commits represent distinct, reviewable changes that stand\non their own.
\nBasic Workflow (squash/fixup)
\ngit rebase -i HEAD~3\npick to fixup or squash:fixup = combine into the previous commit, discard this commit message.
squash = combine, but keep/edit commit messages.
Example todo:
\npick 1111111 mdbook-rss-feed: init at 0.1.0\npick 2222222 mdbook-rss-feed: fix trailing period\npick 3333333 mdbook-rss-feed: formatting\nChange to:
\npick 1111111 mdbook-rss-feed: init at 0.1.0\nfixup 2222222 mdbook-rss-feed: fix trailing period\nfixup 3333333 mdbook-rss-feed: formatting\nPush updated history
\nYou have to force-push because rebase rewrites commit SHAs:
git push --force-with-lease\n# If something goes wrong\n# git rebase --abort\n# If you hit conflicts, fix the files, then:\n# git add <files>\n# git rebase --continue\nIf you have an unrelated change accidentally included (for example: you staged\nan extra file), it’s usually better to fix it via rebase/splitting before\nreviewers spend time re-reviewing noise.
\n\n\n", "date_published": "2025-12-31T00:00:00+00:00", "author": { "name": "saylesss87@proton.me (saylesss88)" } }, { "id": "https://saylesss88.github.io/nix/hardening_networking.html", "url": "https://saylesss88.github.io/nix/hardening_networking.html", "title": "Hardening Networking", "content_html": "As of 01-13-26 I have been waiting for 2 weeks for the darwin checks to complete,\nI guess this bottleneck\nhas gotten worse. I guess most PRs take about 6 weeks to resolve FYI.
\n
\n\nSince networks and systems vary, some adjustments may cause unexpected issues,\nespecially around critical components like DNS or firewalls. Always review and\ntest changes in a controlled environment before applying them broadly.
\n
\n\nUnderstand the trade-offs and tailor the settings to your threat model and\nworkflow. Take what’s useful, adapt as needed, and seek expert guidance for\nmore advanced scenarios.
\n
Every setup is unique, feel free to adapt or skip sections based on your needs.\nStart with the basics and build up as you gain confidence. The goal is\npractical, tested hardening tailored to you.
\nI recently broke this chapter down and added another chapter:\nBrowser/Browsing Security
\nAdopt Encrypted DNS and HTTPS Everywhere
\nConfigure your system and browsers to use DNS over HTTPS (DoH), DNS over TLS\n(DoT), or DNSCrypt to prevent DNS leakage. Use HTTPS-Only mode in browsers to\nencrypt all web traffic. Prefer browsers with strong privacy defaults or add\nrecommended extensions.
\nDisable browser “remember password” and autofill features, clear cookies and\nsite data upon exit, and carefully vet suspicious URLs with tools like\nVirusTotal.
\nLimit Account Linking and Use Unique Credentials
\nUse Metadata Cleaning Tools
\nMany files like images, PDFs, and office documents contain hidden metadata\ninformation such as location data, device details, and more that can reveal\nyour identity or other sensitive information when you share files publicly.
\nTo protect your privacy, always sanitize files by removing this metadata\nbefore sharing. Tools like mat2 are\ndesigned to strip metadata from a wide range of media files efficiently.\n(pkgs.mat2). You just type mat2 swappy-2025.png for example and there will\nthen be a new mat2 swappy-2025.cleaned.png that can safely be shared.
Use Anonymous File-Sharing Tools
\npkgs.onionshare)Avoid Scanning Random QR Codes Without Verification
\nUnderstand Your Threat Model
\nDelete cookies and site data when the browser is closed. (security not\nusability).
\nUse Strong, Unique Passwords and a Password Manager
\nAvoid reused passwords by using reliable password managers like KeePassXC or\nBitwarden, both available on NixOS. Pair this with enabling two-factor\nauthentication (2FA) wherever possible.
\nIt’s advisable to only use the desktop version and not the browser extension\nfor a number of reasons. One is that you can store your passwords completely\noffline and have complete ownership of them.
\nenvironment.systemPackages = [\n pkgs.keepassxc\n pkgs.kpcli # KeePass CLI\n # OR\n pkgs.bitwarden-desktop\n pkgs.bitwarden-cli\n];\nWith KeePassXC, you can require 3 different authentication methods at the same\ntime. You can choose a password, a keyfile, and a security key where it won’t\nopen unless all 3 are present giving you additional security. All 3 might not be\nnecessary but it’s possible. It’s also easy to migrate to KeePassXC, you can\nimport your vault from many different managers.
\nKeepassXC also makes it easy to keep your complete password database offline\nwhich can significantly reduce the risk of a breach.
\nWith Bitwarden, to enable 2 factor authentication, you need to log in with your\nmaster password through the web interface.
\n\nThese recommended steps help protect your privacy and security while maintaining\nusability and minimizing system interruptions. They catch common threats like\nnetwork eavesdropping, password reuse, fingerprinting, and data leakage,\nproviding a solid foundation to build on.
\nA vast majority of secure and privacy-focused browsers available for NixOS are\nbased on Firefox.
\n\n\n\n❗ NOTE: Firefox does lack some security features available in Chrome and\nsandbox escapes in Linux are relatively easy. People such as madaidan say to\nnever use Linux or Firefox period when you’re worried about security and\nprivacy. I’m not personally going to jump to proprietary software with known\nbackdoors in a misguided attempt at increasing security/privacy.
\n
This GrapheneOS article, breaks\ndown why they use Chromium-based browsers and specifically mentions that it’s\nnot recommended to use Firefox, especially on Linux because of the weak\nsandboxing.
\nAs a Chromium-based browser, Brave has been growing on me. Brave uses\nrandomization rather than standardization for fingerprinting protection. If you\nrun Cover Your Tracks with Brave, it will show a randomized fingerprint.
\nSection 215 USA Patriot Act\npermits the collection of “Tangible Things” or “Business Records”, e.g., your\nphone records, medical records, etc. for an investigation to obtain foreign\nintelligence information. If it does relate to a US person it must be relevant\nto preventing terrorism or espionage, and not be based solely on activities\nprotected by the first amendment. “Relevant” is the key word here and it is at\nthe governments discretion meaning they sweep everything and sift it later.\nCriticized for violating American citizens Fourth Amendment protections against\nwarrantless search and seizure and proven to be ineffective.
\nWhat is “normal” and allowed today might be suppressed tomorrow, look at the UK\nOnline Safety Act\npurported to protect children, accused of banning privacy. This is because the\nonly way to verify age is to make everyone submit KYC with their drivers license\nor ID, completely taking away any anonymity of adults and children alike.
\nAlso see\nBBC 4chan refuses to pay fine
\nThe mere existence of a surveillance state breeds fear and conformity and\nstifles free\nexpression.–The Intercept
\nThere are much more scary examples in\nPrivacy, The new Oil
\n\n\n⚠️ A crucial caveat to keep in mind regarding surveillance protections in the\nU.S., whether grounded in the Fourth Amendment, the First Amendment, or\nstatutory laws is that these protections are not foolproof and have\nrepeatedly failed or been circumvented in practice.
\n
Fourth Amendment Basics: It demands reasonableness in searches and usually\nrequires a warrant. This means government agents cannot arbitrarily listen to\nyour private communications or search your digital data without judicial\napproval
\nElectronic Surveillance Challenges: Courts have wrestled with how the\nFourth Amendment applies to modern communications. The Supreme Court has ruled\nin some cases that pervasive or non-consensual electronic surveillance\nviolates reasonable expectations of privacy, but other rulings have allowed\nbroader state actions in national security contexts.
\nThe Third-Party Doctrine: A major limitation arises from the “third-party\ndoctrine,” which holds that information voluntarily shared with third parties\n(like phone companies or internet providers) has reduced Fourth Amendment\nprotections. This means data held by third parties may be subject to\ngovernment access without a warrant in some cases
\nThe First Amendment guarantees free speech and the freedom to receive\ninformation without government censorship or intimidation. Excessive or\nsecretive government surveillance can chill free speech by making people\nafraid their communications are monitored, discouraging open expression and\nparticipation in public discourse.
\nWhile the Fourth Amendment traditionally governs searches and surveillance\nlegality, the First Amendment frames the broader impact on free speech and\ndemocratic engagement. Invoking both provides a more comprehensive\nconstitutional shield against intrusive surveillance practices.
\nDNS (Domain Name System) resolution is the process of translating a website’s\ndomain name into its corresponding IP address. By default, this traffic isn’t\nencrypted, which means anyone on the network, from your ISP to potential\nhackers, can see the websites you’re trying to visit. Encrypted DNS uses\nprotocols to scramble this information, protecting your queries and responses\nfrom being intercepted and viewed by others.
\n\n\n❗ NOTE: There are many other ways for someone monitoring your traffic to see\nwhat domain you looked up via DNS that it’s effectiveness is questionable\nwithout also using Tor or a VPN. Encrypted DNS will not help you hide any of\nyour browsing activity.
\n
There are 3 main types of DNS protection:
\nDNS over HTTPS (DoH): Uses the HTTPS protocol to encrypt data between the\nclient and the resolver.
\nDNS over TLS (DoT): Similar to (DoH), differs in the methods used for\nencryption and delivery using a separate port from HTTPS.
\nDNSCrypt: Uses end-to-end encryption with the added benefit of being able\nto prevent DNS spoofing attacks.
\nUseful resources:
\nHot Take:
\n\nThe following sets up dnscrypt-proxy using ODoH (Oblivious DNS over HTTPS) with\nan oisd blocklist:
\nAdd oisd to your flake inputs:
# flake.nix\ninputs = {\n oisd = {\n url = \"https://big.oisd.nl/domainswild\";\n flake = false;\n };\n};\nTo use the Hagezi Multi PRO Blocklist either with oisd or alone you could do the\nfollowing:
\n# flake.nix\ninputs = {\n oisd = {\n url = \"https://big.oisd.nl/domainswild\";\n flake = false;\n };\n hagezi = {\n url = \"https://raw.githubusercontent.com/hagezi/dns-blocklists/main/wildcard/pro-onlydomains.txt\";\n flake = false;\n };\n};\nadd it to the extraBlocklist variable in the following dnscrypt-proxy.nix:
# dnscrypt-proxy.nix\nextraBlocklist = builtins.readFile inputs.hagezi;\nMore blocklist url’s:
\n# NextDNS CNAME cloaking list\nhttps://raw.githubusercontent.com/nextdns/cname-cloaking-blocklist/master/domains\n\n# AdGuard Simplified Domain Names filter\nhttps://adguardteam.github.io/AdGuardSDNSFilter/Filters/filter.txt\n\n# OISD Big list\nhttps://big.oisd.nl/domainswild\n\n# HaGeZi Multi PRO\nhttps://raw.githubusercontent.com/hagezi/dns-blocklists/main/wildcard/pro-onlydomains.txt\n\n# HaGeZi Threat Intelligence Feeds\nhttps://raw.githubusercontent.com/hagezi/dns-blocklists/main/wildcard/tif-onlydomains.txt\n\n\n❗ NOTE: The
\noisdblocklist is a plain text file that updates frequently.\nThis can causenh os switchto fail with aNarHashmismatch error. To fix\nthis, you need to runnix flake updateto refresh the blocklist and its hash\nin yourflake.lockfile. After that, you can run yournhcommand again.
And the import the following into your configuration.nix:
# dnscrypt-proxy.nix\n{\n pkgs,\n lib,\n inputs,\n ...\n}: let\n blocklist_base = builtins.readFile inputs.oisd;\n extraBlocklist = \"\";\n blocklist_txt = pkgs.writeText \"blocklist.txt\" ''\n ${extraBlocklist}\n ${blocklist_base}\n '';\n hasIPv6Internet = true;\n StateDirName = \"dnscrypt-proxy\"; # Used for systemd StateDirectory\n StatePath = \"/var/lib/${StateDirName}\";\nin {\n networking = {\n nameservers = [\"127.0.0.1\" \"::1\"];\n networkmanager.dns = \"none\";\n };\n\n services.resolved.enable = lib.mkForce false;\n\n services.dnscrypt-proxy = {\n enable = true;\n settings = {\n sources.public-resolvers = {\n urls = [\n \"https://raw.githubusercontent.com/DNSCrypt/dnscrypt-resolvers/master/v3/public-resolvers.md\"\n \"https://download.dnscrypt.info/resolvers-list/v3/public-resolvers.md\"\n ];\n minisign_key = \"RWQf6LRCGA9i53mlYecO4IzT51TGPpvWucNSCh1CBM0QTaLn73Y7GFO3\";\n cache_file = \"${StatePath}/public-resolvers.md\";\n };\n\n sources.relays = {\n urls = [\n \"https://raw.githubusercontent.com/DNSCrypt/dnscrypt-resolvers/master/v3/relays.md\"\n \"https://download.dnscrypt.info/resolvers-list/v3/relays.md\"\n ];\n cache_file = \"${StatePath}/relays.md\";\n minisign_key = \"RWQf6LRCGA9i53mlYecO4IzT51TGPpvWucNSCh1CBM0QTaLn73Y7GFO3\";\n };\n\n sources.odoh-servers = {\n urls = [\n \"https://raw.githubusercontent.com/DNSCrypt/dnscrypt-resolvers/master/v3/odoh-servers.md\"\n \"https://download.dnscrypt.info/resolvers-list/v3/odoh-servers.md\"\n ];\n cache_file = \"${StatePath}/odoh-servers.md\";\n minisign_key = \"RWQf6LRCGA9i53mlYecO4IzT51TGPpvWucNSCh1CBM0QTaLn73Y7GFO3\";\n };\n\n sources.odoh-relays = {\n urls = [\n \"https://raw.githubusercontent.com/DNSCrypt/dnscrypt-resolvers/master/v3/odoh-relays.md\"\n \"https://download.dnscrypt.info/resolvers-list/v3/odoh-relays.md\"\n ];\n cache_file = \"${StatePath}/odoh-relays.md\";\n minisign_key = \"RWQf6LRCGA9i53mlYecO4IzT51TGPpvWucNSCh1CBM0QTaLn73Y7GFO3\";\n };\n\n server_names = [\"odoh-cloudflare\" \"odoh-snowstorm\"];\n\n # This creates the [anonymized_dns] section in dnscrypt-proxy.toml\n anonymized_dns = {\n skip_incompatible = true;\n routes = [\n {\n server_name = \"odoh-snowstorm\";\n via = [\"odohrelay-crypto-sx\"];\n }\n {\n server_name = \"odoh-cloudflare\";\n via = [\"odohrelay-crypto-sx\"];\n }\n ];\n };\n\n ipv6_servers = hasIPv6Internet;\n block_ipv6 = !hasIPv6Internet;\n blocked_names.blocked_names_file = \"${blocklist_txt}\";\n require_dnssec = true;\n require_nolog = false;\n require_nofilter = false;\n odoh_servers = true;\n dnscrypt_servers = true;\n };\n };\n\n # This creates /var/lib/dnscrypt-proxy with correct permissions\n systemd.services.dnscrypt-proxy2.serviceConfig.StateDirectory = StateDirName;\n}\nThis module follows a “Zero Trust” model for your internet traffic, ensuring no\nsingle entity can see both who you are and where you are going.
\n# You should see that dnscrypt-proxy chooses the Server with the lowest initial latency\nsudo systemctl status dnscrypt-proxy2\n# verify that dnscrypt-proxy is listening\nsudo ss -lnp | grep 53\n# Test a DNS query, if you get valid responses it's working\ndig @127.0.0.1 example.com +short\n# check the logs\nsudo journalctl -u dnscrypt-proxy2\ndnscrypt-proxy2 acts as your local DNS resolver listening on your machine\n(127.0.0.1) for IPv4 and ::1 for iPv6.
The system’s DNS settings (networking.nameservers) point to localhost, so\nall DNS queries go to dnscrypt-proxy accept for your browser. Your browser\nhas to be configured separately with a local resolver in which I haven’t figured\nout yet. I recommend setting your browsers DNS over HTTPS to strict with a\nrespected custom DNS resolver such as https://dns.quad9.net/dns-query.
inputs.oisd refers to the flake input oisd blocklist, it prevents your device\nfrom connecting to unwanted or harmful domains.
dnscrypt-proxy2 then encrypts and forwards our DNS requests to third-party\npublic DNSCrypt or DoH servers.
I was surprised at how easy this actually was to set up. Either go to\nhttps://www.tailscale.com and/or download the app for either Android or IOS,\nsign up with your identity provider, and click Start connecting devices ->
To add tailscale to NixOS:
\n# tailscale.nix\n{...}: {\n services.tailscale.enable = true;\n # Tell the firewall to implicitly trust packets routed over Tailscale:\n networking.firewall.trustedInterfaces = [\"tailscale0\"];\n}\nTailscale will automatically use the hostname of your device as the name of the\nnetwork. If you want to change it to something else:
\nsudo tailscale set --hostname=<name>\n# You can also give your account a nickname\nsudo tailscale set --nickname=<name>\nThis allows you to refer to your network by name rather than IP address.
Tailscale uses MagicDNS which is\nenabled by default, and they recommend you keep it enabled.
\nThe docs say that by default, devices in your tailnet prefer their local DNS\nsettings and only use the tailnet’s DNS servers when needed. I had to completely\ndisable my Androids DNS settings for tailscale to access the internet through\nMagicDNS.
\nsudo tailscale set --accept-dns=false\nTo connect to tailscale after rebuilding you can run:
\nsudo tailscale up\nUse nslookup to review and debug DNS responses:
nslookup google.com\nServer: 127.0.0.1\nAddress: 127.0.0.1#53\n\nNon-authoritative answer:\nName: google.com\nAddress: 142.251.40.206\nName: google.com\nAddress: 2a00:1450:4001:827::200e\n127.0.0.1#53 indicate that instead of using the DNS server pushed by\nyour ISP, router, or Tailscale’s MagicDNS, the system is sending all DNS\nrequests through the loopback device to dnscrypt-proxy in my case.Get the status of your connections to other Tailscale devices:
\ntailscale status\n1 2 3 4 5\n100.1.2.3 device-a apenwarr@ linux active; direct <ip-port>, tx 1116 rx 1124\n100.4.5.6 device-b crawshaw@ macOS active; relay <relay-server>, tx 1351 rx 4262\n100.7.8.9 device-c danderson@ windows idle; tx 1214 rx 50\n100.0.1.2 device-d ross@ iOS —\nThere is much more you can do with Tailscale, including integrating\nMullvad-VPN and using Exit Nodes.
\nAll network cards have a unique identifier called a MAC address. They’re stored\nin hardware and are used to assign an address to computers on the local network.
\nThe MAC address is typically only traceable on the local network, it’s not\npassively sent out beyond the local router making it more critical on untrusted,\npublic networks.
\nLeak-proof MAC randomization is very difficult to implement:
\n\nAndroid and iPhone already implement MAC Randomization by default.
\nMAC Randomization enhances privacy by making it harder for third parties to\ntrack users across different networks.
\nRandomizing MAC adresses obscures a device’s unique hardware identity when\nscanning for or connecting to Wi-Fi, blocking passive tracking as well as\nlocation tracking across networks.
\nIf you use NetworkManager you can set MAC randomization with:
\n networking = {\n networkmanager = {\n enable = true;\n wifi.scanRandMacAddress = true;\n wifi.macAddress = \"random\";\n plugins = [];\n };\nRight when I rebuilt, I got an alert from my router saying that a new device\njust connected to the network.
\nThere is also a utility for viewing/manipulating the MAC address of network\ninterfaces, pkgs.macchanger. This is less reliable than the NetworkManager\nsetting.
NixOS includes an integrated firewall based on iptables/nftables.
\nThe following firewall setup is based on the dnscrypt setup above utilizing\nnftables.
\nThis nftables firewall configuration is a strong recommended practice for\nenforcing encrypted DNS on your system by restricting all outbound DNS traffic\nto a local dnscrypt-proxy process. It greatly reduces DNS leak risks and\nenforces privacy by limiting DNS queries to trusted, encrypted upstream\nservers.(This was edited on 08-08-25) replace <DNSCRYPT-UID> with the UID\ngiven from the command ps -o uid,user,pid,cmd -C dnscrypt-proxy:
{ ... }: {\n networking.nftables = {\n enable = true;\n\n ruleset = ''\n table inet filter {\n chain output {\n type filter hook output priority 0; policy accept;\n\n # Allow localhost DNS for dnscrypt-proxy2\n ip daddr 127.0.0.1 udp dport 53 accept\n ip6 daddr ::1 udp dport 53 accept\n ip daddr 127.0.0.1 tcp dport 53 accept\n ip6 daddr ::1 tcp dport 53 accept\n\n # Allow dnscrypt-proxy2 to talk to upstream servers\n # Replace <DNSCRYPT-UID> with:\n # ps -o uid,user,pid,cmd -C dnscrypt-proxy\n meta skuid <DNSCRYPT-UID> udp dport { 443, 853 } accept\n meta skuid <DNSCRYPT-UID> tcp dport { 443, 853 } accept\n\n # Block all other outbound DNS\n udp dport { 53, 853 } drop\n tcp dport { 53, 853 } drop\n }\n }\n '';\n };\n networking.firewall = {\n enable = true;\n allowedTCPPorts = [\n # Ports open for inbound connections.\n # Limit these to reduce the attack surface.\n\n 22 # SSH – Keep open only if you need remote access.\n # To change the SSH port in NixOS:\n # services.openssh.ports = [ 2222 ];\n # Update this list to match the new port.\n\n # 53 # DNS – Only if running a public DNS server.\n # 80 # HTTP – Only if hosting a website.\n # 443 # HTTPS – Only if hosting a secure website.\n ];\n allowedUDPPorts = [\n # Ports open for inbound UDP traffic.\n # Most NixOS workstations won't need any here.\n\n # 53 # DNS – Only if running a public DNS server.\n ];\n };\n}\n\n\n❗ TIP: Reduce SSH noise by changing the default port On most systems, SSH\nlistens on TCP port 22 — which means automated bots and scanners will hit it\nconstantly. While this doesn’t replace real security measures, moving SSH to a\ndifferent port drastically cuts down on drive-by brute-force attempts you’ll\nsee in your logs.
\nIn NixOS, change both the SSH daemon port and your firewall rule:
\n\n# Example: Move SSH to port 2222\n networking.firewall.allowedTCPPorts = [ 2222 ];\n services.openssh.ports = [ 2222 ];\n\n
\n- After rebuilding, test from another terminal/session before closing your\nexisting one:
\n\nssh -p 2222 user@host\n
nft is a cli tool used to set up, maintain and inspect packet filtering and\nclassification rules in the Linux kernel, in the nftables framework. The Linux\nkernel subsystem is known as nftables, and ‘nf’ stands for Netfilter.–man nft
sudo nft list ruleset\nnft to inspect our ruleset.nftables Rulesetnetworking.nftables: This section provides a raw nftables ruleset that gives\nyou granular, low-level control. The rules here are more specific and are meant\nto handle the intricate logic of the DNS proxy setup. They will be applied\ndirectly to the kernel’s nftables subsystem and prevent DNS leaks.
networking.firewall: This is a higher-level, simpler NixOS option that uses\niptables rules to open ports for inbound traffic. The rules defined here\n(allowing port 22) is for incoming SSH connections to the machine, not for\noutbound traffic, so they do not interfere with the nftables rules that filter\nthe outgoing traffic. (Make sure to comment out or remove this if you don’t SSH\ninto your machine).
The firewall ensures only authorized, local encrypted DNS proxy process can\nspeak DNS with the outside world, and that all other DNS requests from any other\nprocess are blocked unless they’re to 127.0.0.1 (our local proxy). This is a\nrobust policy against both DNS leaks and local compromise.
Review listening ports: After each rebuild, use ss -tlpn, nmap or netstat\nto see which services are accepting connections. Close or firewall anything\nunnecessary.
You can also test firewall DNS restrictions using dig:
dig @127.0.0.1 example.com # Should work\n\ndig @8.8.8.8 example.com # Should fail/time out for normal users\ndig command gave results letting me know that the restrictions weren’t being\napplied correctly.Since we defined an output chain inside table inet filter with the line:
type filter hook output priority 0; policy accept;\nThis attaches the chain to the kernel’s OUTPUT hook, so all locally generated\npackets, including DNS queries are filtered by this chain.
\nWithin this chain, the rules:
\nExplicitly allow DNS queries to localhost addresses (127.0.0.1 and ::1).
Allow the dnscrypt-proxy process (running with UID 62396) to send DNS\nqueries 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,\nbut queries directly to public DNS servers like 8.8.8.8 are blocked for\nusers/processes other than the allowed DNS proxy.
Opensnitch is an open-source\napplication firewall that focuses on monitoring and controlling outgoing network\nconnections on a per-application basis.
\nThis can be used to block apps from accessing the internet that shouldn’t need\nto (i.e., block telemetry and more). Opensnitch will report that the app has\nattempted to make an outbound internet connection and block it or allow it based\non the rules you set.
\nSurveillance Self-Defence has a lot of helpful info to\nprotect your privacy.
\nWhat is Fingerprinting, more\nthan you realize is being tracked constantly.
\noisd.nl the oisd website
\nFor potentially dangerous file types like PDFs, office documents, or images,\nespecially those downloaded from untrusted sources such as torrents, consider\nconverting them to a safe PDF format with\ndangerzone. Dangerzone not\nonly removes metadata but also applies robust sanitization to neutralize\nmalicious content.
\nNixOS Wiki LibreWolf, the options in\nthe wiki make it less secure and aren’t recommended settings to use. They\nexplicitly disable several of LibreWolf’s default privacy-enhancing features,\nsuch as fingerprinting resistance and clearing session data on shutdown.
\nLibreWolf Features You still need to\nenable DNS over HTTPS through privacy settings.
\n\n\nIf you should trust the U.S. Governments recommendations is another story but\nit can be good to compare and contrast with other trusted resources. You’ll\nhave to think whether the CISA recommending that everyone uses Signal is solid\nadvice or guiding you towards a honeypot, I can’t say for sure.
\n
Mozilla Firefox Security Technical Implementation Guide\nThe STIG for Mozilla Firefox (Security Technical Implementation Guide) is a\nset of security configuration standards developed by the U.S. Department of\nDefense. They are created by the Defense Information Systems Agency (DISA) to\nsecure and harden DoD information systems and software.
\nFirefox Relay can be used to\ncreate email aliases that forward to your real email address. The paid plan\nalso lets you create phone number aliases that forward to your phone number.
\n\n\n“The major problem with current systems is their inability to provide\neffective isolation between various programs running on one machine. E.g. if\nthe user’s Web browser gets compromised (due to a bug exploited by a malicious\nweb site), the OS is usually unable to protect other user’s applications and\ndata from also being compromised.” –Qubes arch-spec
\n
The web browser is the most complex, most exposed, and most vulnerable\napplication on a hardened Linux system. It is your primary interface with the\ninternet and, consequently, the primary vector for exploitation and tracking.
\nThe Three Pillars of Web Defense To secure your browsing, you must balance\nthree often-conflicting goals:
\nSecurity (Exploit Mitigation): Preventing malicious sites from escaping\nthe browser sandbox to access your local files or execute code.
\nPrivacy (Tracking Protection): Preventing advertisers and sites from\nlinking your current session to your real-world identity or browsing history.
\nAnonymity (Identity Obfuscation): Making your traffic indistinguishable\nfrom thousands of other users to hide your physical location and legal\nidentity.
\nBrowser hardening focuses on reducing attack surface and blocking tracking\nby disabling or restricting features like JavaScript, cookies, telemetry, and\nthird-party scripts.
\nFingerprint protection, on the other hand, aims to make your browser\nindistinguishable from others. Instead of just blocking data collection, it\nensures that your browser’s configuration; screen size, fonts, user agent,\netc. matches a large group of users, so you blend in.
\nAnonymity: Maximizing anonymity often means restricting or masking\nfeatures (setting a generic fingerprint, disabling browser APIs, blocking\ntrackers) so the browser blends in with many others. This reduces uniqueness\nbut can break website functionality, cause CAPTCHAs, and limit usability.
\nBrowser compartmentalization is a technique where different browsers are\ndedicated to distinct online activities to isolate cookies, trackers, and\nbrowsing data. For example, Mullvad Browser can be used solely for activities\nwhere fingerprinting resistance is critical, such as anonymous browsing or\nvisiting privacy-sensitive sites. Meanwhile, a hardened LibreWolf or Firefox\ncan be used for general browsing, email, or banking where you want solid\nsecurity and feature flexibility but aren’t as concerned about fingerprint\nuniqueness.
\nOn a hardened Linux system, the browser is most often the weakest link exposed\nto the internet, and so security, privacy, and anti-tracking features of\nbrowsers are now as important, or even more important than platform-level\nprotections.
\nBrowsers leak identity in two main ways: network identifiers (IP address,\nDNS, TLS metadata) and browser identifiers (fingerprinting + tracking). This\nchapter focuses on the browser side first, then covers when a VPN or Tor changes\nthe network side. Before tweaking anything, pick the browsing goal (anonymity vs\nprivacy vs convenience), because the “best” settings differ.
\nIf the goal is blending in, prefer a browser that ships with a shared,\nconsistent fingerprint (Tor Browser / Mullvad Browser). If the goal is mainly\nreducing cross-site tracking for normal browsing, a hardened Firefox/LibreWolf\nprofile with minimal extensions is usually easier to live with.
\nModern web APIs make rich, customized experiences possible, but they also reveal\nenough low‑level details about your device and browser to build a unique\nfingerprint. This fingerprint can be used for hidden, persistent tracking, even\nwhen cookies are blocked.
\nBrowser fingerprinting is a tracking technique, often done by third-party\ncompanies that specialize in it. They provide code (usually JavaScript) that a\nwebsite owner can embed on their site. When you visit the site, the script runs\nin the background, silently collecting data about your device and browser.
\nThere are two main approaches to obfuscating your fingerprint:
\nStandardization: Make browsers standardized and therefore have the same\nfingerprint to blend into a crowd. This is what Tor and Mullvad Browser do.\nBest for anonymity; increases the crowd you blend into, but may decrease\nusability (site breakage, CAPTCHAs); adversaries may still find subtle\ndifferences.
\nRandomization: Randomize fingerprint metrics so it’s not directly linkable\nto you. Brave has this feature, if you run coveryourtracks with Brave you will\nget a result of “your browser has a randomized fingerprint”. This is good for\nprivacy but may be detectable by advanced scripts.
\nYou can test your browser to see how well you are protected from tracking and\nfingerprinting at Cover Your Tracks.
\nAlso check out, Am I Unique
\n\n\n\n⚠️ WARNING: Don’t put too much weight into the results as people often check\ntheir fingerprint, change one metric and check it again over and over skewing\nthe results. It is helpful for knowing the fingerprint values that trackers\ntrack.
\n
I currently run NixOS in a VM with a secureblue host,\nTrivalent is my default browser, a\nsecurity-focused, Chromium-based browser.
\nIn this section, the goal is to outline several browser options on NixOS and\nshow concrete configurations (with a focus on LibreWolf that can be adapted to\nFirefox). Browsers are complicated and people have different security, privacy,\nand usability needs, so this is not an endorsement of a single “best” choice.\nInstead, the following subsections describe trade-offs and example setups so you\ncan decide which browser and configuration best match your own threat model and\nworkflow.
\nIMO there aren’t many Chromium-based browsers on NixOS that hit the sweet spot\nof being both security-forward and privacy-respecting. Many of the “privacy\nbrowser” options you’ll see on NixOS are Firefox forks; with the right tweaks\nthey can be made pretty private, but they generally don’t match Chromium-family\nbrowsers on exploit mitigations and sandbox depth.
\nBrave is basically “Chromium, but with privacy features turned on by default,”\nand the big win is that most of the protection comes from the browser itself\n(Shields + anti-fingerprinting) instead of from a pile of extensions. Brave’s\nfingerprinting story is also unusually practical: instead of trying to make\nevery Brave user look identical, it mixes API blocking with per-site/per-session\nrandomization (“farbling”) so the fingerprint is harder to reuse across\ncontexts.
\nOn NixOS, IMO the best available Chromium-based browser is Brave. Brave strips\nout Google’s tracking code and includes a native add/tracker blocker (Brave\nShields). It also ships a best‑effort anti‑fingerprinting system that combines\n(1) blocking/removing/modifying certain high-signal APIs and (2) “privacy\nthrough randomization” (farbling), where it returns slightly altered values so\nfingerprints don’t stay stable across sites/sessions.
\nThings to Note about Brave:
\nShields is a bundle of controls (trackers/ads, cookies, fingerprinting\ndefenses, HTTPS upgrades, referrer/query stripping, storage cleanup), so\nturning Shields off for a broken site is a big privacy downgrade for that\nsite—not just “adblock off.”
\nBrave explicitly recommends validating fingerprinting defenses with realistic\ntests (new private window, restart browser, different profile, clear site\nstorage) and expects the fingerprint to change across those boundaries.
\nExtension bloat will break Brave’s privacy and security story: each extension\nincreases attack surface and usually has broad privileges, while Brave’s core\npitch is that you can get most of the privacy wins without third-party code in\nyour browser process
\nDrawbacks worth mentioning:
\nBrave is still Chromium/Blink, so using it doesn’t help with engine diversity;\nif Gecko dies, the web becomes even more “whatever Chromium implements,” which\nis a long-term ecosystem risk.
\nBrave ships a lot (Rewards, Wallet, VPN upsells, Leo/AI features depending on\nbuild/channel), and every extra subsystem is more UI complexity and\npotentially more bugs/attack surface than some browsers.
\nBrave’s model assumes the browser does most privacy work; piling on extensions\nincreases privileged code, fingerprint uniqueness, and the chance of a\nmalicious/compromised extension.
\nFarbling and API defenses reduce stability/linkability, but sophisticated\ntrackers can still correlate behavior, logins, IP ranges, and high-level\npatterns—so “I enabled anti-fingerprinting” shouldn’t be read as “I can’t be\ntracked.”
\nBrave’s built-in ad system (Rewards) is opt-in, but Brave also promotes\nfeatures like Rewards and can show sponsored content (e.g., sponsored new-tab\nimages) unless you disable/hide it
\nFirefox is kind of its own thing: it runs on Gecko, not on Chromium or WebKit,\nso it’s one of the only mainstream browsers that isn’t just another Chrome fork.\nThat uniqueness matters if you care about engine diversity and not having the\nentire web effectively dictated by a single vendor. It’s also very tweakable, so\nif you’re willing to flip some prefs and add a couple of key extensions, you can\nturn it into a solid privacy‑focused daily driver without giving up a\nnon‑Chromium stack.
\nFirefox will usually get security fixes sooner than any fork, and some forks lag\nbehind on patching, which can leave known vulnerabilities exploitable for\nlonger. If you use Firefox’s built‑in Enhanced Tracking Protection (ETP), Resist\nFingerprinting (RFP), and hardening templates like ghacks or Arkenfox together\nwith uBlock Origin configured for dynamic filtering, you can replicate what used\nto require a pile of separate extensions.
\nFirefox does implement Site Isolation via\nProject Fission, but it’s newer and\nhistorically less mature than Chromium’s site‑per‑process model, and it may not\nbe enabled everywhere by default. To check that it is active, go to\nabout:config and ensure both fission.autostart and gfx.webrender.all are\nset to true.
With uBlock Origin you can disable JavaScript per‑site (similar to NoScript),\nenable a bunch of high‑quality blocklists, and selectively relax rules when a\ntrusted site breaks. To turn on Enhanced Tracking Protection and fingerprinting\nprotections in the UI, go to Settings -> Privacy & Security ->\nEnhanced Tracking Protection -> Custom; if that causes breakage on a\nparticular website, click the shield icon in the URL bar and disable protections\njust for that site.
Once you select Custom, you’ll see that among the options is to block\nKnown fingerprinters as well as Suspected fingerprinters. The “Known\nFingerprinters” protection works by blocking scripts listed in\nDisconnect’s fingerprinting list\nFor most users they suggest using the above FPP to avoid breakage. To go further\nand enable RFP, go to about:config and set privacy.resistFingerprinting to\ntrue.
about:config, set\nfission.autostart, and gfx.webrender.all prefs to true.(It’s disabled\nby default on android).Entropy: in this\ncontext, is a measure of how much unique information a specific browser\nfeature contributes to your fingerprint. It’s often quantified in bits of\nentropy, where higher bits mean more uniqueness (i.e., easier to identify\nyou).
\nOrigin: Web\ncontent’s origin is defined by the scheme (protocol), hostname (domain),\nand port of the URL used to access it. Two objects have the same origin only\nwhen the scheme, hostname, and port all match.
\nSame-origin policy:\nis a critical security mechanism that restricts how a document or script\nloaded by one origin can interact with a resource from another origin. It\nhelps isolate potentially malicious documents, reducing possible attack\nvectors.
\nFirefox Site-Isolation.\nFirefox does provide site-isolation as well.
\nLibreWolf is an open-source fork of Firefox with a strong focus on privacy,\nsecurity, and user freedom. LibreWolf enables always HTTPS, includes\nuBlockOrigin, and only includes privacy focused search engines by default.
\nExample LibreWolf config implementing many of the STIG recommendations:
\n# librewolf.nix\n{pkgs, lib, config, ...}: let\n cfg = config.custom.librewolf;\nin {\n options.custom.librewolf = {\n enable = lib.mkOption {\n type = lib.types.bool;\n default = true;\n description = \"Enable the LibreWolf Module\";\n };\n };\n\n config = lib.mkIf cfg.enable {\n programs.librewolf = {\n enable = true;\n policies = {\n # A bit annoying\n DontCheckDefaultBrowser = true;\n # Pocket is insecure according to DoD\n DisablePocket = true;\n # No imperative updates\n DisableAppUpdate = true;\n };\n settings = {\n # // SV-16925 - DTBF030\n \"security.enable_tls\" = true;\n # // SV-16925 - DTBF030\n \"security.tls.version.min\" = 2;\n # // SV-16925 - DTBF030\n \"security.tls.version.max\" = 4;\n\n # // SV-111841 - DTBF210\n \"privacy.trackingprotection.fingerprinting.enabled\" = true;\n\n # // V-252881 - Retaining Data Upon Shutdown\n \"browser.sessionstore.privacy_level\" = 0;\n\n # // SV-251573 - Customizing the New Tab Page\n \"browser.newtabpage.activity-stream.enabled\" = false;\n \"browser.newtabpage.activity-stream.feeds.section.topstories\" = false;\n \"browser.newtabpage.activity-stream.showSponsored\" = false;\n \"browser.newtabpage.activity-stream.feeds.snippets\" = false;\n\n # // V-251580 - Disabling Feedback Reporting\n \"browser.chrome.toolbar_tips\" = false;\n \"browser.selfsupport.url\" = \"\";\n \"extensions.abuseReport.enabled\" = false;\n \"extensions.abuseReport.url\" = \"\";\n\n # // V-251558 - Controlling Data Submission\n \"datareporting.policy.dataSubmissionEnabled\" = false;\n \"datareporting.healthreport.uploadEnabled\" = false;\n \"datareporting.policy.firstRunURL\" = \"\";\n \"datareporting.policy.notifications.firstRunURL\" = \"\";\n \"datareporting.policy.requiredURL\" = \"\";\n\n # // V-252909 - Disabling Firefox Studies\n \"app.shield.optoutstudies.enabled\" = false;\n \"app.normandy.enabled\" = false;\n \"app.normandy.api_url\" = \"\";\n\n # // V-252908 - Disabling Pocket\n \"extensions.pocket.enabled\" = false;\n\n # // V-251555 - Preventing Improper Script Execution\n \"dom.disable_window_flip\" = true;\n\n # // V-251554 - Restricting Window Movement and Resizing\n \"dom.disable_window_move_resize\" = true;\n\n # // V-251551 - Disabling Form Fill Assistance\n \"browser.formfill.enable\" = false;\n\n # // V-251550 - Blocking Unauthorized MIME Types\n \"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\";\n };\n };\n xdg.desktopEntries.librewolf = {\n name = \"LibreWolf\";\n exec = \"${pkgs.librewolf}/bin/librewolf\";\n };\n xdg.mimeApps = {\n enable = true;\n defaultApplications = {\n \"text/html\" = \"librewolf.desktop\";\n \"x-scheme-handler/http\" = \"librewolf.desktop\";\n \"x-scheme-handler/https\" = \"librewolf.desktop\";\n \"x-scheme-handler/about\" = \"librewolf.desktop\";\n \"x-scheme-handler/unknown\" = \"librewolf.desktop\";\n };\n };\n };\n}\nAnd enable it in your home.nix or equivalent with:
# home.nix\ncustom.librewolf.enable = true;\nThe 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\naccounts.firefox and\nturn off “Allow Mozilla accounts to send technical and interaction data to\nMozilla”. Also set 2-fa in\nSecurity Settings
\nI always set Max Protection for DNS over HTTPS and personally set a custom\nresolver to https://dns.quad9.net/dns-query
{\n pkgs,\n lib,\n config,\n ...\n}: let\n cfg = config.custom.librewolf;\nin {\n options.custom.librewolf = {\n enable = lib.mkOption {\n type = lib.types.bool;\n default = true;\n description = \"Enable the LibreWolf Module\";\n };\n };\n\n config = lib.mkIf cfg.enable {\n programs.librewolf = {\n enable = true;\n policies = {\n DontCheckDefaultBrowser = true;\n DisablePocket = true;\n DisableAppUpdate = true;\n };\n profiles.my-default = {\n isDefault = true;\n name = \"Default Profile\";\n extraConfig = ''\n ${builtins.readFile ./user.js}\n \"general.autoScroll\" = true;\n \"sidebar.verticalTabs\" = true;\n '';\n\n settings = {\n };\n };\n };\n xdg.desktopEntries.librewolf = {\n name = \"LibreWolf\";\n exec = \"${pkgs.librewolf}/bin/librewolf\";\n };\n xdg.mimeApps = {\n enable = true;\n defaultApplications = {\n \"text/html\" = \"librewolf.desktop\";\n \"x-scheme-handler/http\" = \"librewolf.desktop\";\n \"x-scheme-handler/https\" = \"librewolf.desktop\";\n \"x-scheme-handler/about\" = \"librewolf.desktop\";\n \"x-scheme-handler/unknown\" = \"librewolf.desktop\";\n };\n };\n };\n}\nDownload the\nArkenfox user.js and\nreview it making sure that you agree with the settings. If you do, place it in\nthe same directory as your librewolf.nix.
Read the Arkenfox Wiki
\nThe user.js is full of comments and information, read it and adjust it for\nyour needs. The following enables RFP fingerprint protection:
***/ user.js ***/\nuser_pref(\"privacy.resistFingerprinting\", true); // [FF41+]\nuser_pref(\"privacy.resistFingerprinting.pbmode\", true); // [FF114+]\nAs you learn more, you can get more strict if you so choose.
\nRebuild, launch LibreWolf, and check your ~/.librewolf/my-default/user.js. It\nshould match the Arkenfox settings. Initially, only the user.js will be\nlisted, as you run LibreWolf other profile files and folders are created\ndynamically.
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\nArkenfox changes, do they match?
The user.js is read in order, if there are 2 of the same setting, the last\none will be applied. Adding overrides to the settings attribute above places the\nchanges at the beginning of the user.js which isn’t what we want. Placing\nthem after the ${builtins.readFile ./user.js} in extraConfig amends them to\nthe end of the user.js allowing us to override the defaults.
The process is the same with Firefox but since Arkenfox strongly recommends\nUblock Origin and it is built into LibreWolf it makes sense to use the browser\nwith the stronger defaults.
\n\n\n❗ NOTE: There is a home-manager module called
\narkenfox-nixosthat is\nsupposed to make updates easier but IMO the documentation leaves you guessing\nhow to use it. As updates come in to Firefox/LibreWolf some of the settings\nbecome unnecessary so it’s important to keep an eye on both Firefox and\nArkenfox updates. Which both have RSS feeds that will alert you upon changes.
I personally use Feeder as my open-source RSS feed reader,\navailable in most app stores including F-Droid. It is listed on\nPrivacyTools.
\n\nStartpage: Advertised as the world’s most private search engine. “Startpage\ndelivers Google search results via their proprietary personal data protection\ntechnology.”
\nTo add Startpage as a search engine, add\nhttps://www.startpage.com/sp/search?query=%s.
SearXNG an open-source, privacy-respecting metasearch engine that aggregates\nresults from various search services, such as Google, DuckDuckGo, etc. without\ntracking you or profiling your searches. You can add SearXNG to firefox by going\nto about:preferences#search and at the bottom click Add, URL will be\nhttps://searx.be/search?q=%s.
\n\n❗️ NOTE: SearXNGs google results are not working as of 11-17-25 and haven’t\nfor a while now leading to bad results being returned for most instances. It’s\nmy understanding this is because Google is actively blocking automated\nrequests from SearXNG. Devs sometimes publish patches or workarounds, but\nthese are quickly blocked when Google changes their back-end.
\n
\n\n❗️ NOTE: The above searx is the default and doesn’t give many relevant\nresults. To get relevant results find a\npublic instance with a good rating from your area and\nadd the
\nsearch?q=%sto the end of it. For example, I’m using\nhttps://priv.au/search?q=%s.
Searx is a bit different, you can choose which search engine you want for your\ncurrent search with !ddg search term to use duckduckgo for example.
\n\n❗ NOTE: Tor is not the most secure browser, anonymity and security can\noften be at odds with each other. Having the exact same browser as many other\npeople isn’t the best security practice, but it is great for anonymity. Tor is\nalso based on Firefox Esr, which only receives patches for vulnerabilities\nconsidered Critical or High which can be taken advantage of.
\n
Tor is a modified version of Firefox specifically designed for use with Tor.
\nTor routes your internet traffic through a global volunteer-operated network,\nmasking your IP address and activities from local observers, ISPs, websites, and\nsurveillance systems. This helps you protect personal information and maintain\nanonymity when browsing, communicating, or using online services.
\nAdding browser plugins to Tor can de-anonymize you, don’t do it. Tor is already\nbuilt with the necessary plugins and privacy protecting rules, so adding more is\nunnecessary and actually dangerous for your anonymity.
\nA Tor exit node can easily see your traffic, and if you’re not using HTTPS then\nit may be able to modify that traffic. Only use HTTPS when browsing the clear\nnet with Tor, this doesn’t apply to onion services (.onion) as the traffic\nstays inside the Tor network all the way to the destination.
You can visit both the clear web and .onion sites on Tor. Whenever possible\nyou should utilize Onion Services (.onion addresses) so communications and web\nbrowsing stay within the Tor network. .onion URLS form a tunnel that is\nend-to-end encrypted using a random rendezvous point and incorporating\nperfect forward secrecy (PFS).
Bridges are only necessary in countries that don’t allow people to use Tor.\nUsing Bridges when they aren’t needed takes resources away from people in\noppressive regimes that need, only use them if necessary. Read the guides, and\nuse Tails OS, or Whonix when it really matters.
\n\nYou will see a lot of conflicting information about using Tor with a VPN. If you\nare in an area that blocks access to Tor or it is dangerous to use Tor, by all\nmeans use a trusted VPN.
\nLearn about Tor
\nI recommend starting with\nPrivacy Guides In Praise of Tor\nand then reading their\nTor Overview they\nhave been the most informative resources I’ve come across yet.
\nThe Electronic Frontier Foundation sponsors and helps fund Tor and so does the\nUnited States Government.
\nIf you are fortunate to live outside of oppressive regimes with extreme\ncensorship, using Tor for every day, mundane activities is likely safe and won’t\nput you on any harmful “list.” Even if it did, you’d be in good company—these\nlists mostly contain great people working tirelessly to defend human rights and\nonline privacy worldwide.
\nBy using Tor regularly for ordinary browsing, you help strengthen the network,\nmaking it more robust and anonymous for everyone. This collective support makes\nstaying private easier for activists, journalists, and anyone facing online\nsurveillance or censorship. The writer of the PrivacyGuides article mentions\nusing Tor when he needs to access Google Maps to protect his privacy
\nSo, consider embracing Tor not only for sensitive browsing but also for daily\nroutine tasks. Every user adds valuable noise to the network, helping protect\nprivacy and freedom for all.
\nTor is at risk, and needs our help. Despite its strength and history, Tor\nisn’t safe from the same attacks oppressive regimes and misinformed legislators\ndirect at encryption and many other privacy-enhancing\ntechnologies.–How to Support Tor
\nRather than try to tweak a browser into fingerprinting submission, I recommend\nusing either Tor or Mullvad-Browser when fingerprintability is the highest\nissue. Both Tor and Mullvad-Browser were designed specifically for this purpose\nand you likely won’t get as much out of tweaking another browser.
\nMullvad-Browser is free and open-source and was developed by the Tor Project in\ncollaboration with Mullvad VPN.(Another Firefox Derivative). It is also the top\nrecommended browser from PrivacyGuides.
\nIt is the Tor Browser without the Tor Network, allowing you to use the privacy\nfeatures Tor created along with a VPN if you so choose.
\npkgs.mullvad-browserProblem: Browsers leak data via .cache and .config.
Pro Tip: Even if you use a persistent home directory, you should mount your\n~/.cache folder to tmpfs.
Performance: Browsers perform thousands of small read/writes to the cache.\nIn-memory storage is significantly faster.
\nDisk Health: It prevents “SSD wear” from constant caching of temporary web\nassets.
\nForensic Hygiene: It ensures that volatile “junk” like images, scripts,\nand stylesheets never touches your physical platter.
\n\n\nNote: This will not wipe your browser session (tabs, cookies,\nhistory), as those are stored in
\n~/.config. If you want a truly “amnesic”\nbrowsing session that wipes everything on reboot, you must also mount your\nbrowser’s profile directory (e.g.,~/.mozillaor~/.config/BraveSoftware)\ntotmpfs.
fileSystems.\"/home/youruser/.cache\" = {\n device = \"none\";\n fsType = \"tmpfs\";\n options = [ \"size=4G\" \"mode=777\" ];\n};\nEnsure it was applied with:
\nfindmnt /home/youruser/.cache\nYou can apply the same tmpfs logic to your config folder. Warning: This\nwill wipe your settings, extensions, and history every reboot.
Manual tmpfs mounts in configuration.nix are powerful because they happen at\nthe system level, but they require explicit ownership (uid/gid) to work with\nuser-level applications.
fileSystems.\"/home/youruser/.config/BraveSoftware\" = {\n device = \"none\";\n fsType = \"tmpfs\";\n options = [\n \"size=4G\"\n \"mode=700\" # Use 700 for privacy\n \"noatime\"\n # Replace `1000` with the output of `id -u`\n \"uid=1000\"\n # Replace `100` with output of `id -g`\n \"gid=100\"\n ];\n};\nHow to find your UID/GID
\nid -u && id -g\nReplace the above uid=, and gid= values with the output of the above\ncommand.
If you followed the above “Nix way” of Amnesic cache, the following script is\nunnecessary, I’m leaving it here for now for those that are interested in\nchanging their machine-id imperatively.
\nThe following example is adapted from\nFirejail All About Tor\nsection, adapted for NixOS.
\nSave the following script as cleanup.sh, change Your-User to your username:
#!/bin/sh -e\nUSER=\"Your-User\"\nHOME_DIR=\"/home/$USER\"\n# clear user cache directly as root\nsudo -u \"$USER\" rm -fr \"$HOME_DIR/.cache\"\n# generate a new machine-id\nrm -f /var/lib/machine-id\ndbus-uuidgen > /var/lib/machine-id\ncp /var/lib/machine-id /etc/machine-id\nchmod 444 /etc/machine-id\nexit 0\nThe ~/.cache directory is where most programs store runtime information:\nwebpages you visited, torrent trackers you connected to, and deleted emails.\nIt’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\n# Output\n0b46feb27a20469da0ee62baaeb51c5c\nls ~/.cache\nchmod +x cleanup.sh\nsudo ./cleanup.sh\nRecheck your machine-id and ~/.cache directories, you should have a newly\ngenerated machine-id and minimal files in the ~/.cache directory. The\nFirejail example shows a systemd unit that runs the above script at every\nshutdown but that may be overkill, I suggest running it occasionally to make it\nharder for sites to link your machine-id to you.
Privacy protection doesn’t need to be perfect to make a difference. The best\nprotection against tracking and fingerprinting available is to use Tor. Many\nadd-ons are redundant, do some research and avoid using an add-on for something\nthat can be accomplished with built-in settings.
\n\nThere are more hardening parameters that can be set but this should be a good\nstarting point for a hardened version of LibreWolf. When testing with Cover your\ntracks, customized LibreWolf tested as having stronger tracking protection than\ndefault Mullvad-Browser and NoScript significantly cuts down the data available\nfor fingerprinting by disabling JavaScript.
\nA VPN (Virtual Private Network) encrypts your Internet connection and routes\nyour traffic through a VPN provider’s servers, masking your IP address from\nlocal network observers, ISPs, and websites. Using a VPN can prevent your ISP or\nlocal Wi-Fi owner from tracking what sites you visit (they only see a connection\nto the VPN), and can help circumvent some regional restrictions or filtering.
\nHowever, VPNs simply shift your trust: Instead of your ISP seeing your activity,\nyour VPN provider can, so you must trust their privacy policies and\ninfrastructure. Quality and privacy protections vary widely from one VPN company\nto another.
\nI see over and over again that Mullvad VPN is the best, I am in no way\naffiliated with them this is just what I hear. They allow you to pay with cash\ncompletely anonymously and keep very minimal metadata. Metadata is a big deal,\nthe US gov has admitted to killing people based solely on their metadata.
\nYour ISP almost certainly does sketchy stuff with your data, personally I would\nrather trust a company like Mullvad whose whole reputation is based on their\ntrustworthiness, transparency, and data protection.
\nYou can use a VPN with Tor, but it’s not recommended by the Tor Project unless\nyou’re an advanced user who knows how to configure both in a way that doesn’t\ncompromise your privacy.
\nPopular VPNs on NixOS
\nMullvad VPN Mullvad VPN uses\nWireGuard under the hood and only works if systemd-resolvd is enabled.
WireGuard VPN, WireGuard is a\nprotocol, but also a VPN provider on NixOS.
\nOpenVPN, OpenVPN is both a protocol and\nfull-featured VPN provider on NixOS.
\n![\"JJ](\"https://saylesss88.github.io/../images/jujutsu.png\")
⚠️ Security Reminder: Never commit secrets (passwords, API keys, tokens,\netc.) in plain text to your Git repository. If you plan to publish your NixOS\nconfiguration, always use a secrets management tool like sops-nix or agenix\nto keep sensitive data safe. See the\nSops-Nix Guide\nfor details.
Jujutsu (jj) is a modern, Git-compatible version control system designed to\nsimplify and improve the developer experience. It offers a new approach to\ndistributed version control, focusing on a more intuitive workflow, powerful\nundo capabilities, and a branchless model that reduces common pitfalls of Git.
\nRecommended resources:
\nSteve’s Jujutsu Tutorial\n(most up to date). Steve does an excellent job explaining the ins and outs of\nJujutsu.
\nOfficial:
\njj help -k tutorial\nEvery time you run a jj command, it examines the working copy and takes a\nsnapshot.
Command help:
\njj <command> --help\njj git init --help\njj git push --help\nIn JJ your working copy is always a real commit. Any changes you make are\nautomatically recorded in this working commit. The working copy is always\n(@) 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\ngit add or git commit for every change. Modifications are always tracked\nin the current commit.
JJ does not have the concept of a “current branch.” Instead, use bookmarks,\nwhich are named pointers to specific commits.
\nBookmarks do not move automatically. Commands like jj new and jj commit\nmove the working copy, but the bookmark stays were it was. Use\njj bookmark move to move bookmarks. (e.g., jj bookmark move main). You can\nalso use jj bookmark set main -r @ to explicitly set the main bookmark to\npoint at the working copy commit.
Only commits referenced by bookmarks are pushed to remotes, preventing\naccidental sharing of unfinished work.
\nTo stop tracking a specific file, first add it to your .gitignore, then run\njj untrack <file>
JJ records every operation (commits, merges, rebases, etc.) in an operation\nlog. Inspect it with: jj op log
You can view and undo any previous operation, not just the most recent one,\nmaking it easy to recover from mistakes, a feature not present in Git’s core\nCLI.
\nConflicts happen when JJ can’t figure out how to merge different changes made to\nthe same file.
\nConflicts are stored inside commits, not just in the working directory. You\ncan resolve them at any time, not just during a merge or rebase.
\nConflict markers are inserted directly into files, and JJ can reconstruct the\nconflict state from these markers. You can resolve conflicts by editing the\nfiles or using jj resolve.
Revsets: JJ’s powerful query language for selecting sets of commits,\ninspired by Mercurial. For example, jj log -r \"author(alice) & file(*.py)\"\nlists all commits by Alice that touch Python files.
Filesets:JJ supports a functional language for selecting sets of files,\nallowing advanced file-based queries and operations.
\n| 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 |
If you haven’t taken the time to deep dive Git, it may be a good time to learn\nabout a new way of doing Version Control that is actually less complex and\neasier to mentally map out in my opinion.
\nJujutsu is a new front-end to Git, and it’s a new design for distributed version\ncontrol. –jj init
\nYou can use jujutsu (jj) with existing Git repositories with one command.\njj git init --colocate or jj git init --git-repo /path/to/git_repository.\nThe native repository format for jj is still a work in progress so people\ntypically use a git repository for backend.
Unlike git, jj has no index “staging area”. It treats the working copy as an\nactual commit. When you make changes to files, these changes are automatically\nrecorded to the working commit. There’s no need to explicitly stage changes\nbecause they are already part of the commit that represents your current working\nstate.
Simplified Workflow
\nCheck where you’re at, JJ doesn’t care about commits without descriptions but\nGit and GitHub do:
\n❯ jj st\nThe working copy has no changes.\nWorking copy (@) : n a8b19ca2 (empty) (no description set)\nParent commit (@-): k 8c487558 edit(jj): ui.color = always diff.format color-words\nWe can see that the Working copy is (empty) and has (no description set),\nlets give it a description:
❯ jj desc -m \"chore: nix flake update\"\nWorking copy (@) now at: n 5c36a33d (empty) chore: nix flake update\nParent commit (@-) : k 8c487558 edit(jj): ui.color = always diff.format color-words\nI ran nix flake update, let’s check our status:
❯ jj st\nWorking copy changes:\nM flake.lock\nWorking copy (@) : n d54ab019 chore: nix flake update\nParent commit (@-): k 8c487558 edit(jj): ui.color = always diff.format color-words\nnix flake update modified M our flake.lock. To\nfinalize this change we can run jj new.❯ jj new\nWorking copy (@) now at: v cad9d50b (empty) (no description set)\nParent commit (@-) : n d54ab019 chore: nix flake update\nNow, looking at the output of jj new above, we can see that the Working copy\nis empty and has no description set. If we want to push these changes to GitHub,\nwe have to point the main bookmark where the changes exist, the Parent commit\nin this case:
❯ jj bookmark set main -r @-\nMoved 1 bookmarks to n d54ab019 main* | chore: nix flake update\nmain*, the * indicates that our local main has changes that\nmain@origin does not have.Ok, our main bookmark is now pointing at our latest changes. We can now run\njj git push to push them to the remote and make them a part of the permanent\nrecord:
❯ jj git push\nChanges to push to origin:\n Move forward bookmark main from 3956b1386d0a to d54ab0197bef\ngit: Enumerating objects: 14, done.\ngit: Counting objects: 100% (14/14), done.\ngit: Delta compression using up to 16 threads\ngit: Compressing objects: 100% (10/10), done.\ngit: Writing objects: 100% (10/10), 1.52 KiB | 520.00 KiB/s, done.\ngit: Total 10 (delta 7), reused 0 (delta 0), pack-reused 0 (from 0)\nremote: Resolving deltas: 100% (7/7), completed with 4 local objects.\nSuccess! Let’s check out our status again:
\n❯ jj st\nThe working copy has no changes.\nWorking copy (@) : v cad9d50b (empty) (no description set)\nParent commit (@-): n d54ab019 main | chore: nix flake update\nmain* is now just main, indicating our local and remotes are\nin sync!Let’s check out the log:
\n❯ jj log\n@ v sayls8@proton.me 2026-03-22 12:35:34 5835b760\n│ (no description set)\n◆ n sayls8@proton.me 2026-03-22 12:26:20 main d54ab019\n│ chore: nix flake update\n~\n◆ indicates that change n is now immutable after the push. Since it is\nnow immutable, jj automatically creates a new change on top of main and\nmoves the working copy to it.This is the hardest part for most people to grasp so let’s try another example\nwhere this time we push changes from the working copy.
\nI’ll add a simple README.md to our flake root:
❯ touch README.md\n\n\n❯ jj st\nWorking copy changes:\nA README.md\nWorking copy (@) : v 5835b760 (no description set)\nParent commit (@-): n d54ab019 main | chore: nix flake update\nLet’s give the change a description. Remember that jj commands default to the\nworking copy, so jj desc is the same is jj desc -r @
❯ jj desc -m \"chore: add README\"\nWorking copy (@) now at: v cdbb489f chore: add README\nParent commit (@-) : n d54ab019 main | chore: nix flake update\nNow rather than finalizing the current change with jj new, we will just point\nthe main bookmark at the working copy @ and then push.
❯ jj bookmark set main -r @\nMoved 1 bookmarks to v cdbb489f main* | chore: add README\n\n flake HEAD [!]\n❯ jj git push\nChanges to push to origin:\n Move forward bookmark main from d54ab0197bef to cdbb489fecc0\n git: Enumerating objects: 4, done.\n git: Counting objects: 100% (4/4), done.\n git: Delta compression using up to 16 threads\n git: Compressing objects: 100% (2/2), done.\n git: Writing objects: 100% (3/3), 332 bytes | 332.00 KiB/s, done.\n git: Total 3 (delta 1), reused 0 (delta 0), pack-reused 0 (from 0)\n remote: Resolving deltas: 100% (1/1), completed with 1 local object.\n Warning: The working-copy commit in workspace 'default' became immutable, so a new commit has been created on top of it.\n Working copy (@) now at: s 51306e16 (empty) (no description set)\n Parent commit (@-) : v cdbb489f main | chore: add README\nWith jujutsu, most commands allow you to pass -r/--revision
@ is a revset for “whichever commit the working copy reflects”. Think of @\nas where you are currently making changes.
Every time you run a jj command, it examines the working copy (the files on\ndisk) and takes a snapshot. –Steves JJ Tutorial
Let’s version control an existing nix development environment.
\ncd projects/rust\n\n❯ ls\n flake.lock flake.nix\n\njj git init --colocate\nInitialized repo in \".\"\nHint: Running `git clean -xdf` will remove `.jj/`!\n❯ jj log\n@ t sayls8@proton.me 2026-03-15 08:49:21 e8fd7ee0\n│ (no description set)\n◆ z root() 00000000\nLet’s give this change a description:
\n jj desc -m \"Initial commit of dev environment\"\nWorking copy (@) now at: t d671f27c Initial commit of dev environment\nParent commit (@-) : z 00000000 (empty) (no description set)\n\n❯ jj log\n# The change ID stays the same, but the commit ID changes\n@ t sayls8@proton.me 2026-03-15 09:04:17 d671f27c\n│ Initial commit of dev environment\n◆ z root() 00000000\nOk, I’m done with that change. Let’s start a new one, based off of t:
jj new\nWorking copy (@) now at: q a3f5afe8 (empty) (no description set)\nParent commit (@-) : t d671f27c Initial commit of dev environment\n\njj log\n@ q sayls8@proton.me 2026-03-15 09:10:46 a3f5afe8\n│ (empty) (no description set)\n○ t sayls8@proton.me 2026-03-15 09:04:17 d671f27c\n│ Initial commit of dev environment\n◆ z root() 00000000\nSince the repo wasn’t an existing git repo there are no existing branches\n(bookmarks). To share our work we’ll want to create a branch:
\nAbove is a repo that was just created with jj git init --colocate. Notice that\nthere is already 2 changes with change IDs t & z and 2 commits with\nidentifiers e8fd7ee0 & 00000000.
Every jj repo has a root commit with zzzzzzzz 00000000 identifiers.\nThe diamond ◆` represents an immutable, protected revision. This is the\nfoundation of the repo. Jujutsu created a second change based on top of the\nempty root commit.
The working copy in Jujutsu is an actual commit that represents the\ncurrent state of the files you’re working on. Unlike Git, where the working copy\nis separate from commits and changes must be explicitly staged and committed, in\nJJ the working copy is a live commit that automatically records changes as you\nmodify files.
\nAdding or removing files in the working copy implicitly tracks or untracks them\nwithout needing explicit commands like git add
The working copy commit acts as a snapshot of your current workspace. When you\nrun commands, Jujutsu first syncs the filesystem changes into this commit, then\nperforms the requested operation, and finally updates the working copy if needed
\nTo finalize your current changes and start a new set of changes, you use the\njj new command, which creates a new working-copy commit on top of the current\none. This replaces the traditional Git workflow of staging and committing\nchanges separately.
Conflicts in the working copy are represented by inserting conflict markers\ndirectly into the files. Jujutsu tracks the conflicting parts and can\nreconstruct the conflict state from these markers. You resolve conflicts by\nediting these markers and then committing the resolution in the working copy
\ngit add ., running git commit -m \"commit message\" because it’s already\ndone for you. This is handy with flakes by preventing a “dirty working tree”\nand can instantly be rebuilt after making a change.For lazygit fans, Nixpkgs has lazyjj. I’ve seen that it’s recommended to\nuse jj with meld. I’ll share my jj.nix here for an example:
I got a lot of the aliases and such from the\nzerowidth post, this has\nbeen a game changer:
\n{\n lib,\n config,\n pkgs,\n # userVars ? {},\n #\n #\n #\n ...\n}: let\n cfg = config.custom.jj;\nin {\n options.custom.jj = {\n enable = lib.mkOption {\n type = lib.types.bool;\n default = true;\n description = \"Enable the Jujutsu (jj) module\";\n };\n\n userName = lib.mkOption {\n type = lib.types.nullOr lib.types.str;\n default = \"sayls8\";\n description = \"Jujutsu user name\";\n };\n\n userEmail = lib.mkOption {\n type = lib.types.nullOr lib.types.str;\n default = \"sayls8@proton.me\";\n description = \"Jujutsu user email\";\n };\n\n packages = lib.mkOption {\n type = lib.types.listOf lib.types.package;\n default = with pkgs; [lazyjj meld];\n description = \"Additional Jujutsu-related packages to install\";\n };\n\n settings = lib.mkOption {\n type = lib.types.attrs;\n default = {\n ui = {\n # default-command = \"log-recent\";\n default-command = [\"status\" \"--no-pager\"];\n diff-editor = \"gitpatch\";\n # diff-editor = [\"nvim\" \"-c\" \"DiffEditor\" \"$left\" \"$right\" \"$output\"];\n # diff-formatter = [\"meld\" \"$left\" \"$right\"];\n merge-editor = \":builtin\";\n conflict-marker-style = \"diff\";\n };\n git = {\n # remove the need for `--allow-new` when pushing new bookmarks\n auto-local-bookmark = true;\n push-new-bookmarks = true;\n };\n revset-aliases = {\n \"closest_bookmark(to)\" = \"heads(::to & bookmarks())\";\n \"immutable_heads()\" = \"builtin_immutable_heads() | remote_bookmarks()\";\n # The following command is incorrect, TODO\n # \"default()\" = \"coalesce(trunk(),root())::present(@) | ancestors(visible_heads() & recent(), 2)\";\n \"recent()\" = \"committer_date(after:'1 month ago')\";\n trunk = \"main@origin\";\n };\n template-aliases = {\n \"format_short_change_id(id)\" = \"id.shortest()\";\n };\n merge-tools.gitpatch = {\n program = \"sh\";\n edit-args = [\n \"-c\"\n ''\n set -eu\n rm -f \"$right/JJ-INSTRUCTIONS\"\n git -C \"$left\" init -q\n git -C \"$left\" add -A\n git -C \"$left\" commit -q -m baseline --allow-empty\n mv \"$left/.git\" \"$right\"\n git -C \"$right\" add --intent-to-add -A\n git -C \"$right\" add -p\n git -C \"$right\" diff-index --quiet --cached HEAD && { echo \"No changes done, aborting split.\"; exit 1; }\n git -C \"$right\" commit -q -m split\n git -C \"$right\" restore . # undo changes in modified files\n git -C \"$right\" reset . # undo --intent-to-add\n git -C \"$right\" clean -q -df # remove untracked files\n ''\n ];\n };\n aliases = {\n c = [\"commit\"];\n ci = [\"commit\" \"--interactive\"];\n e = [\"edit\"];\n i = [\"git\" \"init\" \"--colocate\"];\n tug = [\"bookmark\" \"move\" \"--from\" \"closest_bookmark(@-)\" \"--to\" \"@-\"];\n log-recent = [\"log\" \"-r\" \"default() & recent()\"];\n nb = [\"bookmark\" \"create\" \"-r\" \"@-\"]; # new bookmark\n upmain = [\"bookmark\" \"set\" \"main\"];\n squash-desc = [\"squash\" \"::@\" \"-d\" \"@\"];\n rebase-main = [\"rebase\" \"-d\" \"main\"];\n amend = [\"describe\" \"-m\"];\n pushall = [\"git\" \"push\" \"--all\"];\n push = [\"git\" \"push\" \"--allow-new\"];\n pull = [\"git\" \"fetch\"];\n dmain = [\"diff\" \"-r\" \"main\"];\n l = [\"log\" \"-T\" \"builtin_log_compact\"];\n lf = [\"log\" \"-r\" \"all()\"];\n r = [\"rebase\"];\n s = [\"squash\"];\n si = [\"squash\" \"--interactive\"];\n };\n revsets = {\n # log = \"main@origin\";\n # log = \"master@origin\";\n };\n };\n description = \"Jujutsu configuration settings\";\n };\n };\n\n config = lib.mkIf cfg.enable {\n home.packages = cfg.packages;\n\n programs.jujutsu = {\n enable = true;\n settings = lib.mergeAttrs cfg.settings {\n user = {\n name = cfg.userName;\n email = cfg.userEmail;\n };\n };\n };\n };\n}\nIn my home.nix I have this to enable it:
custom = {\n jj = {\n enable = true;\n userName = \"sayls8\";\n userEmail = \"sayls8@proton.me\";\n packages = \"\";\n };\n};\nThe custom.jj module allows me to override the username, email, packages, and\nwhether jj is enabled from a single, centralized place within my Nix\nconfiguration. 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\nwhich is common with jj since it automatically tracks everything. I can now run:
jj commit -i\nAnd an interactive diff will come up allowing you to choose what to include in\nthe current commit. This also works for jj split -i and jj squash -i.
Example, using jj commit -i:
![\"jj](\"https://saylesss88.github.io/../images/jj-gitpatch.png\")
You can also use the jj tug command to make pushing to a remote more\nstraightforward. Since JJ’s bookmarks don’t automatically move as they do with\nGit, you can use jj tug after you’ve made a few commits to move the bookmark\nthat is closest to the parent commit of your current position to your current\ncommit:
jj tug\njj git push\nThe tug alias works for both the squash and edit workflows. After running\njj tug, jj git push should work. If you get an error saying no bookmarks to\nmove, you can run jj new and then run jj tug, this happens when the bookmark\nis already at the parent commit.
# jj.nix\nmb = [\"bookmark\" \"set\" \"-r\" \"@\"];\nAnother option would be to run jj mb main before running jj git push in this\nsituation, but you will have to describe the commit first.
![\"jj](\"https://saylesss88.github.io/../images/jj2.png\")
I have run into a few issues, such as every flake command reloading every single\ninput every time. What I mean by this is what you see when you run a flake\ncommand for the first time, it adds all of your flakes inputs. I believe the\nfix for this is deleting and regenerating your flake.lock. The same thing can\nhappen when you move your flake from one location to another.
JJ doesn’t seem to automatically track completely new files, running\ngit add /file/path.nix enables JJ to start tracking the new file.
That said, I recommend doing just that after running something like\njj git init --colocate. Delete your flake.lock and run nix flake update,\nnix 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\nrebuilding changes nothing, this has been more rare but happens occasionally.
\nOne of the most fundamental differences between Jujutsu and Git is how pushing\nworks. If you’re coming from Git, it’s important to understand this shift so you\ndon’t get tripped up by “nothing happened” warnings or missing changes on your\nremote.
\nIn Git, you’re always “on” a branch (e.g., main).
When you make a commit, the branch pointer automatically moves forward.
\ngit push pushes the current branch’s new commits to the remote.
If you forget to switch branches, you might accidentally push to the wrong\nplace, but you rarely have to think about “moving” the branch pointer\nyourself.
\nThe JJ Push Model
\nJJ has no concept of a “currrent branch”
\nBookmarks do not move automatically. When you make a new commit, the\nbookmark (e.g., main) stays where it was. You must explicitly move it to\nyour 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\nisn’t pointed to by a bookmark, jj git push will do nothing and warn you.\nThis is to prevent accidental pushes and gives you more control over what gets\nshared.
Typical JJ Push Workflow
\njj st\nWorking copy changes:\nM README.md\nWorking copy (@) : mnkrokmt 7f0558f8 say hello and goodbye\nParent commit (@-): ywyvxrts 986d16f5 main | test3\n\nBeing more explicit about your commands ensures both you and jj know where\neverything should go. (i.e. jj desc @ -m explicitly describes @, the working\ncopy.) This will save you some headaches.
Our new change, the Working copy is now built off of main. The working copy\nwill always be (@).
Make some changes
\njj st\nWorking copy changes:\nA dev/flake.lock\nA dev/flake.nix\nWorking copy (@) : kxwrsmmu 42b011cd Add a devShell\nParent commit (@-): ywyvxrts 986d16f5 main | test3\nNow I’m done, and since we built this change on top of main the following\ncommand will tell jj we know what we want to push:
jj bookmark set main\njj git push\nIf you forget to move a bookmark, JJ will warn you and nothing will be pushed.\nThis is a safety feature, not a bug. That’s what the mb alias does, moves the\nbookmark to the working copy.
# home-manager alias (move bookmark)\nmb = [\"bookmark\" \"set\" \"-r\" \"@\"];\nIf you really have problems, jj git push --change @ explicitly pushes the\nworking copy.
This is a bit different than Git and takes some getting used to but you don’t\nneed to move the bookmark after every commit, just when you want to push. I know\nI’ve made the mistake of pushing to the wrong branch before this should prevent\nthat.
\nSay I have my configuration flake in the ~/flakes/ directory that is an\nexisting Git repository. To use JJ as the front-end I could do something like:
cd ~/flakes\njj git init --colocate\nDone importing changes from the underlying Git repo.\nSetting the revset alias `trunk()` to `main@origin`\nInitialized repo in \".\"\ntrunk() as the main development branch of your remote\nrepository. This is usually set to main@origin, but could be named something\nelse. This means that whenever you use trunk() in JJ commands, it will\nresolve to the latest commit on main@origin. This makes it easier to refer\nto the main branch in scripts and commands without hardcoding the branch name.Bookmarks in jj are named pointers to specific revisions, similar to\nbranches in Git. When you first run jj git init --colocate in a git repo, you\nwill likely get a Hint saying “Run the following command to keep local bookmarks\nupdated on future pulls”.:
jj bookmark list\ntrack main@origin\n\njj st\nThe working copy has no changes.\nWorking copy (@) : qzxomtxq 925eca75 (empty) (no description set)\nParent commit (@-): qnpnrklz bf291074 main | notes\nThis shows that running jj git init --colocate automatically started tracking\nmain 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\nWorking copy changes:\nM README.md\nWorking copy (@) : qzxomtxq b963dff0 (no description set)\nParent commit (@-): qnpnrklz bf291074 main | notes\nWe can see that the working copy now contains a modified file M README.md and\nhas no description set. Lets give it a description before pushing to github.
jj desc @ -m \"Added to README\"\njj bookmark set main -r @\nMoved 1 bookmarks to pxwnopqo 1e6e08a2 main* | Added to README\njj bookmark set main -r @ moves the main bookmark to the current revision\n(the working copy), which is the explicit, recommended way to update bookmarks\nin JJ. Without this step, your bookmark will continue to point at the old\ncommit, not your latest work. This is a major difference from Git.
And finally push to GitHub:
\njj git push\nChanges to push to origin:\n Move forward bookmark main from bf291074125e to e2a75e45237b\nremote: Resolving deltas: 100% (1/1), completed with 1 local object.\nWarning: The working-copy commit in workspace 'default' became immutable, so a new commit has been created on top of it.\nWorking copy (@) now at: pxwnopqo 8311444b (empty) (no description set)\nParent commit (@-) : qzxomtxq e2a75e45 main | Added to README\nOr to do this in a directory that isn’t already a git repo you can do\nsomething like:
\ncargo new hello-world --vcs=none\ncd hello-world\njj git init\nInitialized repo in \".\"\nOr for example, with Git if you wanted to move to a different branch before\nrunning nix flake update to see if it introduced errors before merging with\nyour main branch, you could do something like:
git checkout -b update-test\n\nnix flake update\n\nsudo nixos-rebuild test --flake .\nIf you’re satisfied you can merge:
\ngit checkout main\ngit add . # Stage the change\ngit commit -m \"update\"\ngit merge update-test\ngit branch -D update-test\nsudo nixos-rebuild switch --flake .\nWith JJ a similar workflow could be:
\njj st to see what you have:jj st\nThe working copy has no changes.\nWorking copy (@) : ttkstzzn 3f55c42c (empty) (no description set)\nParent commit (@-): wppknozq e3558ef5 main@origin | jj diff\nIf you don’t have a description set for the working copy set it now.
\njj desc @ -m \"enable vim\"\njj st\nThe working copy has no changes.\nWorking copy (@) : ttkstzzn 63fda123 (empty) enable vim\nParent commit (@-): wppknozq e3558ef5 main@origin | jj diff\nmain is\nimmutable, you can create your new change by working on top of the working\ncopy commit.Create a new change off of the working copy:
\njj new @\njj st\nWorking copy changes:\nM home/editors/vim.nix\nWorking copy (@) : qrsxltmt 494b5f18 (no description set)\nParent commit (@-): wytnnnto a07e775c (empty) enable vim\njj squash\nThe working copy has no changes.\nWorking copy (@) : tmlwppnu ba06bb99 (empty) (no description set)\nParent commit (@-): wytnnnto 52928ed9 enable vim\nThis moves your working copy changes into the new commit you just created.
\njj squash command\ncreated a new commit that you have to describe again:jj desc @ -m \"Enabled Vim\"\nWorking copy (@) : tmlwppnu 5c1569c3 (empty) Enabled Vim\nParent commit (@-): wytnnnto 52928ed9 enable vim\njj bookmark set wyt\njj git push --allow-new\nChanges to push to origin:\n Add bookmark wyt to 5c1569c35b22\nremote: Resolving deltas: 100% (4/4), completed with 4 local objects.\nremote:\nremote: Create a pull request for 'wyt' on GitHub by visiting:\nremote: https://github.com/sayls8/flake/pull/new/wyt\nremote:\nThis command does the following:
\nUploads your bookmark and the associated commit to the remote repository\n(e.g., GitHub).
\nIf the bookmark is new (not present on the remote), --allow-new tells JJ\nit’s okay to create it remotely.
After pushing, GitHub (or your code host) will usually suggest creating a pull\nrequest for your new branch/bookmark, allowing you or your collaborators to\nreview and merge the change into main.
\nMerging your Change into main
Option 1. Go to the URL suggested in the output, visit in this case:
\nhttps://github.com/sayls8/flake/pull/new/wyt\nClick Create PR
\nClick Merge PR if it shows it can merge cleanly.
\nOption 2.
\nmain (if not already there):jj bookmark set main\nmain:jj new tml wyt -m \"Merge: enable vim\"\nThis creates a new commit with both tml and wyt as parents, which is how JJ\nhandles merges (since jj merge depreciated). JJ merges are additive and\nhistory-preserving by design especially for folks used to Git’s fast-forward and\nsquash options.
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.\njj squash combines the current commit with its parent, effectively doing the\nsame thing in terms of history.
Merging: Git’s merge command is explicit. In jj, the concept is similar, but\nsince there’s no branch, you’re “merging” by moving your working commit to\ninclude these changes.
No need to delete branches: Since there are no branches in jj, there’s no\nequivalent to git branch -D to clean up. Instead commits that are no longer\nneeded can be “abandoned” with jj abandon if you want to clean up your\ncommit graph.
jj describe without a flag just opens $EDITOR where you can write your\ncommit message save and exit.
In git, we finish a set of changes to our code by committing, but in jj we\nstart new work by creating a change, and then make changes to our code. It’s\nmore useful to write an initial description of your intended changes, and then\nrefine 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\nhave noticed some issues here and there when using with NixOS. I’m hoping that\nas the project matures, it gets better on this front.
\nThis workflow is the most similar to Git and Git’s index.
\nThe workflow:
\nDescribe 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\n@ into the change we described in step 1. @ is where your working copy is\npositioned currently.
For example, let’s say we just ran jj git init --colocate in our configuration\nFlake directory making it a jj repo as well using git for backend.
cd flake\njj git init --colocate\njj log\n@ lnmmxwko sayls8@proton.me 2025-06-27 10:14:57 1eac6aa0\n│ (empty) (no description set)\n○ qnknltto sayls8@proton.me 2025-06-27 09:04:08 git_head() 5358483a\n│ (empty) jj\nThe above log output shows that running jj git init creates an empty working\ncommit (@) on top of the git_head()
jj desc -m \"Switch from nixVim to NVF\"\njj new # Create a new empty change\njj log\n@ nmnmznmm sayls8@proton.me 2025-06-27 10:16:30 52dd7ee0\n│ (empty) (no description set)\n○ lnmmxwko sayls8@proton.me 2025-06-27 10:16:24 git_head() 3e8f9f3a\n│ (empty) Switch from nixVim to NVF\n○ qnknltto sayls8@proton.me 2025-06-27 09:04:08 5358483a\n│ (empty) jj\nThe above log shows that running jj desc changes the current (@) commits\ndescription, and then jj new creates a new empty commit on top of it, moving\n(@) 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\ndescribed in the previous steps.
\nThe changes are automatically “staged” so theres no need to git add them, so\nwe just make the changes and squash them.
jj squash # Squash the commit into its parent commit (i.e., our named commit)\njj log\n@ zsxsolsq sayls8@proton.me 2025-06-27 10:18:01 2c35d83f\n│ (empty) (no description set)\n○ lnmmxwko sayls8@proton.me 2025-06-27 10:18:01 git_head() 485eaee9\n│ (empty) Switch from nixVim to NVF\nThis shows jj squashes effect, it merges the changes from the current (@)\ncommit into its parent. The (@) then moves to this modified parent, and a new\nempty commit is created on top, ready for the next set of changes.
sudo nixos-rebuild switch --flake .\nWe’re still in the nameless commit and can either continue working or run\njj desc -m \"\" again describing our new change, then jj new and jj squash\nit’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\ncurrently is and if it’s attached to a bookmark. It’s common for jj new to\ndetach the head, all you have to do is tell JJ which branch to attach to, then\npush:
jj st\nWorking copy changes:\nM hosts/magic/configuration.nix\nM hosts/magic/container.nix\nWorking copy (@) : youptvvn 988e6fc9 (no description set)\nParent commit (@-): qlwqromx 4bb754fa mdbook container\nThe above output means that the working copy has modifications (M) in two\nfiles. And these changes are not yet committed.
jj bookmark set main\njj git push\nThis workflow adds a few new commands jj edit, and jj next.
Here’s the workflow:
\nCreate a new change to work on the new feature with jj new
If everything works exactly as planned, we’re done.
\nIf we realize we want to break this big change up into multiple smaller ones,\nwe do it by making a new change before the current one, swapping to it, and\nmaking the necessary change.
\nLastly, we go back to the main change.
\nThe squash workflow leaves @ at an empty undescribed change, with this\nworkflow, @ 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\"\nsince our @ is already at an empty change, we’ll just describe it and get\nstarted:
For this example, lets say we want to revert back to nixVim:
\njj desc -m \"Switch from NVF to nixVim\"\njj log\n@ zsxsolsq sayls8@proton.me 2025-06-27 10:18:47 606abaa7\n│ (empty) Switch from NVF to nixVim\n○ lnmmxwko sayls8@proton.me 2025-06-27 10:18:01 git_head() 485eaee9\n│ (empty) Switch from nixVim to NVF\n○ qnknltto sayls8@proton.me 2025-06-27 09:04:08 5358483a\n│ (empty) jj\nAgain, this shows jj desc renaming the current empty @ commit.
We make the changes, and it’s pretty straightforward so we’re done, every change\nis automatically staged so we can just run sudo nixos-rebuild switch --flake .\nnow to apply the changes.
If we wanted to make more changes that aren’t described we can use jj new -B\nwhich is similar to git add -a.
jj new -B @ -m \"Adding LSP to nixVim\"\nRebased 1 descendant commits\nWorking copy (@) now at: lpnxxxpo bf929946 (empty) Adding LSP to nixVim\nParent commit (@-) : lnmmxwko 485eaee9 (empty) Switch from nixVim to NVF\nThe -B tells jj to create the new change before the current one and it\ncreates a rebase. We created a change before the one we’re on, it automatically\nrebased our original change. This operation will always succeed with jj, we\nwill have our working copy at the commit we’ve just inserted.
You can see below that @ moved down one commit:
jj log\n○ zsxsolsq sayls8@proton.me 2025-06-27 10:22:03 ad0713b6\n│ (empty) Switch from NVF to nixVim\n@ lpnxxxpo sayls8@proton.me 2025-06-27 10:22:03 bf929946\n│ (empty) Adding LSP to nixVim\n○ lnmmxwko sayls8@proton.me 2025-06-27 10:18:01 git_head() 485eaee9\n│ (empty) Switch from nixVim to NVF\n○ qnknltto sayls8@proton.me 2025-06-27 09:04:08 5358483a\n│ (empty) jj\n○ qnknltto sayls8@proton.me 2025-06-27 09:04:08 git_head()\nThe “Adding LSP to nixVim” commit is directly above “Switch from nixVim to NVF”\n(the old git_head())
The “Switch from NVF to nixVim” commit (which was your @ before jj new -B)\nis now above “Adding LSP to nixVim” in the log output, meaning “Adding LSP to\nnixVim” is its new parent.
@ has moved to “Adding LSP to nixVim”
jj log example output
JJ records every operation (commits, merges, rebases, etc.) in an operation log.\nYou can view and undo previous operations, making it easy to recover from\nmistakes, a feature not present in Git’s core CLI
\njj op log\n@ fbf6e626df22 jr@magic 15 minutes ago, lasted 9 milliseconds\n│ new empty commit\n│ args: jj new -B @ -m 'Adding LSP to nixVim'\n○ bde40b7c17cf jr@magic 19 minutes ago, lasted 8 milliseconds\n│ describe commit 2c35d83f75031dc582bf28b64d4af1c218177f90\n│ args: jj desc -m 'Switch from NVF to nixVim'\n○ 3a2bfe1c0b0a jr@magic 19 minutes ago, lasted 8 milliseconds\n│ squash commits into 3e8f9f3a6a58fef86906e16e9b4375afb43e73e3\n│ args: jj squash\n○ 80abcb58dcb6 jr@magic 21 minutes ago, lasted 8 milliseconds\n│ new empty commit\n│ args: jj new\n○ 8c80314cbcd7 jr@magic 21 minutes ago, lasted 8 milliseconds\n│ describe commit 1eac6aa0b88ba014785ee9c1c2ad6e2abc6206e9\n│ args: jj desc -m 'Switch from nixVim to NVF'\n○ 44b5789cb4d1 jr@magic 22 minutes ago, lasted 6 milliseconds\n│ track remote bookmark main@origin\n│ args: jj bookmark track main@origin\n○ dbefee04aa85 jr@magic 23 minutes ago, lasted 4 milliseconds\n│ import git head\n│ args: jj git init --git-repo .\njj op undo <operation-id>\n# or\njj op restore <operation-id>\nIn JJ, conflicts live inside commits and can be resolved at any time, not just\nduring a merge. This makes rebasing and history editing safer and more flexible
\nJJ treats conflicts as first-class citizens: conflicts can exist inside commits,\nnot just in the working directory. This means if a merge or rebase introduces a\nconflict, the conflicted state is saved in the commit itself, and you can\nresolve it at any time there’s no need to resolve conflicts immediately or use\n“--continue” commands as in Git
Here’s how it works:
\nWhen you check out or create a commit with conflicts, JJ materializes the\nconflicts as markers in your files (similar to Git’s conflict markers)
\nYou can resolve conflicts by editing the files to remove the markers, or by\nusing:
\njj resolve\nJJ includes a powerful query language for selecting commits. For example:
\njj log -r \"author(alice) & file(*.py)\"\nThis command lists all commits by Alice that touch Python files.
\nJujutsu supports a functional language for selecting a set of files. Expressions\nin this language are called “filesets” (the idea comes from Mercurial). The\nlanguage consists of file patterns, operators, and functions. –JJ Docs
\nJujutsu (jj) offers a streamlined, branchless, and undo-friendly approach to\nversion control, fully compatible with Git but designed to be easier to use and\nreason about. Its workflows, operation log, and conflict handling provide a\nsafer and more flexible environment for managing code changes, making it a\ncompelling alternative for both new and experienced developers.
\n![\"sp5\"](\"https://saylesss88.github.io/images/steampunk5.cleaned.png\")
Host secureblue = Fedora Atomic with SELinux enforcing, sVirt,\nSecure Boot, and hardened defaults.
Guest: NixOS in a VM → full declarative power, near zero risk to host.
\nIsolation: Mandatory Access Control (MAC) via SELinux + KVM + no direct\nhardware access.
\n\n\n\nNOTE: Secureblue enables the
\nhardened_mallocby default which causes\nproblems for many browsers and will cause screen flashing with Firefox and\nothers within the VM. See:
Download a secureblue image
\nUse Fedora Media Writer (Flatpak):
\nflatpak install flathub org.fedoraproject.MediaWriter\nFlash the secureblue image & enable Secure Boot in UEFI before install.\nThis is now possible with Fedora, when you boot into Fedora Media Writer (not\nVentoy or Rufus), you will be allowed to enroll the secure boot key with\nsecure boot pre-enabled.
\nOn first boot:
\nujust enroll-secureblue-secure-boot-key\nsecurebluePost-install hardening See:\npost-install
\nInstall virtualization stack:
\nujust install-libvirt-packages\nThe above command enables qemu, libvirt, & virt-manager with SELinux\nlabels.
Read the secureblue FAQ to learn the quirks of\nan atomic fedora image.
\nSecureblue recommends installing GUI apps with Flatpak, CLI apps with homebrew,\nand apps that require more system access to be layered with rpm-ostree. It\ntakes some getting used to but is very stable.
Easiest way to get a working configuration IMO:
\nDownload: NixOS Graphical ISO
\nOpen virt-manager -> File -> New Virtual Machine
Select ISO
\nCPU: host-passthrough (optional, for performance)
Do some research to find the ideal Memory and Storage for your system.
\nEnsure 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\n# Output\nsystem_u:system_r:svirt_t:s0:c383,c416 14793 ? 00:01:37 qemu-system-x86\nEnable LUKS
\nCreate an admin user
\nOptionally skip desktop -> install your own after first boot.
\nThe attack surface is reduced significantly when running NixOS within a hardened\nhosts VM. The VM operates on virtualized hardware, which is a powerful form of\nattack surface reduction.
\nDevices like your host’s Bluetooth adapter, Wi-Fi card, microphone, webcam, and\nUSB ports are not directly exposed to the guest operating system. The VM only\nsees virtual versions of these devices. If an exploit targets a vulnerability in\nthe Bluetooth stack within the VM, it compromises the VM environment, but it\ncannot typically reach and exploit the physical Bluetooth hardware on the host.
\nYou can also choose not to pass through certain devices, like Bluetooth or\nwebcam to the VM at all, effectively disabling that attack vector. Since your\nhost likely already has these hardened features you may not need the additional\nfunctionality within the VM.
\nIf something breaks, you have an option to rollback to the previous generation\nwith rpm-ostree rollback. The previous generation will be applied on next\nreboot. You can also just reboot and choose the previous generation through the\ngrub menu, this way it is temporary and will revert back on next reboot.
The host uses a classic defense-in-depth model: the hardened outer layer (the\nhost) is treated as the real security boundary, and it is designed to remain\nsafe even if the inner layer (the NixOS guest) is fully compromised.
\nOn the secureblue host, sVirt automatically applies SELinux labels to all\nVM-related processes and resources.
\nQEMU process confinement: The QEMU process that runs the NixOS VM runs\nunder a dedicated SELinux type, typically svirt_t. The host’s MAC policy\ntightly restricts what this process can access, so even a successful VM escape\nis still trapped inside a very limited sandbox rather than gaining normal host\nprivileges.
Disk image protection: VM disk images are labeled (for example,\nvirt_image_t), which prevents unrelated host processes from reading or\nmodifying them and keeps the VM’s storage isolated from the rest of the\nsystem.
KVM provides the hardware-assisted virtualization layer and forms a strong\nbarrier between the guest and the host kernel. On top of that, the secureblue\nhost is hardened with SELinux in enforcing mode, Secure Boot, a hardened kernel,\nand hardened_malloc by default. Together, these measures reduce the attack\nsurface and help ensure the integrity of the platform that is actually running\nthe VM.
\nThe host and guest are deliberately decoupled from a security perspective. The\nassumption is that the NixOS VM can be misconfigured, vulnerable, or even fully\ncompromised. If that happens, KVM plus the host MAC policy (SELinux + sVirt) are\nresponsible for containing the damage. In other words, the security boundary is\nnot the NixOS configuration inside the VM, but the hypervisor and the host’s\nmandatory access control rules that enforce strict isolation of the guest from\nthe host.
\nEven with a hardened host and MAC confinement, treating the NixOS VM as\n“untrusted but hardened” adds another independent safety layer. The goal is to\nminimize what an attacker can do inside the guest, even if they never manage a\nbreakout.
\nMinimize VM device exposure
\nUse snapshots aggressively: Take a snapshot right after a fresh install\nand initial configuration. That snapshot becomes your “known-good” state for\ntesting risky software or malware, so you can revert and wipe out any changes\nafterward.
\nAvoid unnecessary passthrough: Only pass through hardware (USB, GPU,\nnetwork interfaces, etc.) if the VM genuinely needs it. Every extra device is\nanother potential attack surface.
\nPrefer simple virtual devices: Use virtio and other paravirtualized\ndevices where possible, and avoid legacy or fully emulated devices unless\nthere is a specific need.
\nNetwork isolation for guests
\nKeep networks virtual and segmented: Favor isolated virtual networks,\nVLANs, or internal-only networks over bridged physical interfaces, so VMs\ncannot talk to the host or each other unless you explicitly design for it.
\nFilter traffic tightly: Use libvirt nwfilter, firewall rules\n(nftables/iptables/firewalld), and similar tools to restrict VM-to-VM and\nVM-to-external traffic, especially for services exposed on multiple guests.
\nBe cautious with IPv6: Full IPv6 inside the VM usually implies bridged\nnetworking, which connects the VM more directly to the host’s LAN. That\nimproves connectivity but reduces isolation, so enable it only if you truly\nneed it.
\nGuest-side hardening measures
\ngraphene-hardened or\ngraphene-hardened-light inside the guest improves memory safety for many\napplications:# configuration.nix\nenvironment.memoryAllocator.provider = \"graphene-hardened\";\n# OR for a more permissive and better performing allocator:\n# environment.memoryAllocator.provider = \"graphene-hardened-light\";\nSome software (notably certain browsers) can be finicky with hardened mallocs\nand may require rebuilding or alternatives; be prepared to switch to another\nbrowser or allocator profile when you hit incompatibilities.
\nFor deeper NixOS-specific hardening, see:\nhardening NixOS
\n\n\n⚠️ Warning: toolbx containers are integrated with the host system, don’t do\nthings you wouldn’t do on your host. Toolbx containers are not fully isolated\nenvironments like VMs.
\n
That said, they are a fast and convenient way to spin up a Nix development\nenvironment. Know the limitations and benefits, and when you need more\nisolation, just spin up a VM instead.
\nSecureblue enforces restrictive container image policies by default, blocking\nunsigned or unverified images from registries like GitHub Container Registry.\nThis requires explicit trust configuration for each container source.
\nujust set-container-userns on\nWithout this setting, containers will fail with OCI permission denied errors.
Allow the Nix-Toolbox Image
\n# For system-wide configuration (affects all users)\nrun0 podman image trust set -t accept ghcr.io/thrix/nix-toolbox\n\n# For user-specific configuration (recommended for development)\npodman image trust set -t accept ghcr.io/thrix/nix-toolbox\nThe -t accept flag allows images from this registry without requiring\nsignature verification.
# Check that the policy has been updated correctly:\npodman image trust show\nCreate the nix-toolbox container:
toolbox create --image ghcr.io/thrix/nix-toolbox:42\nYou will be prompted whether you want Home Manager installed or not as well.
\nEnter the toolbox:
\ntoolbox enter nix-toolbox-42\nYou can then use nix and home-manager to setup a fully declarative\ndev-environment.
\nSecureblue’s design and the underlying firmware safeguards also make certain\nfailures recoverable. On a mini PC, running a firmware update command resulted\nin a boot error (“Something went seriously wrong, MOK is full”) and a forced\nshutdown. Resetting NVRAM by moving the jumper on the motherboard briefly, then\nrestoring it to the original position, allowed the system to retrain and boot\nagain, after which the Secure Boot key could be re-enrolled and the system\nreturned to a known-good, secure state.
\nUsing secureblue as the host OS with NixOS in a VM has been surprisingly smooth\nfor day‑to‑day work. Performance has been more than adequate for editing,\ndevelopment, and browsing, and every issue so far has been fixable with\nrollbacks or small config changes—no “nuke and reinstall” moments required.
\nSoftware installation and workflows
\nFlatpak takes a bit of relearning if you are used to installing everything with\nfull root on a mutable distro. Tools like Flatseal help a lot: you can see\nexactly which permissions an app has, then selectively tighten them instead of\nblindly trusting defaults. On secureblue, running the\nujust flatpak-permissions-lockdown helper gives you a very strict baseline,\nthen you add back only what each app truly needs.
In practice, a hybrid approach has worked best. One editor runs as a Flatpak,\nand another is installed via rpm-ostree for tighter system integration and the\n“traditional” root behavior when needed. The same thing happened with yazi: to\nget the exact workflow wanted, it was easier to install it via rpm-ostree\nrather than poking so many holes in the Flatpak sandbox that most isolation\nbenefits disappeared.
Toolbx also fits into this nicely. Putting Homebrew and Flatpak inside a toolbox\nlets more config be shared while keeping the host image clean. The general\npattern on Silverblue/secureblue is: Flatpak for most GUI apps, toolbox (plus\nbrew or distro packages) for CLI tooling, and only a small number of host‑layer\nrpm-ostree installs when deep integration is really warranted.
One quirk worth knowing about: on secureblue, /home is a symlink to\n/var/home. Most tools don’t care, but a few development workflows get confused\nby the indirection. In those cases, pointing the tool directly at\n/var/home/username instead of /home/username usually clears things up.
Graphics and drivers in the NixOS VM
\nFor GPU and display, the safest approach has been to let secureblue own the\nhardware stack and keep the NixOS guest as simple as possible. Extra GPU drivers\nor compositor tweaks inside the VM tended to make things less stable, showing up\nas flicker, random freezes, or generally janky graphics because the guest was\neffectively fighting the host’s configuration. Sticking close to the defaults in\nthe VM has consistently produced smoother and more predictable graphics\nbehavior.
\nThe main issue I’ve had is with the dns-selector occasionally causing networking\nproblems. I configure global DNS with their ujust command and I’m assuming\nthat updates were incompatible with my DNS setup. Running ujust dns-selector\nand pressing 1 (Reset to defaults), and a reboot typically fix the connection\nand within a few days the global DNS will work again.
As we’ve seen from previous examples, the helix editor repository includes a few\n.nix files including a flake.nix. Their flake uses a lot of idiomatic Nix\ncode and advanced features. First I will break down their flake.nix and\ndefault.nix to understand why they do certain things. And finally, we will\nchange the build to “debug” mode demonstrating how easily you can modify the\nbehavior of a package defined within a Nix flake without changing the original\nsource code or the upstream flake directly.
![\"Helix](\"https://saylesss88.github.io/../images/helix.png\")
–git clone https://github.com/helix-editor/helix.git\ncd helix\nWhen you enter the helix directory, direnv is setup for you already. All you\nwould have to do is direnv allow and it will ask you a few questions then you\nare good to go. Looking at their .envrc it mentions “try to use flakes, if it\nfails use normal nix (i.e., shell.nix)”. If it’s successful you’ll see a long\nlist of environment variables displayed.
The Helix project’s flake.nix includes a devShells.default output,\nspecifically designed for development.
nix develop\nnix develop, Nix builds and drops you into a shell environment\nwith all the dependencies specified in devShells.default. This means you\ndon’t have to manually install or manage tools like Rust, Cargo, or Clang,\nit’s all handled declaratively through Nix.You can now build and run the project using its standard tooling:
\ncargo check\ncargo build\ncargo run\nSince you’re in a reproducible environment, you can confidently hack on the\nproject without worrying about your system setup. Try modifying some code in\nhelix and rebuilding with Cargo. The Nix shell ensures consistency for every\ncontributor or device you work on.
If you only want to run the compiled program without entering the shell, use the\nnix run command:
\nnix run\nThis builds and runs the default package defined by the flake. In the case of\nHelix, this launches the hx editor directly.
To just build the project and get the path to the output binary:
\nnix build\nYou’ll find the compiled binary under ./result/bin.
Because the project uses a flake, you can ensure full reproducibility by pinning\nthe inputs. For example, you can clone with --recurse-submodules and copy the\nflake.lock to ensure you’re using the same dependency versions as upstream.\nThis is great for debugging or sharing exact builds.
✅ Recap:
\nWith flakes, projects like Helix provide everything you need for development and\nrunning in a single flake.nix. You can nix develop to get started hacking, nix\nrun to quickly try it out, and nix build to produce binaries all without\ninstalling or polluting your system.
The helix flake is full of idiomatic Nix code and displays some of the more\nadvanced things a flake can provide:
\n{\n description = \"A post-modern text editor.\";\n\n inputs = {\n nixpkgs.url = \"github:nixos/nixpkgs/nixos-unstable\";\n rust-overlay = {\n url = \"github:oxalica/rust-overlay\";\n inputs.nixpkgs.follows = \"nixpkgs\";\n };\n };\n\n outputs = {\n self,\n nixpkgs,\n rust-overlay,\n ...\n }: let\n inherit (nixpkgs) lib;\n systems = [\n \"x86_64-linux\"\n \"aarch64-linux\"\n \"x86_64-darwin\"\n \"aarch64-darwin\"\n ];\n eachSystem = lib.genAttrs systems;\n pkgsFor = eachSystem (system:\n import nixpkgs {\n localSystem.system = system;\n overlays = [(import rust-overlay) self.overlays.helix];\n });\n gitRev = self.rev or self.dirtyRev or null;\n in {\n packages = eachSystem (system: {\n inherit (pkgsFor.${system}) helix;\n /*\n The default Helix build. Uses the latest stable Rust toolchain, and unstable\n nixpkgs.\n\n The build inputs can be overridden with the following:\n\n packages.${system}.default.override { rustPlatform = newPlatform; };\n\n Overriding a derivation attribute can be done as well:\n\n packages.${system}.default.overrideAttrs { buildType = \"debug\"; };\n */\n default = self.packages.${system}.helix;\n });\n checks =\n lib.mapAttrs (system: pkgs: let\n # Get Helix's MSRV toolchain to build with by default.\n msrvToolchain = pkgs.pkgsBuildHost.rust-bin.fromRustupToolchainFile ./rust-toolchain.toml;\n msrvPlatform = pkgs.makeRustPlatform {\n cargo = msrvToolchain;\n rustc = msrvToolchain;\n };\n in {\n helix = self.packages.${system}.helix.override {\n rustPlatform = msrvPlatform;\n };\n })\n pkgsFor;\n\n # Devshell behavior is preserved.\n devShells =\n lib.mapAttrs (system: pkgs: {\n default = let\n commonRustFlagsEnv = \"-C link-arg=-fuse-ld=lld -C target-cpu=native --cfg tokio_unstable\";\n platformRustFlagsEnv = lib.optionalString pkgs.stdenv.isLinux \"-Clink-arg=-Wl,--no-rosegment\";\n in\n pkgs.mkShell {\n inputsFrom = [self.checks.${system}.helix];\n nativeBuildInputs = with pkgs;\n [\n lld\n cargo-flamegraph\n rust-bin.nightly.latest.rust-analyzer\n ]\n ++ (lib.optional (stdenv.isx86_64 && stdenv.isLinux) cargo-tarpaulin)\n ++ (lib.optional stdenv.isLinux lldb)\n ++ (lib.optional stdenv.isDarwin darwin.apple_sdk.frameworks.CoreFoundation);\n shellHook = ''\n export RUST_BACKTRACE=\"1\"\n export RUSTFLAGS=\"''${RUSTFLAGS:-\"\"} ${commonRustFlagsEnv} ${platformRustFlagsEnv}\"\n '';\n };\n })\n pkgsFor;\n\n overlays = {\n helix = final: prev: {\n helix = final.callPackage ./default.nix {inherit gitRev;};\n };\n\n default = self.overlays.helix;\n };\n };\n nixConfig = {\n extra-substituters = [\"https://helix.cachix.org\"];\n extra-trusted-public-keys = [\"helix.cachix.org-1:ejp9KQpR1FBI2onstMQ34yogDm4OgU2ru6lIwPvuCVs=\"];\n };\n}\nTop-Level Metadata:
\n{\n description = \"A post-modern text editor.\";\n}\ninputs = {\n nixpkgs.url = \"github:nixos/nixpkgs/nixos-unstable\";\n rust-overlay = {\n url = \"github:oxalica/rust-overlay\";\n inputs.nixpkgs.follows = \"nixpkgs\";\n };\n};\nnixpkgs: Uses the nixos-unstable branch of the Nixpkgs repository.
rust-overlay: follows the same nixpkgs, ensuring compatibility between\ninputs.
Outputs Function:
\noutputs = { self, nixpkgs, rust-overlay, ... }:\npackages, devShells, etc.Common Setup:
\nlet\n inherit (nixpkgs) lib;\n systems = [ ... ];\n eachSystem = lib.genAttrs systems;\nsystems: A list of the supported systems
eachSystem: A Helper to map over all platforms.
pkgsFor = eachSystem (system:\n import nixpkgs {\n localSystem.system = system;\n overlays = [(import rust-overlay) self.overlays.helix];\n });\nnixpkgs for each system and applies overlays📦 packages
packages = eachSystem (system: {\n inherit (pkgsFor.${system}) helix;\n default = self.packages.${system}.helix;\n});\nIncludes 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:
{\n lib,\n rustPlatform,\n callPackage,\n runCommand,\n installShellFiles,\n git,\n gitRev ? null,\n grammarOverlays ? [],\n includeGrammarIf ? _: true,\n}: let\n fs = lib.fileset;\n\n src = fs.difference (fs.gitTracked ./.) (fs.unions [\n ./.envrc\n ./rustfmt.toml\n ./screenshot.png\n ./book\n ./docs\n ./runtime\n ./flake.lock\n (fs.fileFilter (file: lib.strings.hasInfix \".git\" file.name) ./.)\n (fs.fileFilter (file: file.hasExt \"svg\") ./.)\n (fs.fileFilter (file: file.hasExt \"md\") ./.)\n (fs.fileFilter (file: file.hasExt \"nix\") ./.)\n ]);\n\n # Next we actually need to build the grammars and the runtime directory\n # that they reside in. It is built by calling the derivation in the\n # grammars.nix file, then taking the runtime directory in the git repo\n # and hooking symlinks up to it.\n grammars = callPackage ./grammars.nix {inherit grammarOverlays includeGrammarIf;};\n runtimeDir = runCommand \"helix-runtime\" {} ''\n mkdir -p $out\n ln -s ${./runtime}/* $out\n rm -r $out/grammars\n ln -s ${grammars} $out/grammars\n '';\nin\n rustPlatform.buildRustPackage (self: {\n cargoLock = {\n lockFile = ./Cargo.lock;\n # This is not allowed in nixpkgs but is very convenient here: it allows us to\n # avoid specifying `outputHashes` here for any git dependencies we might take\n # on temporarily.\n allowBuiltinFetchGit = true;\n };\n\n nativeBuildInputs = [\n installShellFiles\n git\n ];\n\n buildType = \"release\";\n\n name = with builtins; (fromTOML (readFile ./helix-term/Cargo.toml)).package.name;\n src = fs.toSource {\n root = ./.;\n fileset = src;\n };\n\n # Helix attempts to reach out to the network and get the grammars. Nix doesn't allow this.\n HELIX_DISABLE_AUTO_GRAMMAR_BUILD = \"1\";\n\n # So Helix knows what rev it is.\n HELIX_NIX_BUILD_REV = gitRev;\n\n doCheck = false;\n strictDeps = true;\n\n # Sets the Helix runtime dir to the grammars\n env.HELIX_DEFAULT_RUNTIME = \"${runtimeDir}\";\n\n # Get all the application stuff in the output directory.\n postInstall = ''\n mkdir -p $out/lib\n installShellCompletion ${./contrib/completion}/hx.{bash,fish,zsh}\n mkdir -p $out/share/{applications,icons/hicolor/{256x256,scalable}/apps}\n cp ${./contrib/Helix.desktop} $out/share/applications/Helix.desktop\n cp ${./logo.svg} $out/share/icons/hicolor/scalable/apps/helix.svg\n cp ${./contrib/helix.png} $out/share/icons/hicolor/256x256/apps/helix.png\n '';\n\n meta.mainProgram = \"hx\";\n })\nhelix/default.nixThis default.nix file is a Nix derivation that defines how to build the Helix\neditor itself. It’s designed to be called by the main flake.nix as part of its\npackages output.
Here’s a breakdown of its components:
\n{\n lib,\n rustPlatform,\n callPackage,\n runCommand,\n installShellFiles,\n git,\n gitRev ? null,\n grammarOverlays ? [],\n includeGrammarIf ? _: true,\n}:\nlib: The Nixpkgs lib (library) functions, essential for common operations\nlike fileset and strings.
rustPlatform: A helper function from Nixpkgs specifically for building Rust\nprojects. It provides a buildRustPackage function, which simplifies the\nprocess significantly.
callPackage: A Nixpkgs function used to instantiate a Nix expression (like\ngrammars.nix) with its dependencies automatically supplied from the current\nNix environment.
runCommand: A Nixpkgs primitive that creates a derivation by running a shell\ncommand. It’s used here to construct the runtimeDir.
installShellFiles: A utility from Nixpkgs for installing shell completion\nfiles.
git: The Git package, needed for determining the gitRev.
gitRev ? null: The Git revision of the Helix repository. It’s an optional\nargument, defaulting to null. This is passed in from the main flake.nix.
grammarOverlays ? []: An optional list of overlays for grammars, allowing\ncustomization.
includeGrammarIf ? _: true: An optional function to control which grammars are\nincluded.
let ... in)let\n fs = lib.fileset;\n\n src = fs.difference (fs.gitTracked ./.) (fs.unions [\n ./.envrc\n ./rustfmt.toml\n ./screenshot.png\n ./book\n ./docs\n ./runtime\n ./flake.lock\n (fs.fileFilter (file: lib.strings.hasInfix \".git\" file.name) ./.)\n (fs.fileFilter (file: file.hasExt \"svg\") ./.)\n (fs.fileFilter (file: file.hasExt \"md\") ./.)\n (fs.fileFilter (file: file.hasExt \"nix\") ./.)\n ]);\n\n grammars = callPackage ./grammars.nix { inherit grammarOverlays includeGrammarIf; };\n runtimeDir = runCommand \"helix-runtime\" {} ''\n mkdir -p $out\n ln -s ${./runtime}/* $out\n rm -r $out/grammars\n ln -s ${grammars} $out/grammars\n '';\nin\nfs = 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\nbuild Helix by:
Taking all Git-tracked files in the current directory (fs.gitTracked ./.).
Excluding configuration files (e.g., .envrc, flake.lock), documentation\n(.md), images (.svg), and Nix files (.nix) using fs.difference and\nfs.unions. This ensures a clean build input, reducing Nix store size and\navoiding unnecessary rebuilds.
grammars: Builds syntax grammars by calling grammars.nix, passing\ngrammarOverlays (for customizing grammar builds) and includeGrammarIf (a\nfilter 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\nderivation, ensuring Helix uses Nix-managed grammars.
rustPlatform.buildRustPackage)The core of this default.nix is the rustPlatform.buildRustPackage call,\nwhich is a specialized builder for Rust projects:
in\n rustPlatform.buildRustPackage (self: {\n cargoLock = {\n lockFile = ./Cargo.lock;\n # ... comments ...\n allowBuiltinFetchGit = true;\n };\ncargoLock: Specifies how Cargo dependencies are handled.
lockFile = ./Cargo.lock; Points to the Cargo.lock file for reproducible\nbuilds.
allowBuiltinFetchGit = true: Allows Cargo to fetch Git dependencies directly\nfrom repositories specified in Cargo.lock. This is discouraged in Nixpkgs\nbecause it can break build reproducibility, but it’s used here for convenience\nduring development, eliminating the need to manually specify outputHashes for\nGit dependencies.
nativeBuildInputs = [\n installShellFiles\n git\n ];\nnativeBuildInputs: Are tools needed during the build process but not\nnecessarily at runtime.
buildType = \"release\";\nbuildType: Specifies that Helix should be built in “release” mode (optimized).
name = with builtins; (fromTOML (readFile ./helix-term/Cargo.toml)).package.name;\n src = fs.toSource {\n root = ./.;\n fileset = src;\n };\nname: Dynamically sets the package name by reading it from the Cargo.toml\nfile.
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.\n HELIX_DISABLE_AUTO_GRAMMAR_BUILD = \"1\";\n\n # So Helix knows what rev it is.\n HELIX_NIX_BUILD_REV = gitRev;\nEnvironment Variables: Sets environment variables that Helix uses.
\nHELIX_DISABLE_AUTO_GRAMMAR_BUILD = \"1\": Prevents Helix from downloading\ngrammars during the build, as Nix’s sandboxed environment disallows network\naccess. Instead, grammars are provided via the runtimeDir derivation.
HELIX_NIX_BUILD_REV = gitRev: Embeds the specified Git revision (or null if\nunspecified) into the Helix binary, allowing Helix to display its version or\ncommit hash.
doCheck = false;\n strictDeps = true;\ndoCheck = false;: Skips running tests during the build. This is common for\nfaster builds, especially in CI/CD, but tests are often run in a separate\nchecks output (as seen in the flake.nix).
strictDeps = true;: Ensures that all dependencies are explicitly declared.
# Sets the Helix runtime dir to the grammars\nenv.HELIX_DEFAULT_RUNTIME = \"${runtimeDir}\";\n# Sets the Helix runtime dir to the grammars\nenv.HELIX_DEFAULT_RUNTIME = \"${runtimeDir}\";\nenv.HELIX_DEFAULT_RUNTIME: Tells Helix where to find its runtime files\n(including the Nix-managed grammars).
# Get all the application stuff in the output directory.\npostInstall = ''\n mkdir -p $out/lib\n installShellCompletion ${./contrib/completion}/hx.{bash,fish,zsh}\n mkdir -p $out/share/{applications,icons/hicolor/{256x256,scalable}/apps}\n cp ${./contrib/Helix.desktop} $out/share/applications/Helix.desktop\n cp ${./logo.svg} $out/share/icons/hicolor/scalable/apps/helix.svg\n cp ${./contrib/helix.png} $out/share/icons/hicolor/256x256/apps/helix.png\n'';\npostInstall: A shell script that runs after the main build is complete. This\nis used for installing additional files that are part of the Helix distribution\nbut not directly built by Cargo.
Installs shell completion files (hx.bash, hx.fish, hx.zsh). This enables\ntab completion.
Installs desktop entry files (Helix.desktop) and icons (logo.svg,\nhelix.png) for desktop integration for GUI environments.
meta.mainProgram = \"hx\";\n\n})\nmeta.mainProgram: Specifies the primary executable provided by this package,\nallowing nix run to automatically execute hx.
A lot going on in this derivation!
\npackages output section. It looks like this:packages = eachSystem (system: {\n inherit (pkgsFor.${system}) helix;\n /*\n The default Helix build. Uses the latest stable Rust toolchain, and unstable\n nixpkgs.\n\n The build inputs can be overridden with the following:\n\n packages.${system}.default.override { rustPlatform = newPlatform; };\n\n Overriding a derivation attribute can be done as well:\n\n packages.${system}.default.overrideAttrs { buildType = \"debug\"; };\n */\n default = self.packages.${system}.helix;\n });\ndefault package. The comments actually tell us exactly how to do\nthis. We want to use overrideAttrs to change the buildTypeChange this line:
\ndefault = self.packages.${system}.helix;\nTo this:
\ndefault = self.packages.${system}.helix.overrideAttrs { buildType = \"debug\"; };\nbuildType) to “debug” instead of “release”.nix build\n./result/bin/hx\nThis is a simple yet powerful “hack” that demonstrates how easily you can modify\nthe behavior of a package defined within a Nix flake without changing the\noriginal source code or the upstream flake directly. You’re simply telling Nix\nhow you’d like your version of the package to be built.
\nSince we are already familiar with the structure and behavior of Helix’s\nflake.nix, we can leverage that understanding to create our own Nix flake. By\nanalyzing how Helix organizes its inputs, outputs, and package definitions,\nwe gain the confidence to modify and extend a flake’s functionality to suit our\nspecific needs—whether that’s customizing builds, adding overlays, or\nintegrating with home-manager.
flake.nix in your own directory (outside the helix repo):{\n description = \"Customized Helix build with debug features\";\n\n inputs = {\n helix.url = \"github:helix-editor/helix\";\n nixpkgs.url = \"github:nixos/nixpkgs/nixos-unstable\";\n rust-overlay = {\n url = \"github:oxalica/rust-overlay\";\n inputs.nixpkgs.follows = \"nixpkgs\";\n };\n };\n outputs = {\n self,\n helix,\n nixpkgs,\n rust-overlay,\n }: let\n system = \"x86_64-linux\";\n pkgs = import nixpkgs {\n system = system;\n overlays = [rust-overlay.overlay.overlays.default];\n };\n in {\n packages.${system}.default = helix.packages.${system}.helix.overrideAttrs (old: {\n buildType = \"debug\";\n\n # Add additional cargo features\n cargoBuildFlags =\n (old.cargoBuildFlags or [])\n ++ [\n \"--features\"\n \"tokio-console\"\n ];\n\n # Inject custom RUSTFLAGS\n RUSTFLAGS = (old.RUSTFLAGS or \"\") + \" -C debuginfo=2 -C opt-level=1\";\n });\n };\n}\nCheck it:
\nnix flake check\nwarning: creating lock file '\"/home/jr/world/flake.lock\"':\n• Added input 'helix':\n 'github:helix-editor/helix/8961ae1dc66633ea6c9f761896cb0d885ae078ed?narHash=sha256-f14perPUk%2BH15GyGRbg0Akqhn3rxFnc6Ez5onqpzu6A%3D' (2025-05-29)\n• Added input 'helix/nixpkgs':\n 'github:nixos/nixpkgs/5135c59491985879812717f4c9fea69604e7f26f?narHash=sha256-Vr3Qi346M%2B8CjedtbyUevIGDZW8LcA1fTG0ugPY/Hic%3D' (2025-02-26)\n• Added input 'helix/rust-overlay':\n 'github:oxalica/rust-overlay/d342e8b5fd88421ff982f383c853f0fc78a847ab?narHash=sha256-3SdPQrZoa4odlScFDUHd4CUPQ/R1gtH4Mq9u8CBiK8M%3D' (2025-02-27)\n• Added input 'helix/rust-overlay/nixpkgs':\n follows 'helix/nixpkgs'\n• Added input 'nixpkgs':\n 'github:nixos/nixpkgs/96ec055edbe5ee227f28cdbc3f1ddf1df5965102?narHash=sha256-7doLyJBzCllvqX4gszYtmZUToxKvMUrg45EUWaUYmBg%3D' (2025-05-28)\n• Added input 'rust-overlay':\n 'github:oxalica/rust-overlay/405ef13a5b80a0a4d4fc87c83554423d80e5f929?narHash=sha256-k0nhPtkVDQkVJckRw6fGIeeDBktJf1BH0i8T48o7zkk%3D' (2025-05-30)\n• Added input 'rust-overlay/nixpkgs':\n follows 'nixpkgs'\nnix flake check command will generate a flake.lock file if one doesn’t\nexist, and the warnings you see indicate that new inputs are being added and\nlocked to specific versions for reproducibility. This is expected behavior for\na new or modified flake.Inspect the outputs:
\nnix flake show\npath:/home/jr/world?lastModified=1748612128&narHash=sha256-WEYtptarRrrm0Jb/0PJ/b5VPqLkCk5iEenjbKYU4Xm8%3D\n└───packages\n └───x86_64-linux\n └───default: package 'helix-term'\nThe └───packages line indicates that our flake exposes a top-level\npackages attribute.
└───x86_64-linux: System architecture specificity
└───default: package 'helix-term' Signifies that within the x86_64-linux\npackages, there’s a package named default. This is a special name that\nallows 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\ntells us that our default package is helix-term. This confirms that our\noverrideAttrs in the packages.${system}.default section successfully\ntargeted and modified the Helix editor package, which is internally named\nhelix-term by the Helix flake.
What This Does:
\noverrideAttrs lets you change only parts of the derivation without\nrewriting everything.
buildType = \"debug\" enables debug builds.
cargoBuildFlags adds extra features passed to Cargo, e.g.,\n--features tokio-console
RUSTFLAGS gives you even more control over compiler behavior, optimization\nlevels, etc.
Run It:
\nnix run\nOr drop into the dev shell:
\nnix develop\ndevShells output)Adding the devShells output:
Since we already have the helix flake as an input to our own flake.nix we can\nnow forward or extend Helix’s devShells like this:
outputs = { self, nixpkgs, helix, rust-overlay, ... }: {\n devShells = helix.devShells;\n};\nOr if you want to pick a specific system:
\noutputs = { self, nixpkgs, helix, rust-overlay ... }:\n let\n system = \"x86_64-linux\";\n in {\n devShells.${system} = helix.devShells.${system};\n };\nOptional: Combine with your own devShell
You can also extend or merge it with your own shell like so:
\noutputs = { self, nixpkgs, helix, rust-overlay, ... }:\n let\n system = \"x86_64-linux\";\n pkgs = import nixpkgs { inherit system; };\n in {\n devShells.${system} = {\n default = pkgs.mkShell {\n name = \"my-shell\";\n inputsFrom = [ helix.devShells.${system}.default ];\n buildInputs = [ pkgs.git ];\n };\n };\n };\nUsing devour-flake to Cache All Your Flake Outputs to Cachix
\nWhen working with Nix flakes, it’s common to have many outputs: packages, apps,\ndev shells, NixOS or Darwin configurations, and more. Efficiently building and\ncaching all these outputs can be challenging, especially in CI or when\ncollaborating. This is where devour-flake and Cachix shine.
\nWhy Use the devour-flake?
\nBy default, building all outputs of a flake with nix build .#a .#b ... .#z can\nbe slow and inefficient, as Nix will evaluate the flake multiple times, once for\neach output. devour-flake solves this by generating a “consumer” flake that\ndepends on all outputs, allowing you to build everything in one go with a single\nevaluation
There quite a few ways to do this, choose a method of installation from the\ndevour-flake repository and then\ncontinue with step 1.
\nNix will only download binaries from binary caches if they are cryptographically\nsigned with any of the keys listed in nix.settings.trusted-public-keys.
# This is the default\nnix.settings.require-sigs = true;\nExample:
\nnix.settings = {\n builders-use-substitutes = true;\n substituters = [\n \"https://cache.nixos.org\"\n ];\n trusted-public-keys = [\n \"cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDShjY=\"\n ];\n};\nYou can even build it without installing with the following command:
\nnix build github:srid/devour-flake \\\n -L --no-link --print-out-paths \\\n --override-input flake path/to/flake | cachix push <name>\nnix-shell -p cachix\nThis will push all flake outputs to cachix if you have a valid authentication\ntoken and have created a cache already.
\nHow to Use devour-flake with Cachix
\n(Optional) Configure your token locally, copy your auth token for the following\ncommand:
\ncachix authtoken <YOUR_TOKEN>\n# Use cachix cli for the following\ncachix use your-cache-name\ncachix use adds your substitutors and trusted-public-keys to your\n~/.config/nix/nix.conf and creates one if it doesn’t exist.Push All Flake Inputs to Cachix
\nReplace <mycache> with the name of the cache you just created.
nix flake archive --json \\\n | jq -r '.path,(.inputs|to_entries[].value.path)' \\\n | cachix push <mycache>\nYou should see output similar to the following:
\nPushing 637 paths (2702 are already present) using zstd to cache sayls8 ⏳\n\n✓ /nix/store/0aqvmjvhkar3j2f7zag2wjl4073apnvk-vimplugin-crates.nvim-2025-05-30 (734.65 KiB)\n✓ /nix/store/02wm10zck7rb836kr0h3afjxl80866dp-X-Restart-Triggers-keyd (184.00 B)\n✓ /nix/store/0asdaaax0lf1wa6m6lqqdvc8kp6qn3f6-dconf-cleanup (1008.00 B)\n✓ /nix/store/09ki2jlh6sqbn01yw6n15h8d55ihxygf-helix-tree-sitter-mojo-3d7c53b8038f9ebbb57cd2e61296180aa5c1cf64 (601.37 KiB)\n✓ /nix/store/0i2c29nldqvb9pnypvp3ika4i7fhc0ck-devour-output (312.00 B)\n✓ /nix/store/0c0mwfb78xm862a7g4h9fhgzn55zppj6-helix-term (29.88 MiB)\n✓ /nix/store/0fhdpb2qck1kbngq1dlc8lyqqadj2pb1-hyprcursor-0.1.12+date=2025-06-05_45fcc10-lib (487.30 KiB)\n✓ /nix/store/0mfpi51bswgd91l8clqcz6mxy5k5zcd4-vimplugin-auto-pairs-2019-02-27 (40.60 KiB)\n✓ /nix/store/0k2zq8y78vrhhkf658j6i45vz3y89v11-helix-tree-sitter-tcl-56ad1fa6a34ba800e5495d1025a9b0fda338d5b8 (110.25 KiB)\n✓ /nix/store/0qxmahrw935136dbxkmvrg14fgnzi6bb-vimplugin-obsidian.nvim-2025-07-01 (493.02 KiB)\n✓ /nix/store/0wjppqzcbnlf9srhr6k27pz403j3mg2j-hm-session-vars.sh (1.86 KiB)\n✓ /nix/store/0z41071z33zg1zqyasccc3cfhxj389k0-helix-tree-sitter-swift-57c1c6d6ffa1c44b330182d41717e6fe37430704 (2.77 MiB)\n✓ /nix/store/0n5f1x8lpc93zm81bxrfh6yccyngvrdl-unit-plymouth-read-write.service (1.19 KiB)\n✓ /nix/store/0z8ac35n89lv2knzaj6kkp0cfxr6pmgc-hm_face.png (300.60 KiB)\n✓ /nix/store/0zp5846pry5rknnvzz81zlvj4ghnkxp5-hyprutils-0.8.1+date=2025-07-07_a822973 (421.64 KiB)\n✓ /nix/store/118ihgwjw6kp0528igns3pnvzbszljmg-unit-dbus.service (1.34 KiB)\n✓ /nix/store/0pajdq9mfgkcdwbqp38j7d4clc9h9iik-hm_.mozillafirefoxdefault.keep (112.00 B)\n✓ /nix/store/0nlvffvpx6s8mpd2rpnqb1bl5idd16yk-hm-dconf.ini (224.00 B)\n✓ /nix/store/1fiqgqvi574rdckav0ikdh8brwdhvh69-vimplugin-alpha-nvim-2025-05-26 (69.38 KiB)\n✓ /nix/store/1fqxw31p1llag0g7wg7izq22x5msz47r-vimplugin-persistence.nvim-2025-02-25 (37.74\n\n\n❗ NOTE: The effectiveness of pushing the rest to cachix depend on your\nnetwork speed. I actually noticed a slow down after pushing the
\nnix/store.\nPushing thenix/storeis rarely necessary and can be very slow and\nbandwidth-intensive. Most users will only need to push relevant outputs.
Push the Entire /nix/store
\nnix path-info --all | cachix push <mycache>\nPushing shell environment
\nnix develop --profile dev-profile -c true\n# then run\ncachix push <mycache> dev-profile\n{\n config,\n lib,\n pkgs,\n ...\n}: let\n cfg = config.custom.cachix;\nin {\n options = {\n custom.cachix.enable = lib.mkEnableOption \"Enable custom cachix configuration\";\n };\n\n config = lib.mkIf cfg.enable {\n environment.systemPackages = with pkgs; [cachix];\n\n # to prevent garbage collection of outputs immediately after building\n nix.extraOptions = \"gc-keep-outputs = true\";\n nix.settings = {\n substituters = [\n \"https://nix-community.cachix.org\"\n \"https://hyprland.cachix.org\"\n \"https://ghostty.cachix.org\"\n \"https://neovim-nightly.cachix.org\"\n \"https://yazi.cachix.org\"\n \"https://helix.cachix.org\"\n \"https://nushell-nightly.cachix.org\"\n \"https://wezterm.cachix.org\"\n \"https://sayls88.cachix.org\"\n # \"https://nixpkgs-wayland.cachix.org\"\n ];\n trusted-public-keys = [\n \"nix-community.cachix.org-1:mB9FSh9qf2dCimDSUo8Zy7bkq5CX+/rkCWyvRCYg3Fs=\"\n \"hyprland.cachix.org-1:a7pgxzMz7+chwVL3/pzj6jIBMioiJM7ypFP8PwtkuGc=\"\n \"ghostty.cachix.org-1:QB389yTa6gTyneehvqG58y0WnHjQOqgnA+wBnpWWxns=\"\n \"neovim-nightly.cachix.org-1:feIoInHRevVEplgdZvQDjhp11kYASYCE2NGY9hNrwxY=\"\n \"yazi.cachix.org-1:Dcdz63NZKfvUCbDGngQDAZq6kOroIrFoyO064uvLh8k=\"\n \"helix.cachix.org-1:ejp9KQpR1FBI2onstMQ34yogDm4OgU2ru6lIwPvuCVs=\"\n \"nushell-nightly.cachix.org-1:nLwXJzwwVmQ+fLKD6aH6rWDoTC73ry1ahMX9lU87nrc=\"\n \"wezterm.cachix.org-1:kAbhjYUC9qvblTE+s7S+kl5XM1zVa4skO+E/1IDWdH0=\"\n \"sayls88.cachix.org-1:LT8JnboX8mKhabC3Mj/ONHb5tyrjlnsdauQkD8Lu0us=\"\n # \"nixpkgs-wayland.cachix.org-1:3lwxaILxMRkVhehr5StQprHdEo4IrE8sRho9R9HOLYA=\"\n ];\n };\n };\n}\nThe sayls8 entries are my custom cache. To find your trusted key go to the\ncachix website, click on your cache and it is listed near the top.
\nI enable this with custom.cachix.enable = true; in my configuration.nix or\nequivalent.
Another option is to use the top-level nixConfig attribute for adding your\nsubstitutors and trusted-public-keys. You only need to choose 1 method FYI:
{\n description = \"NixOS & Flake Config\";\n\n# the nixConfig here only affects the flake itself, not the system configuration!\n nixConfig = {\n experimental-features = [ \"nix-command\" \"flakes\" ];\n trusted-users = [ \"ryan\" ];\n\n substituters = [\n # replace official cache with a mirror located in China\n \"https://mirrors.ustc.edu.cn/nix-channels/store\"\n \"https://cache.nixos.org\"\n ];\n\n # nix community's cache server\n extra-substituters = [\n \"https://nix-community.cachix.org\"\n \"https://nixpkgs-wayland.cachix.org\"\n ];\n extra-trusted-public-keys = [\n \"cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDShjY=\"\n \"nix-community.cachix.org-1:mB9FSh9qf2dCimDSUo8Zy7bkq5CX+/rkCWyvRCYg3Fs=\"\n \"nixpkgs-wayland.cachix.org-1:3lwxaILxMRkVhehr5StQprHdEo4IrE8sRho9R9HOLYA=\"\n ];\n };\n# ... snip\n\n\n❗️ WARNING:
\ntrusted-usersis a list of users who are allowed to bypass many\nof Nix’s normal safety restrictions and change daemon-level settings. Keep\ntrusted-usersas small as possible (often justrootand maybe your own\nuser on a single-user box)
You can build and push all outputs of your flake to Cachix using the following\ncommand when in your flake directory:
\nnix build github:srid/devour-flake \\\n -L --no-link --print-out-paths \\\n --override-input flake . \\\n | cachix push <your-cache-name>\nReplace your-cache-name with your actual Cachix cache name.
This command will:
\nUse devour-flake to enumerate and build all outputs of your flake (including\npackages, devShells, NixOS configs, etc.)
\nPipe the resulting store paths to cachix push, uploading them to your binary\ncache.
\nSuppose your cache is named my-flake-cache:
\nnix build github:srid/devour-flake \\\n -L --no-link --print-out-paths \\\n --override-input flake . \\\n | cachix push my-flake-cache\nThis approach is particularly useful in CI pipelines, where you want to ensure\nall outputs are built and cached for collaborators and future builds. You can\nadd the above command to your CI workflow, ensuring the Cachix auth token is\nprovided as a secret
\nYou can add devour-flake as an input to your flake for local development:
\n{\n inputs = {\n devour-flake.url = \"github:srid/devour-flake\";\n devour-flake.flake = false;\n };\n}\nAnd in your flake’s outputs, add an overlay that makes devour-flake\navailable in your package set:
outputs = { self, nixpkgs, devour-flake, ... }@inputs: {\n overlays.default = final: prev: {\n devour-flake = import devour-flake { inherit (prev) pkgs; };\n };\n\n # Example: Add devour-flake to your devShell\n devShells.x86_64-linux.default = let\n pkgs = import nixpkgs {\n system = \"x86_64-linux\";\n overlays = [ self.overlays.default ];\n };\n in pkgs.mkShell {\n buildInputs = [ pkgs.devour-flake ];\n };\n};\nUse devour-flake in your devShell:
\nnix develop\nYou’ll have the devour-flake command available for local use, so you can\nquickly build and push all outputs as needed.
\n\nTIP: Alternatively, use
\ndevour-flakeas an app:\napps.x86_64-linux.devour-flake = {\n type = \"app\";\n program = \"${self.packages.x86_64-linux.devour-flake}/bin/devour-flake\";\n};\n\n
What Gets Built and Cached?
\ndevour-flake detects and builds all standard outputs of a flake, including:
packages
\napps
\nchecks
\ndevShells
\nnixosConfigurations.*
\ndarwinConfigurations.*
\nhome-manager configurations
\nThis ensures that everything your flake produces is available in your Cachix\ncache for fast, reproducible builds.
\n![\"Whonix](\"https://saylesss88.github.io/../images/swappy-20250901-101339.cleaned.png\")
\n\n⚠️ WARNING: There is no general software that can guarantee absolute anonymity\nor security; perfect security is a myth. Security is a continuous process, not\na one-time product. It also depends on time and resources: if an adversary has\nenough of either, eventual compromise is probable. However, by layering\ndefenses and following best practices, we can make attacks costly and\ntime-consuming, deterring all but highly targeted adversaries.
\n
It is highly recommended to harden your Host Machine as Type 2 hypervisors are\nonly as secure as their host. KVM is actually a type 1 hypervisor but relies on\nQEMU for emulation which is a Type 2 hypervisor. This actually makes it a sort\nof hybrid in between Type 1 and Type 2 but is in theory less secure than running\na Xen hypervisor (Type 1) on bare-metal.
\nWhonix offers many benefits, including the convenience of running within your\ncurrent operating system without needing to reboot or use a separate Tails USB.\nIt provides similar strong anonymity protections by routing all traffic through\nTor in isolated virtual machines. The Whonix documentation is transparent about\nits limitations, which helps build trust and confidence in its security model.
\nTails is great but they add an add blocker to Tor that makes every Tails user\nunique from the rest of Tor Browser users reducing anonymity.
\n\n\n⚠️ Never rely solely on the Virtual Machine to protect you, if your host OS\nisn’t secure a Virtual Machine won’t protect you. If you have high threat\nmodel, you may want to choose a Host with better support for AppArmor and\nSelinux as they are highly limited on NixOS.
\n
That being said, there is a lot you can do to harden NixOS…
\nNo activity conducted inside Whonix-Workstation can cause IP/DNS leaks so\nlong as Whonix-Gateway is left unchanged or only documented changes are made\nlike configuring bridges, establishing onion services and running updates.
Whonix does not and does not claim to protect users against advanced\nadversaries such as nation state actors, if they target you, you will be\ninfected! If used correctly, Whonix can provide partial protection against\npassive surveillance programs, it all depends on whether Tor can provide\nadequate protection or not, which is not clear at this time.
\nYou shouldn’t use a VPN with Whonix and it is obvious that you’re using Tor\nbecause connections are made to known Tor Relays, which are publicly listed\nand identifiable.
\n\n\n⚠️It is impossible to Hide Tor use from the internet service provider (ISP).\nIt has been concluded this goal is difficult beyond practicality.\n–Whonix Hide Tor from your ISP
\n
Millions of people use Tor daily for wholly legitimate reasons, particularly\nto assert their privacy rights when faced with countless corporate /\ngovernment network observers and censors.
\nTrue anonymity is very difficult to successfully pull off and not something\nthat you can maintain for a long time.
\n\nWhonix is an operating system based on Debian base (Kicksecure Hardened) and the\nTor network, which is designed for maximum anonymity and security. Whonix\nconsists 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\nmodule, libvirtd service, and QEMU virtualization service which together enable\nhosting VMs. It is recommended to harden the host before moving on.
\nGuests are the virtualized operating systems running inside the host’s\nvirtual machines. In this case the Whonix VMs are the Guest Machines.
\nWhonix-Gateway the first of 2 VMs runs Tor processes and forces all traffic\nthrough the Tor network using iptables.
Whonix-Workstation the second VM, is responsible for running user applications\nsuch as the Tor Browser. The Whonix-Workstation is isolated from both the\nWhonix-Gateway and the Host OS, if an app misbehaves, it is contained within the\nisolated Whonix-Workstation. It is largely unaware of sensitive info and won’t\nleak 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\nfind out the user’s IP, location, or de-anonymize the user. It offers full\nspectrum anti-tracking protection that is much safer than VPNs. Whonix provides\nthis through security by isolation, no app is trusted.
\nWhonix Concept: Whonix is an Isolating Proxy with an additional Transparent\nProxy, which can be optionally disabled. –Whonix Docs
Since Whonix is based on Kicksecure which is based on Debian stable, you can\ntypically look up solutions in a Kicksecure, Debian, or Ubuntu forum.
\nIf you really want to use VirtualBox, I got it working off of this config:
\nVirtualBox = Type 2 hypervisor
\nChange your-user to your username
# vbox.nix\n{\n config,\n lib,\n ...\n}: let\n cfg = config.custom.virtualbox;\nin {\n options.custom.virtualbox = {\n enable = lib.mkEnableOption \"Enable VirtualBox\";\n };\n\n config = lib.mkIf cfg.enable {\n virtualisation.virtualbox.host = {\n enable = false;\n # enableExtensionPack = true;\n };\n\n user.user.your-user.extraGroups = [\"vboxusers\"];\n\n boot.kernelModules =\n if config.hardware.cpu.amd.updateMicrocode\n then [\"kvm-amd\"]\n else [\"kvm-intel\"];\n };\n}\nEnable it with custom.virtualbox.enable = true;.
After rebuilding with virtualbox enabled and downloading the virtualbox whonix,\nopen VirtualBox and import the Whonix file.
\nFix the error:: VirtualBox can’t enable the AMD-V extension. Please disable the\nKVM kernel extension:
\nIf both of these are active, they compete with each other:
\nsudo lsmod | grep -E 'kvm|vbox'\nCheck the currently in use modules:
\nmodprobe -r kvm\nDisable kvm and kvm_amd:
\nsudo rmmod kvm_amd\nsudo rmmod kvm\n# To re-enable them when necessary\n# sudo modprobe kvm\n# sudo modprobe kvm_amd\nThere is an opposite viewpoint,\nWhy choose VirtualBox over KVM
\nThe whonix-gateway is software designed to run Tor.
\nThe Gateway acts as a firewall and is what is routing all your traffic through\nTor.
\nYou will spend minimal time in the Gateway, it’s mainly used for Tor\nconfiguration which is reserved for advanced users.
\nAll user applications should only be launched from Whonix-Workstation to ensure\nthey utilize the Tor network. (Never launch the Tor browser or any other user\napp from Whonix-Gateway.)
\nLeaky applications can’t breakout of the Workstation, all network connections\nare forced to go through the Whonix-Gateway where they are torrified and routed\nto the internet.
\nKVM (Kernel-based Virtual Machine) is a Linux kernel module that provides\nhardware-assisted virtualization.
\nIt allows the Linux kernel to act as a hypervisor, enabling virtual machines\n(VMs) to run with near-native speeds by using CPU virtualization extensions\n(Intel VT-x or AMD-V).
\nKVM itself doesn’t handle the entire VM lifecycle; it provides the core\nvirtualization infrastructure.
\nQEMU (Quick Emulator) is an open-source user-space program that emulates\nhardware for virtual machines.
\nWhen combined with KVM, QEMU uses hardware acceleration to run VMs much faster\nby offloading CPU virtualization to KVM.
\nSo, QEMU provides the device emulation and VM management interface, while KVM\nprovides the fast virtualization engine within the kernel.
\nInstall Qemu-KVM:
\n{\n config,\n pkgs,\n ...\n}: {\n ## QEMU-KVM\n environment.systemPackages = with pkgs; [\n qemu\n # Optional\n virt-viewer\n ];\n\n # Virt-Manager GUI\n programs.virt-manager.enable = true;\n virtualisation = {\n # libvirtd daemon\n libvirtd = {\n enable = true;\n qemu = {\n # enables a TPM emulator\n swtpm.enable = true;\n };\n };\n # allow USB device to be forwarded\n spiceUSBRedirection.enable = true;\n };\n # Spice protocol improves VM display and input responsiveness\n services.spice-vdagentd.enable = true;\n}\nThe libvirtd is the primary daemon (service) in the libvirt virtualization\nmanagement system. It runs on your host machine and acts as the core management\ncomponent for virtual machines (VMs).
\nAdd libvirtd & kvm to your users extraGroups:
users.users = {\n your-user = {\n extraGroups = [\n \"libvirtd\"\n \"kvm\"\n ];\n };\n};\nRestart libvirtd:
sudo systemctl restart libvirtd\nEnsure KVM’s / QEMU’s default network is enabled and has started:
\nsudo virsh -c qemu:///system net-autostart default\nsudo virsh -c qemu:///system net-start default\nGo to whoniix.org to verify the signature.\nDownload the OpenPGP Signature, and the Download Whonix OpenPGP Key. Your\nDownloads directory will look like this:
~/Downloads ls\n╭───┬───────────────────────────────────────────────────────┬──────┬─────────┬───────────────╮\n│ # │ name │ type │ size │ modified │\n├───┼───────────────────────────────────────────────────────┼──────┼─────────┼───────────────┤\n│ 0 │ Whonix-Xfce-17.4.4.6.Intel_AMD64.qcow2.libvirt.xz │ file │ 3.3 GB │ 2 minutes ago │\n│ 1 │ Whonix-Xfce-17.4.4.6.Intel_AMD64.qcow2.libvirt.xz.asc │ file │ 1.0 kB │ a minute ago │\n│ 2 │ derivative.asc │ file │ 77.3 kB │ 3 minutes ago │\n╰───┴───────────────────────────────────────────────────────┴──────┴─────────┴───────────────╯\nImport derivative.asc:
gpg --import derivative.asc\nVerify the Public Key:
\ngpg --verify Whonix-Xfce-17.4.4.6.Intel_AMD64.qcow2.libvirt.xz.asc Whonix-Xfce-17.4.4.6.Intel_AMD64.qcow2.libvirt.xz\ngpg: Signature made Sun 10 Aug 2025 09:04:13 AM EDT\ngpg: using RSA key 6E979B28A6F37C43BE30AFA1CB8D50BB77BB3C48\ngpg: Good signature from \"Patrick Schleizer <adrelanos@kicksecure.com>\" [unknown]\ngpg: aka \"Patrick Schleizer <adrelanos@riseup.net>\" [unknown]\ngpg: aka \"Patrick Schleizer <adrelanos@whonix.org>\" [unknown]\ngpg: WARNING: This key is not certified with a trusted signature!\ngpg: There is no indication that the signature belongs to the owner.\nPrimary key fingerprint: 916B 8D99 C38E AF5E 8ADC 7A2A 8D66 066A 2EEA CCDA\n Subkey fingerprint: 6E97 9B28 A6F3 7C43 BE30 AFA1 CB8D 50BB 77BB 3C48\n~/Downloads 09/04/2025 11:53:10 AM\nNow 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\nkeyserver to contribute to the web of trust but optional.
\nNixpkgs 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\nWhonix.
nix-shell -p xz safe-rm\ntar -xvf Whonix*.libvirt.xz\nThe following commands come directly from the\nWhonix KVM Docs Importing Whonix VM Templates
\nsudo virsh -c qemu:///system net-define Whonix_external*.xml\nsudo virsh -c qemu:///system net-define Whonix_internal*.xml\nsudo virsh -c qemu:///system net-autostart Whonix-External\nsudo virsh -c qemu:///system net-start Whonix-External\nsudo virsh -c qemu:///system net-autostart Whonix-Internal\nsudo virsh -c qemu:///system net-start Whonix-Internal\nsudo virsh -c qemu:///system define Whonix-Gateway*.xml\nsudo virsh -c qemu:///system define Whonix-Workstation*.xml\nAfter the above steps, either copy or move the qcow2 images to\n/var/lib/libvirt/images:
\n\n❗ It’s recommended to move the files into place, if you want to copy them you\nneed to use a special command FYI.
\n
sudo mkdir -p /var/lib/libvirt/images\nsudo mv Whonix-Gateway*.qcow2 /var/lib/libvirt/images/Whonix-Gateway.qcow2\nsudo mv Whonix-Workstation*.qcow2 /var/lib/libvirt/images/Whonix-Workstation.qcow2\nsafe-rm Whonix*\nsafe-rm -r WHONIX*\nvirt-manager\nFrom here it will take a bit to load both VMs, you can click on one and go to\nEdit, Virtual Machine Details and from there you have some options to give\nthe VM more CPUs and memory.
Considering that the Whonix-Workstation is where all of the user applications\nwill be opened, it makes sense to give it more CPUs and memory.
\nI’ve seen recommendations for a minimum of 4G of RAM for the Workstation and 2GB\nfor the Gateway.
\nIncrease vCPU count for better performance
\nEnable XML editing in settings
\nEnable copy pasting by adding <clipboard copypaste=\"yes\"/>
![\"Whonix](\"https://saylesss88.github.io/../images/swappy-20250901-101351.cleaned.png\")
Always start the Whonix-Gateway first.
\nClick on Whonix-Gateway, press Play, and choose the default Persistent VM.
\nTo view the gateway press Open.
You can use the “System Maintenance Panel” to Check for Updates and then\nInstall Updates. This can also be used for user and password creation, the\ndefault user is user with a passwordless login.
Change the password manually:
\nsudo passwd\nchangeme\nChange the passwords and disable auto-login.
\nRun a systemcheck if it wasn’t run automatically. Click the Xfce Logo and go to\nSystem, System Check.
Whonix-Workstation is another VM, designed to provide users with a secure and\nanonymous environment for running applications and performing online tasks.
\nWhen you first launch Whonix-Workstation, choose the second option down or\nreboot, and then choose “Persistent Mode Sysmaint Session”. From there, you can\ngo through the same steps as you did for the Gateway.
With the workstation, a security feature disables sudo for the default user.\nInstead of the user account, a separate sysmaint (system maintenance)\naccount is used for administrative tasks that require root privileges, such as\nupdates and package installations.
After you get your system updated and upgraded, you’ll want to reboot the\nWorkstation and start it in the first Persistent mode available rather than the\nsysmaint mode.
Once Workstation is running and both VMs are updated and upgraded, check that\nyour IP address is a Tor IP:
\ncurl ip.me\n#\ncurl ip.me\nEach consecutive time that you run curl ip.me, Tor establishes a new circuit\nand you will get a different IP returned each time for as many Tor nodes are\navailable. Not that you would want to but it’s cool functionality giving us a\nvisual of the new circuit.
Start Tor and check what you are fingerprinted as by typing deviceinfo.me into\nthe URL.
Click the Xfce logo and choose Tor Browser. On the first launch, you will need\nto update Tor by clicking in the top right corner.
\nOr you can open the terminal and type:
\nupdate-torbrowser\nMake sure you don’t forget to go to the Settings, Privacy and Security, and set\nthe Security Level to Safest to disable JavaScript and more before exploring\nthe dark web.
Visit https://check.torproject.org, you should see “Congratulations. This\nbrowser is configured to use Tor.”
If you need a place to start, check out https://tor.taxi by plugging that into\nthe URL. Always include the https yourself!
\n\n❗ NOTE: Use HTTPS and TLS wherever possible, since Tor only encrypts traffic\nas it travels through the network of three nodes. Traffic at Exit nodes is\nvulnerable if unencrypted, because when it reaches the Exit node it is plain\ntext. Prefer the use of
\n.onionservices because they form a tunnel that is\nencrypted end-to-end, using a random rendezvous point within the Tor network;\nHTTPS isn’t required within Onion services. Prefer the use of.onion\nservices because they form a tunnel that is encrypted end-to-end, using a\nrandom rendezvous point within the Tor network; HTTPS isn’t required within\nOnion services.\n–All my traffic is encrypted by default?
To get Whonix to perform more similarly to Tails you could run Whonix in Live\nMode. Live Mode is a privacy-focused mode where nothing is saved at shutdown,\nmaking it great for handling sensitive data.
\nSame process, reboot the Workstation and Choose\nLIVE Mode | USER Session | disposable use
Import the derivative.asc file:
gpg --import derivative.asc\ngpg --verify Kicksecure-Xfce-17.4.4.6.Intel_AMD64.qcow2.libvirt.xz.asc Kicksecure-Xfce-17.4.4.6.Intel_AMD64.qcow2.libvirt.xz\ngpg: Signature made Sun 10 Aug 2025 07:32:52 AM EDT\ngpg: using RSA key 6E979B28A6F37C43BE30AFA1CB8D50BB77BB3C48\ngpg: Good signature from \"Patrick Schleizer <adrelanos@kicksecure.com>\" [unknown]\ngpg: aka \"Patrick Schleizer <adrelanos@riseup.net>\" [unknown]\ngpg: aka \"Patrick Schleizer <adrelanos@whonix.org>\" [unknown]\ngpg: WARNING: This key is not certified with a trusted signature!\ngpg: There is no indication that the signature belongs to the owner.\nPrimary key fingerprint: 916B 8D99 C38E AF5E 8ADC 7A2A 8D66 066A 2EEA CCDA\n Subkey fingerprint: 6E97 9B28 A6F3 7C43 BE30 AFA1 CB8D 50BB 77BB 3C48\ntar -xvf Kicksecure*.libvirt.xz\nDon’t use unxz!
When you start exploring NixOS configurations or tools like Home Manager, you’ll\nencounter a concept called Nix Modules. Modules are also functions, but they\nbehave differently regarding their arguments, which can be a source of\nconfusion.
\nWhat are NixOS Modules?
\nNix Modules are a powerful system built on top of basic Nix functions, primarily\nused for declarative system configurations (like NixOS, Home Manager, NixOps,\netc.). They allow you to define parts of your system configuration in separate\nfiles that are then composed together.
\nEach module is typically a Nix function that returns an attribute set with\nspecific keys like options, config, and imports.
Automatic Arguments in Modules
\nUnlike the functions we’ve been writing, Nix’s module system automatically\npasses a standard set of arguments to every module function it evaluates. You\ndon’t explicitly pass these arguments when you import a module file; the\nmodule system handles it for you.
The most common automatic arguments you’ll see are:
\nconfig: The aggregated configuration options of all modules combined. This\nis what you use to read other configuration values.
options: The definitions of all available configuration options across all\nmodules.
pkgs: The standard Nixpkgs set, equivalent to import <nixpkgs> {}. This is\nincredibly convenient as you don’t need to import it in every module.
lib: The Nixpkgs utility library (pkgs.lib), providing helper functions\nfor common tasks.
specialArgs: An attribute set of extra arguments to be passed to the module\nfunctions.
A typical module might start like this:
\n# Example NixOS module\n{ config, pkgs, lib, ... }: # These arguments are passed automatically by the module system\n{\n # ... module options and configuration\n environment.systemPackages = [ pkgs.firefox pkgs.git ];\n services.nginx.enable = true;\n # ...\n}\nIn the above module, the only required argument is pkgs because we explicitly\nuse it in the module (i.e. pkgs.firefox). Editors have pretty good support for\nletting you know if you’re missing arguments or have unnecessary ones. config,\nand 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\nsimplifies writing configurations, as you always have access to pkgs, lib,\nand the evolving config and options without boilerplate.
specialArgs: Passing Custom Arguments to ModulesWhile the module system passes a standard set of arguments automatically, what\nif you need to pass additional, custom data to your modules that isn’t part of\nthe standard config, pkgs, lib, or options? This is where specialArgs\ncomes in.
specialArgs is an attribute you can pass to the import function when you\nload a module (or a set of modules). It’s typically used to provide data that\nyour modules need but isn’t something Nixpkgs would normally manage.
For example, in a configuration.nix:
# From your configuration.nix\n{ config, pkgs, lib, ... }: # Standard module arguments\n\nlet\n myCustomValue = \"helloWorld\";\nin\n{\n # ... imports all modules, including your custom ones\n imports = [\n ./hardware-configuration.nix\n ./my-webserver-module.nix\n ];\n\n # This is where specialArgs would be used (often in import statements)\n # Example: passing a custom value to ALL modules:\n # (in module context, this is more complex, but conceptually)\n # let\n # allModules = [ ./my-module.nix ];\n # in\n # lib.nixosSystem {\n # modules = allModules;\n # specialArgs = {\n # username = \"johndoe\";\n # mySecretKey = \"/run/keys/ssh_key\";\n # };\n # # ...\n # };\n}\nAnd then, inside my-webserver-module.nix:
# my-webserver-module.nix\n{ config, pkgs, lib, username, mySecretKey, ... }: # username and mySecretKey come from specialArgs\n{\n # ... use username and mySecretKey in your module\n users.users.${username} = {\n isNormalUser = true;\n extraGroups = [ \"wheel\" \"networkmanager\" ];\n # ...\n };\n # ...\n}\nAny argument listed in a module’s function signature that is not one of the\nstandard config, pkgs, lib, options (or pkgs.callPackage, etc., which\nare often implicit through pkgs) must be provided via specialArgs at the\npoint where the modules are composed.
Any values listed in a module that aren’t automatically passed via Nixpkgs must\nbe explicitly provided through specialArgs.
specialArgs and extraSpecialArgs with FlakesNixOS modules use specialArgs and Home-Manager uses extraSpecialArgs to\nallow you to pass extra arguments.
Or with Flakes it would look like this:
\n{\n description = \"My Flake\";\n inputs = {\n nixpkgs.url = \"github:nixos/nixpkgs/nixos-unstable\";\n home-manager.url = \"github:nix-community/home-manager\";\n home-manager.inputs.nixpkgs.follows = \"nixpkgs\";\n };\n\n outputs = { self, nixpkgs, home-manager, ... }:\n let\n lib = nixpkgs.lib;\n pkgs = nixpkgs.legacyPackages.${\"x86_64-linux\"};\n system = \"x86_64-linux\";\n host = \"magic\";\n username = \"jr\";\n userVars = {\n timezone = \"America/New_York\";\n locale = \"en_US.UTF-8\";\n gitUsername = \"TSawyer87\";\n dotfilesDir = \"~/.dotfiles\";\n wm = \"hyprland\";\n browser = \"firefox\";\n term = \"ghostty\";\n editor = \"hx\";\n keyboardLayout = \"us\";\n };\n in {\n nixosConfigurations = {\n YOURHOSTNAME = lib.nixosSystem {\n system = \"x86_64-linux\";\n modules = [ ./configuration.nix ];\n specialArgs = {\n inherit userVars; # == userVars = userVars;\n inherit host;\n inherit username;\n };\n };\n };\n homeConfigurations = {\n USERNAME = home-manager.lib.homeManagerConfiguration {\n inherit pkgs;\n modules = [ ./home.nix ];\n extraSpecialArgs = {\n inherit userVars;\n inherit host;\n inherit username;\n # or it can be written like this:\n # inherit userVars host username;\n };\n };\n };\n };\n}\nNow if I want to use any of these arguments in modules I can by any module file\nreferenced by my configuration.
\nFor example, the following is a git.nix module that uses the variables from\nthe flake passed from extraSpecialArgs in this case because it’s a\nhome-manager module:
# git.nix\n{ userVars, ... }: {\n programs = {\n git = {\n enable = true;\n userName = userVars.gitUsername;\n };\n };\n}\n| 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. |
⚠️ Important: Never commit secrets (passwords, API keys, tokens, etc.) in\nplain text to your Git repository. If you plan to publish your NixOS\nconfiguration, always use a secrets management tool like sops-nix or agenix to\nkeep sensitive data safe. See the\nSops-Nix Guide\nfor details.
\nIt’s also important to understand that all files in the /nix/store are\nworld-readable by default This has important security implications for anyone\nmanaging sensitive data on a NixOS system.
What Does “World-Readable” Mean?
\nAll files in /nix/store are readable by any user on the system.
\nThis is by design, the nix store is intended to be shared, immutable store of\nall packages and configuration files.
\nPermissions are typically set to r-xr-xr-x(read and execute for everyone)
Security Implications
\nNever store secrets or sensitive data in plane text in the Nix store.
\nIf you include secrets directly in your configuration, they will end up in the\n/nix/store and be accessible to any user or process on the system.
This applies to files, environment variables, and any data embedded in\nderivations.
\nBest Practices
\nAlways use a secrets management tool (like sops-nix or agenix) that\ndecrypts secrets at activation time and stores them outside the Nix store,\nwith restricted permissions.
Do not embed secrets directly in Nix expressions or configuration files that\nwill be build into the store.
\nEven hashed passwords can be vulnerable when stored in a public repository, be\nconscious of what you store where.
\nIf you’re unsure about what’s safe to share, start with a private repository.\nThis gives you time to learn about secrets management and review your\nconfiguration before making anything public.
\nFirst, I’ll briefly explain some of the limitations of NixOS Rollbacks and then\nI’ll go into how Git compliments them.
\nNixOS is famous for its ability to roll back to previous system generations,\neither from the boot menu or with commands like nixos-rebuild --rollback.
When you perform rollbacks in NixOS, whether from the boot menu or using\ncommands like nixos-rebuild --rollback only the contents and symlinks managed\nby the Nix store are affected. The rollback works by switching which system\ngeneration is active, atomically updating symlinks to point to the previous\nversion of all packages, systemd units and services stored in /nix/store.
However, it’s important to understand what these rollbacks actually do and what\nthey don’t do. What NixOS Rollbacks Cover
\nSystem generations: When you rebuild your system, NixOS creates a new\n“generation” that you can boot into or roll back to. This includes all\npackages, services, and system configuration managed by Nix.
\nQuick recovery: If an upgrade breaks your system, you can easily select an\nolder generation at boot and get back to a working state
\nKey Limitations:
\nConfiguration files are not reverted: Rolling back only changes which\nsystem generation is active, it does not revert your actual configuration\nfiles (like configuration.nix or your flake files)
User data and service data are not rolled back: Only files managed by Nix\nare affected. Databases, user files, and other persistent data remain\nunchanged, which can cause problems if, for example, a service migrates its\ndatabase schema during an upgrade
\nManual changes persist: Any manual edits to configuration files or system\nstate outside of Nix are not reverted by a rollback
\nThe gh-cli,\nsimplifies quite a few things for working with GitHub from the command line.
\nTracks every configuration change: By version-controlling your NixOS\nconfigs with Git, you can easily see what changed, when, and why.
\nTrue config rollback: If a configuration change causes issues, you can use\ngit checkout or git revert to restore your config files to a previous good\nstate, then rebuild your system
Safer experimentation: You can confidently try new settings or upgrades,\nknowing you can roll back both your system state (with NixOS generations) and\nyour config files (with Git).
\nCollaboration and backup: Git lets you share your setup, collaborate with\nothers, and restore your configuration if your machine is lost or damaged.
\nIn summary: NixOS rollbacks are powerful for system state, but they don’t manage\nyour configuration file history. Git fills this gap, giving you full control and\ntraceability over your NixOS configs making your system both robust and truly\nreproducible. Version control is a fundamental tool for anyone working with\nNixOS, whether you’re customizing your desktop, managing servers, or sharing\nyour configuration with others. Git is the most popular version control system\nand is used by the NixOS community to track, share, and back up system\nconfigurations.
\nWhy use Git with NixOS?
\nTrack every change: Git lets you record every modification to your\nconfiguration files, so you can always see what changed, when, and why.
\nExperiment safely: Try new settings or packages without fear—if something\nbreaks, you can easily roll back to a previous working state.
\nSync across machines: With Git, you can keep your NixOS setups in sync\nbetween your laptop, desktop, or servers, and collaborate with others.
\nDisaster recovery: Accidentally delete your config? With Git, you can\nrestore it from your repository in minutes.
\nInstalling Git on NixOS
\nYou can install Git by adding it to your system packages in your\nconfiguration.nix or via Home Manager:
\nIf you develop good git practices on your own repositories it will make it\neasier to contribute with others as well as get help from others.
\nAtomic commits are a best practice in Git where each commit represents a\nsingle, focused, and complete change to the codebase. The main characteristics\nof atomic commits are:
\nOne purpose: Each commit should address only one logical change or task.
\nComplete: The commit should leave the codebase in a working state.
\nDescriptive: The commit message should be able to clearly summarize the\nchange in a single sentence.
\nWhy Atomic Commits Matter
\nEasier debugging: You can use tools like git bisect to quickly find\nwhich commit introduced a bug, since each commit is isolated.
Simpler reverts: You can revert without affecting unrelated changes.
\nBetter collaboration: Code reviews and merges are more manageable when\nchanges are small and focused.
\nWhen you lump together a bunch of changes into a single commit it can lead to\nquite a few undesirable consequences. They make it harder to track down bugs,\nit’s more difficult to revert undesired changes without reverting desired ones,\nmake larger tickets harder to manage.
\nEvery time a logical component is completed, commit it. Smaller commits make\nit easier for other devs and yourself to understand the changes and roll them\nback if necessary. This also makes it easier to share your code with others to\nget help when needed and makes merge conflicts less frequent and complex.
\nFinish the component, then commit it: There’s really no reason to commit\nunfinished work, use git stash for unfinished work and git commit for when\nthe logical component is complete. Use common sense and break complex components\ninto logical chunks that can be finished quickly to allow yourself to commit\nmore often.
Write Good Commit Messages: Begin with a summary of your changes, add a line\nof whitespace between the summary and the body of your message. Make it clear\nwhy this change was necessary. Use consistent language with generated messages\nfrom commands like git merge which is imperative and present tense\n(<<change>>, not <<changed>> or <<changes>>).
Squashing limits the benefits of atomic commits as it combines them all into a\nsingle commit as if you didn’t take the time to write them all out atomically.
\n🧠 Why Rebasing Wins for Linear History
\nNo Merge Bubbles: Rebasing avoids those extra merge commits that clutter\ngit log --graph. You get a clean, readable timeline.
Atomic Commit Integrity: Each commit stands alone and tells a story. Rebasing\npreserves that narrative without diluting it with merge noise.
\nBetter Blame & Bisect: Tools like git blame and git bisect work best when\nhistory is linear and logical.
\nTime-Travel Simplicity: Cherry-picking or reverting is easier when commits\naren’t tangled in merge commits.
\nBy default, when you run git pull git merges the commits into your local repo.\nTo change this to a rebase you can set the following:
git config --global pull.rebase true\ngit config --global rebase.autoStash true\ngit config --global fetch.prune true # auto delets remote-tracking branches that no longer exist\ngit config --global pull.ff only # blocks merge pulls\nNote: With pull.ff only pulls will fail if they would have had to merge. This\ncould happen if your local branch has diverged from the remote (e.g., someone\npushed new commits and you also committed locally) git pull will throw an\nerror like:
fatal: Not possible to fast-forward, aborting.\nHow to fix it
\nYou basically do what Git won’t auto-do:
\ngit fetch origin\ngit rebase origin/main\nThis rewinds your local commits, applies remote commits, and replays yours on\ntop, keeping the history linear.
\nIf you don’t care about your local changes and want to discard them you can use\nthe following command:
\ngit reset --hard origin/main\nThis just makes your branch identical to the remote, no rebase required. This\nprevents rogue merge commits, preserving atomic commits and linear logs.
\nYou could set an alias for this with:
\ngit config --global alias.grs '!git fetch origin && git rebase origin/main'\nTo check whether a setting is active or now you can use:
\ngit config --get rebase.autoStash\ntrue\nTo set these options with home-manager:
\n# ... snip ...\n extraConfig = lib.mkOption {\n type = lib.types.attrs;\n default = {\n commit.gpgsign = true;\n gpg.format = \"ssh\";\n user.signingkey = \"/etc/ssh/ssh_host_ed25519_key.pub\";\n extraConfig = {\n pull = {\n rebase = true;\n ff = \"only\";\n };\n };\n rebase = {\n autoStash = true; # Auto stashes and unstashes local changes during rebase\n };\n fetch = {\n prune = true; # Automatically deletes remote-tracking branches that no longer exist\n };\n# ... snip ...\nView an old commit:
\ngit checkout <commit_hash>\nThis puts you in a “detached HEAD” state, letting you explore code as it was at\nthat commit. To return, checkout your branch again.
\nGo back and keep history (revert):
\ngit revert <commit_hash>\nGo back and rewrite history (reset):
\ngit reset --soft <commit_hash>\ngit reset <commit_hash>\ngit reset --hard <commit_hash>\nUse the above command with caution, it can delete commits from history.
\ngit reset --hard HEAD@{5.minutes.ago}\nor
\ngit reset --hard HEAD@{yesterday}\nCreate a branch from the past:
\ngit checkout -b <new-brach> <commit_hash>\nThis starts a new branch from any previous commit, preserving current changes.
\nSome repositories have guidelines, such as Nixpkgs:
\nCommit conventions
\nCreate a commit for each logical unit.
\nCheck for unnecessary whitespace with git diff --check before committing.
If you have commits pkg-name: oh, forgot to insert whitespace: squash commits\nin this case. Use git rebase -i. See Squashing Commits for additional\ninformation.
For consistency, there should not be a period at the end of the commit\nmessage’s summary line (the first line of the commit message).
\nWhen adding yourself as maintainer in the same pull request, make a separate\ncommit with the message maintainers: add <handle>. Add the commit before\nthose making changes to the package or module. See Nixpkgs Maintainers for\ndetails.
Make sure you read about any commit conventions specific to the area you’re\ntouching. See: Commit conventions for changes to pkgs. Commit conventions\nfor changes to lib. Commit conventions for changes to nixos. Commit\nconventions for changes to doc, the Nixpkgs manual.
Writing good commit messages
\nIn addition to writing properly formatted commit messages, it’s important to\ninclude relevant information so other developers can later understand why a\nchange was made. While this information usually can be found by digging code,\nmailing list/Discourse archives, pull request discussions or upstream changes,\nit may require a lot of work.
\nPackage version upgrades usually allow for simpler commit messages, including\nattribute name, old and new version, as well as a reference to the relevant\nrelease notes/changelog. Every once in a while a package upgrade requires more\nextensive changes, and that subsequently warrants a more verbose message.
\nPull requests should not be squash merged in order to keep complete commit\nmessages and GPG signatures intact and must not be when the change doesn’t make\nsense as a single commit.
\nA Git workflow is a recipe or recommendation for how to use Git to\naccomplish work in a consistent and productive manner. Having a defined workflow\nlets you leverage Git effectively and consistently. This is especially important\nwhen working on a team.
\nOrigin is the default name (alias) for the remote repository that your\nlocal repository is connected to, usually the one you cloned from.
\nRemote Repositories are versions of your project that are hosted on the\ninternet or network somewhere.
\nWhen you run git push origin main, you’re telling Git to push your changes\nto 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\nto a different remote repo. Each of which is generally either read-only or\nread/write for you. Collaborating involves managing these remotes and pushing\nand pulling data to and from them when you need to share work.
\n\n❗ You can have a remote repo on your local machine. The word “remote” doesn’t\nimply that the repository is somewhere else, only that it’s elsewhere.
\n
origin is just a convention, it’s not special. It is automatically\nset when you clone a repo.Local is your local copy of the repository, git tracks the differences\nbetween local and remote which is a repo hosted elsewhere (e.g., GitHub\nGitLab etc.)
\nThe Upstream in Git typically refers to the original repository from which\nyour local repository or fork was derived. The Upstream is the remote repo\nthat serves as the main source of truth, often the original project you forked\nfrom. You typically fetch changes from upstream to update your local repo with\nthe latest updates from the original project, but you don’t push to upstream\nunless you have write access.
\nIf you haven’t already created a Git repo in your NixOS config directory (for\nexample, in your flake or /etc/nixos):
cd ~/flake\ngit init\ngit add .\ngit commit -m \"Initial commit: NixOS Configuration\"\nTaking this initial snapshot with Git is a best practice—it captures the exact\nstate of your working configuration before you make any changes.
\nThe command git add . stages all files in the directory (and its\nsubdirectories) for commit, meaning Git will keep track of them in your\nproject history.
The command git commit -m \"message\" then saves a snapshot of these staged\nfiles, along with your descriptive message, into the repository.
git add and saving with\ngit commit is at the heart of how Git tracks and manages changes over\ntime.Now that you’ve saved a snapshot of your working configuration, you’re free to\nexperiment and try new things, even if they might break your setup.
\nSuppose you want to try a new desktop environment, like Xfce. You edit your\nconfiguration.nix to add:
services.xserver.desktopManager.xfce.enable = true;\nYou run:
\nsudo nixos-rebuild switch # if configuration.nix is in /etc/nixos/\nBut something goes wrong: the system boots, but your desktop is broken or won’t\nstart. You decide to roll back using the boot menu or:
\nsudo nixos-rebuild switch --rollback\nWhat happens?
\nYour system reverts to the previous working generation in /nix/store
But: Your configuration.nix file is still changed, it still has the line\nenabling Xfce. If you rebuild again, you’ll get the same broken system,\nbecause your config itself wasn’t rolled back.
How does Git Help on Failure?
\nGit gives you quite a few options and ways to inspect what has been done.
\nUse git status to see what’s changed, and git checkout -- <file> to\nrestore any file to its last committed state.
Review your changes with git diff to see exactly what you modified before\ndeciding whether to keep or revert those changes.
Reset everything with git reset --hard HEAD, this will discard all local\nchanges and return to your last commit.
With Git you can simply run:
\ngit checkout HEAD~1 configuration.nix\n# or, if you committed before the change:\ngit revert <commit-hash>\nShow the full hash of the latest commit:
\ngit rev-parse HEAD\nf53fef375d89496c0174e70ce94993d43335098e\nShort hash:
\ngit log --pretty=format:'%h' -n 1\nf53fef3\ngit revert f53fef3\nShow a list of Recent commits:
\ngit log\n# a list of all commits, with hashes, author, date, and message\ngit log --oneline\ngit log --oneline\nf53fef3 (HEAD -> main) thunar\nb34ea22 thunar\n801cbcf thunar\n5e72ba5 sops\n8b67c59 sops\n1a353cb sops\nYou can copy the commit hash from any of these and use it in commands like\ngit checkout <hash> or git revert <hash>.
Commit successful experiments
\ngit add .\n# or more specifically the file you changed or created\ngit add configuration.nix\ngit commit -m \"Describe the new feature or fix\"\nWith Git you’re always on a branch and the default branch is master. Many\nchange it to main because of the suggestion Git gives you. I think people are\ntoo easily offended these days, just keep this in mind that main and master\nrefer to the main development branch.
You can get a listing of your current branches with:
\ngit branch\n* (no branch)\n main\nThe * is next to the current branch and is where the HEAD is currently\npointing. It says (no branch) because I’m currently in detached HEAD where\nHEAD points to no branch. The reason for this is because I’ve been trying out\nJujutsu 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\nchanges and commit them, and you can discard any commits you make\nin this state without impacting any branch by switching back.\n\nIf you want to create a new branch to retain commits you create,\nyou can do so now (using 'git switch -c <new-branch-name>') or\nlater (using 'git branch <new-branch-name> <commit-id>').\n\nSee 'git help switch' for details.\nTo attach the HEAD (i.e., have the pointer pointing to a branch), use the\ngit checkout command
git checkout main\nSwitched to branch 'main'\ngit branch\n* main\n# Ensure that you have the latest \"tip\" from the remote repository `origin`\ngit fetch origin main\nFrom github.com:sayls8/flake\n * branch main -> FETCH_HEAD\nAlthough we’re working on our own repo and there is basically no chance of our\nlocal branch diverging from our remote, it’s still good to get in the practice\nof getting everything in sync before merging or rebasing etc.
\ngit fetch doesn’t update main, it just updates your references. To update\nmain you would use git pull origin/main or git rebase origin/main
You can inspect your upstream branches with the following command:
\ngit remote show origin\n* remote origin\n Fetch URL: git@github.com:saylesss88/flake.git\n Push URL: git@github.com:saylesss88/flake.git\n HEAD branch: main\n Remote branch:\n main tracked\n Local ref configured for 'git push':\n main pushes to main (fast-forwardable)\n* branch main -> FETCH_HEAD: This line signifies that the main\nbranch from the remote repository (likely origin) was successfully fetched,\nand the commit ID of its current tip (its latest commit) is now stored in your\nlocal FETCH_HEAD reference.
Now that we know our local main is up to date with our remote origin/main we\ncan safely create a new feature branch:
git checkout -b feature/prose_wrap\nSwitched to a new branch 'feature/prose_wrap'\nRight now the branch feature/prose_wrap is exactly the same as main and we\ncan safely make changes without affecting main. We can try crazy or even\n“dangerous” things and always be able to revert to a working state with\ngit 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\npoint the HEAD to main and then either merge or rebase the feature branch\ninto main:
git checkout main\ngit fetch origin main\ngit merge feature/prose_wrap\nUpdating c8bd54c..b281f79\nFast-forward\n home/editors/helix/default.nix | 69 +++++++++++++++++++++++++++++++--------------------------------------\n 1 file changed, 31 insertions(+), 38 deletions(-)\nfeature/prose_wrap branch was directly ahead\nof the last commit on main. When you merge one commit with another commit\nthat can be reached by following the first commits history, remember the\nfeature branch is exactly the same as main until I made another commit. If\nthe branches diverged more and the history can’t be followed, Git will perform\na 3-way merge where it creates a new “merge commit” that combines the 2\nchanges.If you have a bunch of branches and forget which have been merged yet use:
\ngit branch --merged\nfeature/prose_wrap\n* main\n# OR to see branches that haven't been merged use:\ngit branch --no-merged\nIt’s now safe to delete the feature branch:
\ngit branch -d feature/prose_wrap\nDeleted branch feature/prose_wrap (was b281f79)\n\n\n❗ TIP: If your feature branch has a lot of sloppy commits that won’t be of\nmuch benefit to anyone, squash them first then merge. The workflow would look\nsomething like this:
\n\n# Make sure you're on the main branch\n git checkout main\n\n # Merge the feature branch with squash\n git merge --squash feature/prose_wrap\n\n
\n- This combines all the commits in your branch and adds them to your
\nmain\nstaging area, it doesn’t move HEAD or create a merge commit for you. To\napply the changes into one big commit, finalize it with:\ngit commit -m \"Add prose wrapping feature\"\nThis is often referred to as the “squash commit”.
\n
Branching means to diverge from the main line of development and continue to do\nwork without risking messing up your main branch. There are a few commits on\nyour main branch so to visualize this it would look something like this, image\nis from Pro Git:
\n\nLet’s say you haven’t ran nix flake update in a while and you don’t want to\nintroduce errors to your working configuration. To do so we can first, make sure\nwe don’t lose any changes on our main branch:
git add .\ngit commit -m \"Staging changes before switching branches\"\n# I always like to make sure the configuration will build before pushing to git\nsudo nixos-rebuild switch --flake .\n# If everything builds and looks correct\ngit push origin main\nOR, if you have incomplete changes that you don’t want to commit yet you can\nstash them with git stash:
git status\nOn branch main\nYour branch is ahead of 'origin/main' by 1 commit.\n (use \"git push\" to publish your local commits)\n\nChanges not staged for commit:\n (use \"git add <file>...\" to update what will be committed)\n (use \"git restore <file>...\" to discard changes in working directory)\n modified: home/git.nix\n\nno changes added to commit (use \"git add\" and/or \"git commit -a\")\nNow we want to switch branches, without committing the incomplete changes to\ngit.nix:
git stash\nSaved working directory and index state WIP on main: 0e46d6b git: lol alias\n\ngit status\nOn branch main\nYour branch is ahead of 'origin/main' by 1 commit.\n (use \"git push\" to publish your local commits)\n\nnothing to commit, working tree clean\n\n\n❗
\ngit stashis equivalent togit stash push
To see which stashes you have stored, use git sash list:
git stash list\nstash@{0}: WIP on main: 0e46d6b git: lol alias\nTo apply the most recent stash:
\ngit stash apply\ngit add home/git.nix\nOn branch main\nYour branch is ahead of 'origin/main' by 1 commit.\n (use \"git push\" to publish your local commits)\n\nChanges not staged for commit:\n (use \"git add <file>...\" to update what will be committed)\n (use \"git restore <file>...\" to discard changes in working directory)\n modified: home/git.nix\n\n# or for multiple stashes\ngit stash apply stash@{2}\nRunning git stash apply applies the changes that were in your stash but\ndoesn’t automatically restage them, to apply the changes and stage them in one\ncommand:
git stash apply --index\nNow let’s create our branch so we can safely update:
\ngit checkout -b update-test\nSwitched to a new branch 'update-test'\n-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\nkept it short for the example. Or if your company uses an issue tracker,\nincluding the ticket number in the branch name can be helpful:\nupdate/123-flake-inputs
The above command is equivalent to:
\ngit branch update-test\ngit checkout update-test\nNow our branches would look something like this, note how both branches\ncurrently point to the same commit: I discovered that Git Book has pretty\nrestrictive licensing and will eventually find a replacement.
Now, lets run our update:
\nnix flake update\nsudo nixos-rebuild test --flake .\n# If everything looks ok let's try applying the changes\nsudo nixos-rebuild switch --flake .\n# And if everything looks ok:\ngit add .\ngit commit -m \"feat: Updated all flake inputs\"\ngit push origin update-test\n\n\n❗ This is the same workflow for commiting a PR. After you first fork and\nclone the repo you want to work on, you then create a new feature branch and\npush to that branch on your fork. This allows you to create a PR comparing\nyour changes to their existing configuration.
\n
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\nupdate-test into it:
git checkout main\ngit merge origin/update-test\ngit branch -D update-test\nsudo nixos-rebuild test --flake .\nsudo nixos-rebuild switch --flake .\nIt’s good practice to delete a branch after you’ve merged and are done with it.
\nTo combine two seperate branches into one unified history you typically use\ngit merge or git rebase.
git merge takes two commit pointers and finds a common base commit between\nthem, 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.
The following example is the git.nix from the hydenix project it shows some\ncustom options and a way to manage everything from a single location:
# git.nix from hydenix: declarative Git configuration for Home Manager\n{ lib, config, ... }:\n\nlet\n cfg = config.hydenix.hm.git;\nin\n{\n\n options.hydenix.hm.git = {\n enable = lib.mkOption {\n type = lib.types.bool;\n default = config.hydenix.hm.enable;\n description = \"Enable git module\";\n };\n\n name = lib.mkOption {\n type = lib.types.nullOr lib.types.str;\n default = null;\n description = \"Git user name\";\n };\n\n email = lib.mkOption {\n type = lib.types.nullOr lib.types.str;\n default = null;\n description = \"Git user email\";\n };\n };\n\n config = lib.mkIf cfg.enable {\n\n programs.git = {\n enable = true;\n userName = cfg.name;\n userEmail = cfg.email;\n extraConfig = {\n init.defaultBranch = \"main\";\n pull.rebase = false;\n };\n };\n };\n}\n\n\n❗ You can easily change the name of the option, everything after
\nconfig.is\ncustom. So you could change it to for example,config.custom.gitand you\nwould enable it withcustom.git.enable = true;in yourhome.nixor\nequivalent.
Then he has a hm/default.nix with the following to enable it.
#...snip...\n\n # hydenix home-manager options go here\n hydenix.hm = {\n #! Important options\n enable = true;\n git = {\n enable = true; # enable git module\n name = null; # git user name eg \"John Doe\"\n email = null; # git user email eg \"john.doe@example.com\"\n };\n }\n\n # ... snip ...\nYou can enable git, and set your git username as well as git email right here.
\n![\"Nu\"](\"https://saylesss88.github.io/images/nu.png\")
TL;DR:I recently switched default shells from zsh to nushell, this post is\nabout some of the challenges and advantages of using nushell with NixOS.
\nWhile the average user might not immediately see significant advantages, those\nwho frequently work with structured data formats like JSON, YAML, and CSV –\nsuch as developers interacting with APIs, system administrators managing\nconfigurations, and data professionals – will likely find Nushell’s native\ndata handling and powerful pipeline capabilities a plus. Additionally, users\nwho value a more consistent and safer scripting experience might appreciate\nNushell’s language-first design and features like strong typing.
\nI’ll start with some of the unique build design choices and unique features\nthat I think make Nushell special, then show an example using Nushell to\nmanipulate JSON data. Finally, I will highlight some of the visually appealing\naspects of Nushell and lastly I share some resources for learning more.
\nNushell borrows concepts from many shells and languages and is itself both a\nprogramming language and a shell. Because of this, it has its own way of\nworking with files, directories, websites, and more.
\nNushell is powerful and has many essential commands built directly into the\nshell (“internal” commands) rather than a link to an executable. You can use\nthis set of commands across different operating systems, having this\nconsistency is helpful when creating cross-platform code.
\nWhen internal Nushell commands (like ls, open, where, get, sort-by,\netc.) produce output, they generally do so in Nushell’s structured data format\n(tables or records). This is the shell’s native way of representing\ninformation.
Beyond these foundational strengths, Nushell offers a range of unique features\nthat enhance its functionality and make it particularly well-suited for\ndata-heavy tasks. Here are some highlights that showcase its versatility.
\nSome Unique Features:
\nBesides the built-in commands, Nushell has a\nstandard library Nushell\noperates on structured data. You could call it a “data-first” shell and\nprogramming language.
\nAlso included, is a full-featured dataframe processing engine using\nPolars if you want to process large data\nefficiently directly in your shell, check out the\nDataframes-Docs
\nMulti-Line Editing:
\nWhen writing a long command you can press Enter to add a newline and move to\nthe next line. For example:
\nls | # press enter\nwhere name =~ | # press enter, comments after pipe ok\nget name | # press enter\nmv ...$in ./backups/\nThis allows you to cycle through the entire multi-line command using the up\nand down arrow keys and then customize different lines or sections of the\ncommand.
\nYou can manually insert a newline using Alt+Enter or Shift+Enter.
The Reedline-Editor is\npowerful 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\nnu’s version of a table pager, just like less but for table structured data:
$nu | explore --peek\nWith the above command you can navigate with vim keybinds or arrow keys.
\nThese features demonstrate Nushell’s user-friendly interface, but what truly\nsets it apart is its underlying design as a structured data scripting\nlanguage. This “language-first” approach powers many of its distinctive\ncapabilities.
\n![\"explore\"](\"https://saylesss88.github.io/images/explore.png\")
Unique design:
\nFundamentally designed as a structured data scripting language: and then\nit acts as a shell on top of that foundation. This “language first” approach\nis what gives it many of its distinctive features and makes it a powerful\nscripting language. I reiterate this here because of the implications of this.\nA few of those features are:
\nPipelines of structured data: Unlike traditional shells that primarily\ndeal with plain text streams, Nushell pipelines operate on tables of\nstructured data. Each command can understand and manipulate this structured\ndata directly.
\nConsistent syntax: Its syntax is more consistent and predictable\ncompared to the often quirky syntax of Bash and Zsh, drawing inspiration\nfrom other programming languages.
\nStrong typing Nushell has a type system, which helps catch errors early\nand allows for more robust scripting.
\nFirst-class data types: It treats various data formats (like JSON, CSV,\nTOML) as native data types, making it easier to work with them. Because of\nthis, Nushell aims to replace the need for external tools like jq, awk,\nsed, cut, and even some uses of grep and curl.
Variables are Immutable by Default: Nushell’s commands are based on a\nfunctional-style of programming which requires immutability, sound familiar?
\nNushell’s Environment is Scoped: Nushell takes many design cues from\ncompiled languages, one is that languages should avoid global mutable state.\nShells have commonly used global mutation to update the environment, Nushell\nattempts to steer clear of this increasing reproducability.
\nSingle-use Environment Variables:
\nFOO=BAR $env.FOO\n# => BAR\nconfig.nu# config.nu\n$env.FOO = 'BAR'\nThese design principles make Nushell a powerful tool for scripting, but\nthey’re best understood through a hands-on example. Let’s see how Nushell’s\nstructured data capabilities shine in a common task: processing a JSON file.
\nExample: I wanted to provide a practical example to illustrate some of these\n“Good” features in action. And break it down for better understanding.
\nLet’s consider a common task: processing data from a JSON file. Imagine you\nhave a file containing a list of users with their names and ages. With\ntraditional shells, you’d likely need to rely on external tools like jq to\nparse and filter this data. However, Nushell can handle this directly within\nits own commands.
For this example you could create a test directory and move to it:
mkdir test ; cd test\nusers.json with the following contents:👇 users.json
\n[\n { \"name\": \"Alice\", \"age\": 25 },\n { \"name\": \"Bob\", \"age\": 30 },\n { \"name\": \"Charlie\", \"age\": 20 }\n]\nfilter.nu that first converts users.json into its\nown internal structured data format with the open command, then to filters\nout people under 21 with the where control flow construct, then selects\nthe name and age columns, sorts them by age, and finally converts them\nback to json and saves them to a file called filtered_users.json. A lot\nhappening in a 6 line script.# filter.nu\nopen users.json # Read JSON file into structured data\n| where age > 21 # Filter users older than 21\n| select name age # Select only name and age columns\n| sort-by age # Sort by age\n| to json # Convert back to JSON\n| save filtered_users.json # Save result to a new file\nopen command takes data from a file (or even a URL in some cases) and\nparses it and converts it into Nushells own internal structured data format.\nSo this command isn’t just showing you the contents of users.json but doing\na conversion to Nu’s special structured format.open users.json\n╭───┬─────────┬─────╮\n│ # │ name │ age │\n├───┼─────────┼─────┤\n│ 0 │ Alice │ 25 │\n│ 1 │ Bob │ 30 │\n│ 2 │ Charlie │ 20 │\n╰───┴─────────┴─────╯\nsource command in Nushell is used to execute the commands within a\nscript file (like filter.nu) in the current Nushell environment. It’s\nsimilar to running the script directly in the shell, but keeps the shell open\nfor further use. In this example, source filter.nu runs the commands inside\nfilter.nu, processing the users.json file and creating the\nfiltered_users.json file:source filter.nu\n# View the contents with bat\nbat filtered_users.json\n───────┬──────────────────────────────────────────────────────────────────────────────────────\n │ File: filtered_users.json\n───────┼──────────────────────────────────────────────────────────────────────────────────────\n 1 │ [\n 2 │ {\n 3 │ \"name\": \"Alice\",\n 4 │ \"age\": 25\n 5 │ },\n 6 │ {\n 7 │ \"name\": \"Bob\",\n 8 │ \"age\": 30\n 9 │ }\n 10 │ ]\n───────┴───────────────────────────────────────────────────────────────────────────────────\nIn the filter.nu example:
\n# filter.nu\nopen users.json # Read JSON file into structured data\n| where age > 21 # Filter users older than 21\n| select name age # Select only name and age columns\n| sort-by age # Sort by age\n| to json # Convert back to JSON\n| save filtered_users.json # Save result to a new file\nopen users.json: Produces a Nushell table representing the data.
| where age > 21: Receives the table, filters rows based on the age\ncolumn, and outputs a new, filtered table.
| select name age: Receives the filtered table, selects only the name and\nage columns, and outputs a table with fewer columns.
| sort-by age: Receives the table, sorts the rows based on the age\ncolumn, 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\nthrough the Nushell pipeline is richer and more structured, enabling more\npowerful and direct data manipulation.
\nWhile Nushell’s strengths, like its structured data pipelines, make it a\ngame-changer for many tasks, it’s not without its challenges, especially when\nintegrated with NixOS’s Bash-centric ecosystem. Let’s explore some of the\nlimitations you might encounter when adopting Nushell as your default shell.
\nWhile the project is still maturing, the active community and ongoing\nimprovements are promising. Don’t get too discouraged by the following, there\nwould be a bad section for any shell imo.
\nThere are many similarities so it can be easy to forget that some Bash (and\nPOSIX in general) style constructs just won’t work in Nushell. Considering\nthat NixOS seems to have been designed for bash, even Zsh isn’t fully\ncompatable you may want to think twice before you choose Nushell as your\ndefault.
\nThe documentation is incomplete and written by devs for devs imo, it is quite\na bit different from anything else I’ve seen so there is a bit of a learning\ncurve. Nushell is generally still considered to be in a stage where it might\nnot be the most seamless or trouble-free experience as a daily driver default\nshell for most users, especially on a system like NixOS known for its unique\napproach.
\nThe any-nix-shell project doesn’t\ninclude Nushell as with many others because of it’s lack of maturity.
\nThe following addition comes from Joey_McKur’s sugggestion, on mentioning the\njob command as one of the biggest criticisms against Nu because it doesn’t\nsupport background tasks. I should also note that Nushell’s team is aware of\nthese criticisms and actively working on improving job control.
Limited Feature Set Compared to Traditional Job Control:
\nLack of Full POSIX Job Control: Nushell’s job control doesn’t yet fully\nimplement all the features and signals defined by POSIX job control (e.g.,\nmore nuanced signal handling, stopped jobs). While it covers the basics, users\naccustomed to advanced Bash job control might find it lacking.
\nForegrounding Behavior: There have been criticisms about how foregrounding\njobs interacts with the terminal and potential issues with signal propagation.
\nOutput Handling Challenges:
\nInterleaved Output: Managing the output of multiple backgrounded jobs can\nsometimes be messy, with output from different jobs potentially interleaving\nin the terminal. While Nushell tries to handle this, it’s not always as clean\nas desired.
\nRedirection Complexity: Redirecting the input and output of backgrounded\njobs can be less straightforward than in Bash, sometimes requiring more\nexplicit handling.
\nIntegration with Pipelines:
\nError Reporting:
\nDifficult to Track Errors in Background Jobs: Identifying and debugging\nerrors in backgrounded jobs can be less direct than with foreground processes,\nand the job command’s output might not always provide sufficient information\nfor troubleshooting.
\nMany of Nushell’s challenges stem from its departure from traditional shell\nconventions, particularly those of Bash, which NixOS heavily relies on. To\nbetter understand these differences and how they impact your workflow, let’s\ncompare Nushell’s static, structured approach to Bash’s dynamic, text-based\nmodel.
\n| 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\nis equivalent to the following in bash:
\necho \"hello\" > output.txt\necho prefix, this\nis because Nushell has Implicit Return:\"Hello, World\" == (echo \"Hello, World\")\n# => true\nThe above example shows that the string, \"Hello, World\" is equivalent to the\noutput value from echo \"Hello, World\"
Every Command Returns a Value:
\nlet p = 7\nprint $p # 7\n$p * 6 # 42\nCtrl+t List Commands with carapace and fzf:
![\"nu4\"](\"https://saylesss88.github.io/images/nu4.png\")
Carapace\nCarapace-Bin Install:
The folling is showing tab completion, I typed hx fl<TAB>:
![\"nu9\"](\"https://saylesss88.github.io/images/nu9.png\")
Carapace man example:
![\"nu7\"](\"https://saylesss88.github.io/images/nu7.png\")
Custom Nushell Commands
\nMost of the following scripts come from the\nnu_scripts repo
\n# nix.nu\n# upgrade system packages\n# `nix-upgrade` or `nix-upgrade -i`\ndef nix-upgrade [\n flake_path: string = \"/home/jr/flake\", # path that contains a flake.nix\n --interactive (-i) # select packages to upgrade interactively\n]: nothing -> nothing {\n let working_path = $flake_path | path expand\n if not ($working_path | path exists) {\n echo \"path does not exist: $working_path\"\n exit 1\n }\n let pwd = $env.PWD\n cd $working_path\n if $interactive {\n let selections = nix flake metadata . --json\n | from json\n | get locks.nodes\n | columns\n | str join \"\\n\"\n | fzf --multi --tmux center,20%\n | lines\n # Debug: Print selections to verify\n print $\"Selections: ($selections)\"\n # Check if selections is empty\n if ($selections | is-empty) {\n print \"No selections made.\"\n cd $pwd\n return\n }\n # Use spread operator to pass list items as separate arguments\n nix flake update ...$selections\n } else {\n nix flake update\n }\n cd $pwd\n nh os switch $working_path\n}\nUsage:
\nnix-upgrade\n# or for individual packages\nnix-upgrade -i\n![\"nu5\"](\"https://saylesss88.github.io/images/nu5.png\")
ns command is designed to search for Nix packages using nix search and\npresent the results in a cleaner format, specifically removing the\narchitecture and operating system prefix that nix search often includes.def ns [\n term: string # Search target.\n] {\n\n let info = (\n sysctl -n kernel.arch kernel.ostype\n | lines\n | {arch: ($in.0|str downcase), ostype: ($in.1|str downcase)}\n )\n\n nix search --json nixpkgs $term\n | from json\n | transpose package description\n | flatten\n | select package description version\n | update package {|row| $row.package | str replace $\"legacyPackages.($info.arch)-($info.ostype).\" \"\"}\n}\nUsage:
\nns fzf<ENTER>\n![\"nu10\"](\"https://saylesss88.github.io/images/nu10.png\")
nufetch command:# `nufetch` `(nufetch).packages`\ndef nufetch [] {\n{\n\"kernel\": $nu.os-info.kernel_version,\n\"nu\": $env.NU_VERSION,\n\"packages\": (ls /etc/profiles/per-user | select name | prepend [[name];\n[\"/run/current-system/sw\"]] | each { insert \"number\" (nix path-info --recursive\n ($in | get name) | lines | length) | insert \"size\" ( nix path-info -S\n ($in | get name) | parse -r '\\s(.*)' | get capture0.0 | into filesize) | update\n \"name\" ($in | get name | parse -r '.*/(.*)' | get capture0.0 | if $in == \"sw\"\n {\"system\"} else {$in}) | rename \"environment\"}),\n\"uptime\": (sys host).uptime\n}\n}\n![\"nu1\"](\"https://saylesss88.github.io/images/nu1.png\")
duf command, I have mine aliased to df:![\"nu8\"](\"https://saylesss88.github.io/images/nu8.png\")
ps command:![\"ps\"](\"https://saylesss88.github.io/images/ps.png\")
nix-list-system command lists all installed packages:# list all installed packages\ndef nix-list-system []: nothing -> list<string> {\n ^nix-store -q --references /run/current-system/sw\n | lines\n | filter { not ($in | str ends-with 'man') }\n | each { $in | str replace -r '^[^-]*-' '' }\n | sort\n}\nUsage:
\nnix-list-system\n![\"nu6\"](\"https://saylesss88.github.io/images/nu6.png\")
just and justfiles come in, simplifying complex\nworkflows and bridging gaps in Nushell’s functionality.The following is my justfile that I keep right next to my flake.nix it\nsimplifies some commands and makes things work that weren’t working with\nnushell for my case, you’ll have to change it to match your configuration.\nIt’s not perfect but works for my use case, take whats useful and leave the\nrest.
You’ll first need to install just to make use\nof justfiles.
# nix shell nixpkgs#just nixpkgs#nushell\nset shell := [\"nu\", \"-c\"]\nflake_path := \"/home/jr/flake\"\nhostname := \"magic\"\nhome_manager_output := \"jr@magic\"\n\nutils_nu := absolute_path(\"utils.nu\")\n\ndefault:\n @just --list\n# Rebuild\n[group('nix')]\nfr:\n nh os switch --hostname {{hostname}} {{flake_path}}\n\n# Flake Update\n[group('nix')]\nfu:\n nh os switch --hostname {{hostname}} --update {{flake_path}}\n\n# Update specific input\n# Usage: just upp nixpkgs\n[group('nix')]\nupp input:\n nix flake update {{input}}\n# Test\n[group('nix')]\nft:\n nh os test --hostname {{hostname}} {{flake_path}}\n# Collect Garbage\n[group('nix')]\nncg:\n nix-collect-garbage --delete-old ; sudo nix-collect-garbage -d ; sudo /run/current-system/bin/switch-to-configuration boot\n\n[group('nix')]\ncleanup:\n nh clean all\n\njust![\"just\"](\"https://saylesss88.github.io/images/just2.png\")
So just fmt will run nix fmt.
A lot of the .nu files came from this repo by BlindFS:
modern-dot-files he\nuses Nix Darwin so there are a few changes for NixOS. I found this through\nthis_week_in_nu.
\nmy-nu-config\nIf you use this, you’ll need to change the first line of fzf.nu to the\nlocation of your config. You’ll also need to change the constants at the top\nof config.nu. These are my old dotfiles, I have recently updated and made\nsure this config is up to date with recent nushell changes. Also, change the\nlet flake_path = ($env.HOME | path join \"flake\") to your flake path.
The examples use this starship\nconfigAylur-dotfiles\nThe logic on the bottom enables starship for Nushell, Zsh, and Bash!
\nIf you wan’t to use my config you’ll have to enable the experimental-feature\npipe-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\nsomething to work i.e. nix-shell and a few others.
From custom commands to justfile integrations, Nushell offers a wealth of\ntools to enhance your NixOS experience, even if occasional workarounds are\nneeded. To dive deeper into Nushell and tailor it to your needs, here are some\nvaluable resources to explore, from official documentation to community-driven\nconfigurations.
nu_scripts some of the custom\ncommands came from here.
\ndiscord You can find custom commands,\nconfigurations, etc here.
\n![\"gruv10\"](\"https://saylesss88.github.io/images/gruv10.png\")
Nix’s build instructions, known as derivations, are defined using the Nix\nLanguage. These derivations can describe anything from individual software\npackages to complete system configurations. The Nix package manager then\ndeterministically “realizes” (builds) these derivations, ensuring consistency\nbecause they rely solely on a predefined set of inputs.
\nMost things in NixOS are built around derivations. Your NixOS system is\ndescribed by such a single system derivation. When you want to apply a new\nconfiguration, nixos-rebuild handles the process:
It first builds this derivation:
\nnix-build '<nixpkgs/nixos>' -A system\nThen, once the build is complete, it switches to that new system:
\nresult/bin/switch-to-configuration\nAfter the build, nixos-rebuild updates a crucial symbolic link:\n/run/current-system This symlink always points to the active, running version\nof your system in the Nix store. In essence, the /run/current-system path is\nthe currently active system derivation. This design choice gives NixOS its\npowerful atomic upgrade and rollback capabilities: changing your system involves\nbuilding a new system derivation and updating this symlink to point to the\nlatest version.
\n\n\nls -lsah /run/current-system\n 0 lrwxrwxrwx 1 root root 85 May 23 12:11 /run/current-system -> /nix/store/\n cy2c0kxpjrl7ajlg9v3zh898mhj4dyjv-nixos-system-magic-25.11.20250520.2795c50\n
The -> indicates a symlink and it’s pointing to a store path which is\nthe result of a derivation being built (the system closure)
For beginners, the analogy of a cooking recipe is helpful:
\nIngredients (Dependencies): What other software or libraries are needed.
\nSteps (Build Instructions): The commands to compile, configure, and\ninstall.
\nFinal Dish (Output): The resulting package or resource.
\nA Nix derivation encapsulates all this information, telling Nix what inputs to\nuse, how to build it, and what the final output should be.
\nNix derivations run in pure, isolated environments, meaning they\ncannot access the internet during the build phase. This ensures that builds\nare reproducible – they don’t depend on external sources that might change over\ntime.
\nThere are Fixed-output-derivations that allow fetching resources during the\nbuild process by explicitly specifying the expected hash upfront. Just keep this\nin mind that normal derivations don’t have network access.
The primary way to define packages in Nix is through the mkDerivation\nfunction, which is part of the standard environment (stdenv). While a\nlower-level derivation function exists for advanced use cases, mkDerivation\nsimplifies the process by automatically managing dependencies and the build\nenvironment.
mkDerivation (and derivation) takes a set of attributes as its argument. At\na minimum, you’ll often encounter these essential attributes:
name: A human-readable identifier for the derivation (e.g., “foo”,\n“hello.txt”). This helps you and Nix refer to the package.
\nsystem: Specifies the target architecture for the build (e.g.,\nbuiltins.currentSystem for your current machine).
builder: Defines the program that will execute the build instructions\n(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\nderivation and mkDerivation, this takes the form\nfunctionName { attribute1 = value1; attribute2 = value2; ... }, where the {}\nencloses the set of attributes being passed as the function’s argument.
Remember that derivation and mkDerivation take a set (i.e. {}) of\nattributes as its first argument. So, in order to pass the required attributes\nyou would do something like this:
nix-repl> pkgs = import <nixpkgs> {}\n\nnix-repl> d = derivation {\n name = \"mydrv\";\n builder = \"${pkgs.bash}/bin/bash\";\n args = [\n \"-c\" # Tells bash to execute the following string as a command\n ''\n # Explicitly set PATH to include coreutils bin directory\n export PATH=\"${pkgs.coreutils}/bin:$PATH\"\n mkdir $out\n ''\n ];\n system = builtins.currentSystem;\n }\n\nnix-repl> :b d\nd = derivation { name = \"myname\"; builder = \"${coreutils}/bin/true\"; system = builtins.currentSystem; }\npkgs = import <nixpkgs> {};, you are importing the Nixpkgs\ndefault.nix file, which resolves to a function. Calling that function by\npassing it an empty attribute set {} as its argument. The function then\nevaluates and returns the entire pkgs attribute set. To specify a different\nsystem for example, you could do something like:pkgsForAarch64 = import <nixpkgs> { system = \"aarch64-linux\"; };\nSo when you see:
\nimport <nixpkgs> { overlays = []; config = {}; }\nInstead, these empty sets explicitly override any global or implicit\noverlays/configurations that Nix might otherwise pick up from environment\nvariables (like NIXPKGS_CONFIG), default locations (like\n~/.config/nixpkgs/config.nix or ~/.config/nixpkgs/overlays), or other\nmechanisms.
This is to prevent accidental partial application from other parts of your\nconfiguration and is saying “Do not pass any custom configuration options for\nthis particular import”
\nderivation is a pre-made, built-in function in the Nix language. Here, we\nare passing it an attribute set as argument with the three required\nattributes. (name, builder, system, and we added an extra argument\nargs.)
For this example, first create a hello directory and add the\nHello tarball to said\ndirectory.
Now lets create the classic Hello derivation:
\n# hello.nix\nlet\n pkgs = import <nixpkgs> { };\nin\nderivation {\n name = \"hello\";\n builder = \"${pkgs.bash}/bin/bash\";\n args = [ ./hello_builder.sh ];\n inherit (pkgs)\n gnutar\n gzip\n gnumake\n gcc\n coreutils\n gawk\n gnused\n gnugrep\n ;\n bintools = pkgs.binutils.bintools;\n src = ./hello-2.12.1.tar.gz;\n system = builtins.currentSystem;\n}\nhello package. The tar.gz package can be found\nhere You would just place\nthe tarball in the same directory as the derivation along with the following\nhello_builder.sh:# hello_builder.sh\nexport PATH=\"$gnutar/bin:$gcc/bin:$gnumake/bin:$coreutils/bin:$gawk/bin:$gzip/bin:$gnugrep/bin:$gnused/bin:$bintools/bin\"\ntar -xzf $src\ncd hello-2.12.1\n./configure --prefix=$out\nmake\nmake install\nAnd build it with:
\nnix-build hello.nix\nFinally execute it with:
\n./result/bin/hello\nHello, world!\nCreate a simple.rs with the following contents:
fn main() {\n println!(\"Simple Rust!\")\n}\nAnd a rust_builder.sh like this (this is our builder script):
# rust_builder.sh\n# Set up the PATH to include rustc coreutils and gcc\nexport PATH=\"$rustc/bin:$coreutils/bin:$gcc/bin\"\n\n# IMPORTANT: Create the $out directory BEFORE rustc tries to write to it\nmkdir -p \"$out\"\n\n# Compile the Rust source code and place the executable inside $out\nrustc -o \"$out/simple_rust\" \"$src\"\nNow we’ll enter the nix repl and build it:
❯ nix repl\nNix 2.28.3\nType :? for help.\n\nnix-repl> :l <nixpkgs>\nadded 3950 variables.\n\n# Define the variables for rustc, coreutils, bash, AND gcc from the loaded nixpkgs\nnix-repl> rustc = pkgs.rustc\n\nnix-repl> coreutils = pkgs.coreutils\n\nnix-repl> bash = pkgs.bash\n\nnix-repl> gcc = pkgs.gcc\n\n# Now define the derivation\nnix-repl> simple_rust_program = derivation {\n name = \"simple-rust-program\";\n builder = \"${bash}/bin/bash\";\n args = [ ./rust_builder.sh ];\n rustc = rustc;\n coreutils = coreutils;\n gcc = gcc;\n src = ./simple.rs;\n system = builtins.currentSystem;\n }\n\nnix-repl> :b simple_rust_program\nThis derivation produced the following outputs:\nout -> /nix/store/fmyqr2d3ph0lpnxd0xppwvwyhv3iyb7y-simple-rust-program\nnix-store -r /nix/store/fmyqr2d3ph0lpnxd0xppwvwyhv3iyb7y-simple-rust-program\n\nwarning: you did not specify '--add-root'; the result might be removed by the garbage collector\n/nix/store/fmyqr2d3ph0lpnxd0xppwvwyhv3iyb7y-simple-rust-program\nThis simple Rust example, built with a direct derivation call, illustrates:
\nHow Nix explicitly manages every single tool in your build environment\n(bash, rustc, gcc, coreutils).
The strict isolation of Nix builds, where nothing is implicitly available.
\nThe deterministic mapping of inputs to unique output paths in the Nix store.
\nThe above example shows the fundamental structure of a Nix derivation, how\nit’s defined within the nix-repl.
.drv files are intermediate files that describe how to build a derivation;\nit’s the bare minimum information.
Nix doesn’t build derivations during the evaluation of your Nix expressions.\nInstead, it processes your code in two main phases (and why you need to use\n: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\n.nix expression. The result is a precise derivation description (often\nrepresented as a .drv file on disk), and the unique “out paths” where the\nfinal built products will go are calculated. No actual code is compiled or\nexecuted yet. Achieved with nix-instantiate
Realize/Build Phase: Only after a derivation has been fully described does\nNix actually execute its build instructions. It first ensures all the\nderivation’s inputs (dependencies) are built, then runs the builder script\nin an isolated environment, and places the resulting products into their\ndesignated “out paths” in the Nix store. Achieved with nix-store -r
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\nthen convert the derivation set into a string:
nix repl\nnix-repl> :l <nixpkgs>\nnix-repl> fzf\n«derivation /nix/store/vw1zag9q4xvf10z24j1qybji7wfsz78v-fzf-0.62.0.drv»\nnix-repl> fzf.outPath\n\"/nix/store/z3ayhjslz72ldiwrv3mn5n7rs96p2g8a-fzf-0.62.0\"\nnix-repl> builtins.toString fzf\n\"/nix/store/z3ayhjslz72ldiwrv3mn5n7rs96p2g8a-fzf-0.62.0\"\noutPath attribute, Nix will do the “set to string\nconversion”.Building on the concept of a derivation as a recipe, let’s create our first\npractical derivation. This example shows how to define a temporary development\nenvironment (a shell) using stdenv.mkDerivation, which is the primary function\nfor defining packages in Nix.
\n# my-shell.nix\n# We use a `let` expression to bring `pkgs` and `stdenv` into scope.\n# This is a recommended practice over `with import <nixpkgs> {}`\n# for clarity and to avoid potential name collisions.\nlet\n pkgs = import <nixpkgs> {};\n stdenv = pkgs.stdenv; # Access stdenv from the imported nixpkgs\nin\n\n# Make a new \"derivation\" that represents our shell\nstdenv.mkDerivation {\n name = \"my-environment\";\n\n # The packages in the `buildInputs` list will be added to the PATH in our shell\n buildInputs = [\n # cowsay is an arbitrary package\n # see https://nixos.org/nixos/packages.html to search for more\n pkgs.cowsay\n pkgs.fortune\n ];\n}\nUsage
\nnix-shell my-shell.nix\nfortune | cowsay\n _________________________________________\n/ \"Lines that are parallel meet at \\\n| Infinity!\" Euclid repeatedly, heatedly, |\n| urged. |\n| |\n| Until he died, and so reached that |\n| vicinity: in it he found that the |\n| damned things diverged. |\n| |\n\\ -- Piet Hein /\n -----------------------------------------\n \\ ^__^\n \\ (oo)\\_______\n (__)\\ )\\/\\\n ||----w |\n || ||\nexitThis Nix expression defines a temporary development shell. Let’s break it down:
\npkgs = import <nixpkgs> {};: Standard way to get access to all the packages\nand helper functions (i.e. nixpkgs.lib)
stdenv = pkgs.stdenv;: stdenv provides us mkDerivation and is from the\nnixpkgs collection.
stdenv.mkDerivation { ... };: This is the core function for creating\npackages.
stdenv provides a set of common build tools and conventions.mkDerivation takes an attribute set (a collection of key-value pairs) as its\nargument.
name = \"my-environment\";: This gives your derivation a human-readable name.
buildInputs = [ pkgs.cowsay ];: This is a list of dependencies that will be\navailable in the build environment of this derivation (or in the PATH if you\nenter the shell created by this derivation). pkgs.cowsay refers to the\ncowsay package from the imported pkgs collection.
The command nix-instantiate --eval my-shell.nix evaluates the Nix expression\nin the file. It does not build the derivation. Instead, it returns the Nix value\nthat the expression evaluates to.
nix-instantiate --eval my-shell.nix\nThis value is a structured data type that encapsulates all the attributes (like\nname, system, buildInputs, etc.) required to build the derivation. Your\noutput shows this detailed internal representation of the derivation’s “recipe”\nas understood by Nix. This is useful for debugging and inspecting the\nderivation’s definition.
builder.builder attribute in a derivation tells Nix how to perform the build\nsteps. A simple and common way to define these steps is with a bash script.In typical Unix-like systems, you might start a bash script with a shebang\n(#!/bin/bash or #!/usr/bin/env bash) to tell the system how to execute it.\nHowever, in Nix derivations, we generally avoid this.
Reason: Nix builds happen in an isolated environment where the exact path\nto common tools like bash isn’t known beforehand (it resides within the Nix\nstore). Hardcoding a path or relying on the system’s PATH would break Nix’s\nstateless property.
Stateful Systems (Traditional): When you install software traditionally,\nit often modifies the core system environment directly. This can lead to\ndependency conflicts and makes rollbacks difficult.
\nStateless Systems (Nix): Nix takes a different approach. When installing a\npackage, it creates a unique, immutable directory in the Nix store. This\nmeans:
\nNo Conflicts: Different versions of the same package can coexist without\ninterfering with each other.
\nReliable Rollback: You can easily switch back to previous versions\nwithout affecting system-wide files.
\nReproducibility: Builds are more likely to produce the same result\nacross different machines if they are “pure” (don’t rely on external system\nstate).
\nWhen Nix executes a builder script, it sets up a highly controlled and pristine\nenvironment to ensure reproducibility and isolation. Here’s what\nhappens:
\nFresh Start: Nix creates a temporary, empty directory for the build and\nmakes it the current working directory.
\nClean Environment: It completely clears the environment variables from\nyour shell.
\nControlled Inputs: Nix then populates the environment with only the\nvariables essential for the build, such as:
\n$NIX_BUILD_TOP: The path to the temporary build directory.
$PATH: Carefully set to include only the explicit buildInputs you’ve\nspecified, preventing reliance on arbitrary system tools.
$HOME: Set to /homeless-shelter to prevent programs from reading\nuser-specific configuration files.
Variables for each declared output ($out, etc.), indicating where the\nfinal results should be placed in the Nix store.
Execution & Logging: The builder script is run with its specified\narguments. All its output (stdout/stderr) is captured in a log.
\nClean Up & Registration: If successful, the temporary directory is\nremoved. Nix then scans the build outputs for references to other store\npaths, ensuring all dependencies are correctly tracked for future use and\ngarbage collection. Finally, it normalizes file permissions and timestamps\nin the output for consistent hashing.
\nThis meticulous setup ensures that your builds are independent of the machine\nthey run on and always produce the same result, given the same inputs.
\nbuilder.sh file in the\ncurrent directory:# builder.sh\ndeclare -xp\necho foo > $out\nThe command declare -xp lists exported variables (it’s a bash builtin\nfunction).
Nix needs to know where the final built product (the “cake” in our earlier\nanalogy) should be placed. So, during the derivation process, Nix calculates a\nunique output path within the Nix store. This path is then made available to\nour builder script as an environment variable named $out. The .drv file,\nwhich is the recipe, contains instructions for the builder, including setting\nup this $out variable. Our builder script will then put the result of its\nwork (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\nexecutable, common way to do this is to load Nixpkgs into the repl and check:
\nnix-repl> :l <nixpkgs>\nAdded 3950 variables.\nnix-repl> \"${bash}\"\n\"/nix/store/ihmkc7z2wqk3bbipfnlh0yjrlfkkgnv6-bash-4.2-p45\"\nSo, with this little trick we are able to refer to bin/bash and create our\nderivation:
nix-repl> d = derivation { name = \"foo\"; builder = \"${bash}/bin/bash\";\n args = [ ./builder.sh ]; system = builtins.currentSystem; }\nnix-repl> :b d\n[1 built, 0.0 MiB DL]\n\nthis derivation produced the following outputs:\n out -> /nix/store/gczb4qrag22harvv693wwnflqy7lx5pb-foo\nThe contents of the resulting store path (/nix/store/...-foo) now contain\nthe file foo, as intended. We have successfully built a derivation!
Derivations are the primitive that Nix uses to define packages. “Package” is a\nloosely defined term, but a derivation is simply the result of calling\nbuiltins.derivation.
Create a new directory and a hello.nix with the following contents:
# hello.nix\n{\n stdenv,\n fetchzip,\n}:\n\nstdenv.mkDerivation {\n pname = \"hello\";\n version = \"2.12.1\";\n\n src = fetchzip {\n url = \"https://ftp.gnu.org/gnu/hello/hello-2.12.1.tar.gz\";\n sha256 = \"\";\n };\n}\nSave this file to hello.nix and run nix-build to observe the build failure:
$ nix-build hello.nix\n~error: cannot evaluate a function that has an argument without a value ('stdenv')\n~ Nix attempted to evaluate a function as a top level expression; in\n~ this case it must have its arguments supplied either by default\n~ values, or passed explicitly with '--arg' or '--argstr'. See\n~ https://nix.dev/manual/nix/stable/language/constructs.html#functions.\n~\n~ at /home/nix-user/hello.nix:3:3:\n~\n~ 2| {\n~ 3| stdenv,\n~ | ^\n~ 4| fetchzip,\nProblem: The expression in hello.nix is a function, which only produces\nit’s intended output if it is passed the correct arguments.(i.e. stdenv is\navailable from nixpkgs so we need to import nixpkgs before we can use\nstdenv):
The recommended way to do this is to create a default.nix file in the same\ndirectory as the hello.nix with the following contents:
# default.nix\nlet\n nixpkgs = fetchTarball \"https://github.com/NixOS/nixpkgs/tarball/nixos-24.05\";\n pkgs = import nixpkgs { config = {}; overlays = []; };\nin\n{\n hello = pkgs.callPackage ./hello.nix { };\n}\nThis allows you to run nix-build -A hello to realize the derivation in\nhello.nix, similar to the current convention used in Nixpkgs:
nix-build -A hello\n~error: hash mismatch in fixed-output derivation '/nix/store/pd2kiyfa0c06giparlhd1k31bvllypbb-source.drv':\n~ specified: sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=\n~ got: sha256-1kJjhtlsAkpNB7f6tZEs+dbKd8z7KoNHyDHEJ0tmhnc=\n~error: 1 dependencies of derivation '/nix/store/b4mjwlv73nmiqgkdabsdjc4zq9gnma1l-hello-2.12.1.drv' failed to build\nnix-prefetch-url https://ftp.gnu.org/gnu/hello/hello-2.12.1.tar.gz\npath is '/nix/store/pa10z4ngm0g83kx9mssrqzz30s84vq7k-hello-2.12.1.tar.gz'\n086vqwk2wl8zfs47sq2xpjc9k066ilmb8z6dn0q6ymwjzlm196cd\nnix-prefetch-url, you get a Base32 hash when nix needs SRI\nformat.Run the following command to convert from Base32 to SRI:
\nnix hash to-sri --type sha256 086vqwk2wl8zfs47sq2xpjc9k066ilmb8z6dn0q6ymwjzlm196cd\nsha256-jZkUKv2SV28wsM18tCqNxoCZmLxdYH2Idh9RLibH2yA=\nfetchzip automatically extracts archives before\ncomputing the hash and slight differences in the metadata cause different\nresults. I had to switch from fetchzip to fetchurl to get the correct\nresults.\nExtracted archives can differ in timestamps, permissions, or compression\ndetails, causing different hash values.
\nA simple takeaway is to use fetchurl when you need an exact match, and\nfetchzip when working with extracted contents.
fetchurl returns a fixed-output derivation(FOD): A derivation where a\ncryptographic hash of the output is determined in advance using the\noutputHash attribute, and where the builder executable has access to the\nnetwork.
Lastly replace the empty sha256 placeholder with the returned value from the\nlast command:
\n# hello.nix\n{\n stdenv,\n fetchzip,\n}:\n\nstdenv.mkDerivation {\n pname = \"hello\";\n version = \"2.12.1\";\n\n src = fetchzip {\n url = \"https://ftp.gnu.org/gnu/hello/hello-2.12.1.tar.gz\";\n sha256 = \"sha256-1kJjhtlsAkpNB7f6tZEs+dbKd8z7KoNHyDHEJ0tmhnc=\";\n };\n}\nRun nix-build -A hello again and you’ll see the derivation successfully\nbuilds.
Reproducible source paths: If we built the following derivation in\n/home/myuser/myproject then the store path of src will be\n/nix/store/<hash>-myproject causing the build to no longer be reproducible:
let pkgs = import <nixpkgs> {}; in\n\npkgs.stdenv.mkDerivation {\n name = \"foo\";\n src = ./.;\n}\n\n\n❗ TIP: Use
\nbuiltins.pathwith thenameattribute set to something fixed.\nThis will derive the symbolic name of the store path from thenameinstead\nof the working directory:\nlet pkgs = import <nixpkgs> {}; in\n\npkgs.stdenv.mkDerivation {\n name = \"foo\";\n src = builtins.path { path = ./.; name = \"myproject\"; };\n}\n
In this chapter, we’ve laid the groundwork for understanding Nix derivations,\nthe fundamental recipes that define how software and other artifacts are built\nwithin the Nix ecosystem. We’ve explored their key components – inputs, builder,\nbuild phases, and outputs – and how they contribute to Nix’s core principles of\nreproducibility and isolated environments. Derivations are the workhorses behind\nthe packages and tools we use daily in Nix.
\nAs you’ve learned, derivations offer a powerful and principled approach to\nsoftware management. However, the way we organize and manage these derivations,\nalong with other Nix expressions and dependencies, has evolved over time.\nTraditionally, Nix projects often relied on patterns involving default.nix\nfiles, channel subscriptions, and manual dependency management.
A more recent and increasingly popular approach to structuring Nix projects and\nmanaging dependencies is through Nix Flakes. Flakes introduce a standardized\nproject structure, explicit input tracking, and a more robust way to ensure\nreproducible builds across different environments.
\nIn our next chapter,\nComparing Flakes and Traditional Nix,\nwe will directly compare and contrast these two approaches. We’ll examine the\nstrengths and weaknesses of traditional Nix practices in contrast to the\nbenefits and features offered by Nix Flakes. This comparison will help you\nunderstand the motivations behind Flakes and when you might choose one approach\nover the other for your Nix projects.
\nAs you can see below, there is a ton of information on derivations freely\navailable.
\nSparky/blog-creatingASuperSimpleDerivation #\nHow to learn Nix
\nThe attribute inputs specifies the dependencies of a flake, as an attrset\nmapping input names to flake references.
If a repository provides a flake.nix you can include it as an input in your\nflake.nix.
For example, I like yazi as my file explorer and have been using helix as my\neditor. To be able to get yazi to work with helix I needed the latest versions\nof both yazi and helix. One way to get the latest versions was to add their\nflakes as inputs to my flake:
\n{\n\tinputs = {\n\t\tnixpkgs.url = \"github:NixOS/nixpkgs/nixos-24.11\";\n\t\thome-manager = {\n\t\t\turl = \"github:nix-community/home-manager/release-24.11\";\n\t\t\tinputs.nixpkgs.follows = \"nixpkgs\";\n\t\t};\n helix = {\n url = \"github:helix-editor/helix\";\n inputs.nixpkgs.follows = \"nixpkgs\";\n };\n\t\tyazi.url = \"github:sxyazi/yazi\";\n\t};\n\toutputs = { nixpkgs, home-manager, ... } @ inputs: {\n\t# ... snip ... #\n# yazi.nix\n{ pkgs, config, inputs, ... }: {\n\tprograms.yazi = {\n\t\tenable = true;\n\t\tpackage = inputs.yazi.packages.${pkgs.system}.default;\n\t};\n}\n# helix.nix\n{ pkgs, config, inputs, ... }: {\n\tprograms.helix = {\n\t\tenable = true;\n\t\tpackage = inputs.helix.packages.${pkgs.system}.helix;\n\t};\n}\nUnderstanding .default vs. Named Outputs (e.g., .helix) from the Source
The difference between inputs.yazi.packages.${pkgs.system}.default and\ninputs.helix.packages.${pkgs.system}.helix comes down to how the respective\nupstream flakes define their outputs. You can always inspect a flake’s\nflake.nix or use nix flake show <flake-reference> to understand its\nstructure.
flake.nixLet’s look at the relevant section of Helix’s flake.nix click the eye to see\nthe full flake:
~ {\n~ description = \"A post-modern text editor.\";\n~\n~ inputs = {\n~ nixpkgs.url = \"github:nixos/nixpkgs/nixos-unstable\";\n~ rust-overlay = {\n~ url = \"github:oxalica/rust-overlay\";\n~ inputs.nixpkgs.follows = \"nixpkgs\";\n~ };\n~ };\n~\n~ outputs = {\n~ self,\n~ nixpkgs,\n~ rust-overlay,\n~ ...\n~ }: let\n~ inherit (nixpkgs) lib;\n~ systems = [\n~ \"x86_64-linux\"\n~ \"aarch64-linux\"\n~ \"x86_64-darwin\"\n~ \"aarch64-darwin\"\n~ ];\n~ eachSystem = lib.genAttrs systems;\n~ pkgsFor = eachSystem (system:\n~ import nixpkgs {\n~ localSystem.system = system;\n~ overlays = [(import rust-overlay) self.overlays.helix];\n~ });\n~ gitRev = self.rev or self.dirtyRev or null;\n in {\n packages = eachSystem (system: {\n inherit (pkgsFor.${system}) helix;\n /*\n The default Helix build. Uses the latest stable Rust toolchain, and unstable\n nixpkgs.\n\n The build inputs can be overridden with the following:\n\n packages.${system}.default.override { rustPlatform = newPlatform; };\n\n Overriding a derivation attribute can be done as well:\n\n packages.${system}.default.overrideAttrs { buildType = \"debug\"; };\n */\n default = self.packages.${system}.helix;\n });\n~ checks =\n~ lib.mapAttrs (system: pkgs: let\n~ # Get Helix's MSRV toolchain to build with by default.\n~ msrvToolchain = pkgs.pkgsBuildHost.rust-bin.fromRustupToolchainFile ./rust-toolchain.toml;\n~ msrvPlatform = pkgs.makeRustPlatform {\n~ cargo = msrvToolchain;\n~ rustc = msrvToolchain;\n~ };\n~ in {\n~ helix = self.packages.${system}.helix.override {\n~ rustPlatform = msrvPlatform;\n~ };\n~ })\n~ pkgsFor;\n~\n~ # Devshell behavior is preserved.\n~ devShells =\n~ lib.mapAttrs (system: pkgs: {\n~ default = let\n~ commonRustFlagsEnv = \"-C link-arg=-fuse-ld=lld -C target-cpu=native --cfg tokio_unstable\";\n~ platformRustFlagsEnv = lib.optionalString pkgs.stdenv.isLinux \"-Clink-arg=-Wl,--no-rosegment\";\n~ in\n~ pkgs.mkShell {\n~ inputsFrom = [self.checks.${system}.helix];\n~ nativeBuildInputs = with pkgs;\n~ [\n~ lld\n~ cargo-flamegraph\n~ rust-bin.nightly.latest.rust-analyzer\n~ ]\n~ ++ (lib.optional (stdenv.isx86_64 && stdenv.isLinux) cargo-tarpaulin)\n~ ++ (lib.optional stdenv.isLinux lldb)\n~ ++ (lib.optional stdenv.isDarwin darwin.apple_sdk.frameworks.CoreFoundation);\n~ shellHook = ''\n~ export RUST_BACKTRACE=\"1\"\n~ export RUSTFLAGS=\"''${RUSTFLAGS:-\"\"} ${commonRustFlagsEnv} ${platformRustFlagsEnv}\"\n~ '';\n~ };\n~ })\n~ pkgsFor;\n~\n~ overlays = {\n~ helix = final: prev: {\n~ helix = final.callPackage ./default.nix {inherit gitRev;};\n~ };\n~\n~ default = self.overlays.helix;\n~ };\n~ };\n~ nixConfig = {\n~ extra-substituters = [\"https://helix.cachix.org\"];\n~ extra-trusted-public-keys = [\"helix.cachix.org-1:ejp9KQpR1FBI2onstMQ34yogDm4OgU2ru6lIwPvuCVs=\"];\n~ };\n~}\nDissecting inherit (pkgsFor.${system}) helix;
Imagine the Nix evaluation process for Helix flake.nix in the outputs\nsection:
packages = eachSystem (system: { ... }); Part iterates through each\nsystem (like x86_64-linux). For each system, it’s creating an attribute\nset that will become self.packages.${system}.
Inside the eachSystem function, for a specific system (e.g.\nx86_64-linux): The code is building an attribute set that will ultimately\nbe assigned to self.packages.x86_64-linux.
When you write inherit (sourceAttrset) attributeName;, it’s equivalent to\nwriting attributeName = sourceAttrset.attributeName;.
So, inherit (pkgsFor.${system}) helix; is equivalent to:
helix = pkgsFor.${system}.helix;\nTherefore, because of inherit (pkgsFor.${system}) helix;, the helix attribute\nis explicitly defined under\npackages.${system}``. This is why you access it as inputs.helix.packages.${pkgs.system}.helix;`.
flake.nixNow this is yazi’s flake.nix, yazi’s documentation tells you to use .default\nbut lets examine the flake and see why:
~{\n~ inputs = {\n~ nixpkgs.url = \"github:NixOS/nixpkgs/nixpkgs-unstable\";\n~ flake-utils.url = \"github:numtide/flake-utils\";\n~ rust-overlay = {\n~ url = \"github:oxalica/rust-overlay\";\n~ inputs.nixpkgs.follows = \"nixpkgs\";\n~ };\n~ };\n~\n~ outputs =\n~ {\n~ self,\n~ nixpkgs,\n~ rust-overlay,\n~ flake-utils,\n~ ...\n~ }:\n~ flake-utils.lib.eachDefaultSystem (\n~ system:\n~ let\n~ pkgs = import nixpkgs {\n~ inherit system;\n~ overlays = [ rust-overlay.overlays.default ];\n~ };\n~ toolchain = pkgs.rust-bin.stable.latest.default;\n~ rustPlatform = pkgs.makeRustPlatform {\n~ cargo = toolchain;\n~ rustc = toolchain;\n~ };\n~\n~ rev = self.shortRev or self.dirtyShortRev or \"dirty\";\n~ date = self.lastModifiedDate or self.lastModified or \"19700101\";\n~ version =\n~ (builtins.fromTOML (builtins.readFile ./yazi-fm/Cargo.toml)).package.version\n~ + \"pre${builtins.substring 0 8 date}_${rev}\";\n~ in\n {\n packages = {\n yazi-unwrapped = pkgs.callPackage ./nix/yazi-unwrapped.nix {\n inherit\n version\n rev\n date\n rustPlatform\n ;\n };\n yazi = pkgs.callPackage ./nix/yazi.nix { inherit (self.packages.${system}) yazi-unwrapped; };\n default = self.packages.${system}.yazi;\n };\n\n~ devShells = {\n~ default = pkgs.callPackage ./nix/shell.nix { };\n~ };\n~\n~ formatter = pkgs.nixfmt-rfc-style;\n~ }\n~ )\n~ // {\n~ overlays = {\n~ default = self.overlays.yazi;\n~ yazi = _: prev: { inherit (self.packages.${prev.stdenv.system}) yazi yazi-unwrapped; };\n~ };\n~ };\n~}\nIn this case using inputs.yazi.packages.${pkgs.system}.yazi would also work
yazi = pkgs.callPackage ./nix/yazi.nix { inherit (self.packages.${system}) yazi-unwrapped; };\nThis line defines the yazi variable (or, more precisely, creates an attribute\nnamed yazi within the packages.${system} set). It assigns to this yazi\nattribute the result of calling the Nix expression in ./nix/yazi.nix with\nyazi-unwrapped as an argument. This yazi attribute represents the actual,\nrunnable Yazi package.
default = self.packages.${system}.yazi; This line then aliases the yazi\npackage. It creates another attribute named default within the same\npackages.${system} set and points it directly to the yazi attribute that was\njust defined.
So, when you access inputs.yazi.packages.${pkgs.system}.default, you’re\neffectively following the alias to the yazi package.
The choice to use .default is primarily for convenience and adherence to a\ncommon flake convention, making the flake easier for users to consume without\nneeding to dive into its internal structure.
Flake outputs are what the flake produces when built. Flakes can have multiple\noutputs simultaneously such as:
\nPackages: Self-contained bundles that are built using derivations and\nprovide either some kind of software or dependencies of software.
\nNix development environments
\nThe outputs top-level attribute is actually a function that takes an\nattribute set of inputs and returns an attribute set that is essentially a\nrecipe for building the flake.
Once the inputs are resolved, they’re passed to the outputs attribute. This\noutputs attribute is, in fact, a function, as indicated by the : colon (or\nthe lambda syntax) that follows its definition. This function takes the\nresolved inputs (and self, the flake’s directory in the store) as arguments,\nand its return value dictates the outputs of the flake, following this schema:
{ self, nixpkgs, ... }@inputs:\n{\n # Executed by `nix flake check`\n checks.\"<system>\".\"<name>\" = derivation;\n # Executed by `nix build .#<name>`\n packages.\"<system>\".\"<name>\" = derivation;\n # Executed by `nix build .`\n packages.\"<system>\".default = derivation;\n # Executed by `nix run .#<name>`\n apps.\"<system>\".\"<name>\" = {\n type = \"app\";\n program = \"<store-path>\";\n };\n # Executed by `nix run . -- <args?>`\n apps.\"<system>\".default = { type = \"app\"; program = \"...\"; };\n\n # Formatter (alejandra, nixfmt or nixpkgs-fmt)\n formatter.\"<system>\" = derivation;\n # Used for nixpkgs packages, also accessible via `nix build .#<name>`\n legacyPackages.\"<system>\".\"<name>\" = derivation;\n # Overlay, consumed by other flakes\n overlays.\"<name>\" = final: prev: { };\n # Default overlay\n overlays.default = final: prev: { };\n # Nixos module, consumed by other flakes\n nixosModules.\"<name>\" = { config, ... }: { options = {}; config = {}; };\n # Default module\n nixosModules.default = { config, ... }: { options = {}; config = {}; };\n # Used with `nixos-rebuild switch --flake .#<hostname>`\n # nixosConfigurations.\"<hostname>\".config.system.build.toplevel must be a derivation\n nixosConfigurations.\"<hostname>\" = {};\n # Used by `nix develop .#<name>`\n devShells.\"<system>\".\"<name>\" = derivation;\n # Used by `nix develop`\n devShells.\"<system>\".default = derivation;\n # Hydra build jobs\n hydraJobs.\"<attr>\".\"<system>\" = derivation;\n # Used by `nix flake init -t <flake>#<name>`\n templates.\"<name>\" = {\n path = \"<store-path>\";\n description = \"template description goes here?\";\n };\n # Used by `nix flake init -t <flake>`\n templates.default = { path = \"<store-path>\"; description = \"\"; };\n}\nThe first line { self, nixpkgs, ... }@ inputs: defines the functions\nparameters: It’s important to understand that within the scope of the outputs\nfunction nixpkgs is available at the top-level because we explicitly passed it\nas an argument but for individual modules outside this flake the scope is lost,\nand you need to use inputs.nixpkgs (or equivalent)
It explicitly names the self attribute, making it directly accessible. The\nvariadic ... ellipses part of the function signature is what allows all\nyour flake inputs to be brought into the function’s scope without having to\nlist each one explicitly.
It destructures all other attributes (your defined inputs) into the\nfunctions scope.
It gives you a convenient single variable, inputs, that refers to the\nentire attribute set passed to the outputs function. This allows you to\naccess inputs either individually (e.g. nixpkgs) or through the inputs\nvariable (e.g. inputs.nixpkgs).
You can also define additional arbitrary attributes, but these are the outputs\nthat Nix knows about.
\nAs you can see, the majority of the outputs within the outputs schema expect a\nderivation. This means that for packages, applications, formatters, checks, and\ndevelopment shells, you’ll be defining a Nix derivation—a set of instructions\nthat tells Nix how to build a particular software component. This is central to\nNix’s declarative nature.
\nnix flake show, takes a flake URI and prints all the outputs of\nthe flake as a nice tree structure, mapping attribute paths to the types of\nvalues. ~/players/third 3s\n❯ nix flake show\npath:/home/jr/players/third?lastModified=1748272555&narHash=sha256-oNzkC6X9hA0MpOBmJSZ89w4znXxv4Q5EkFhp0ewehY0%3D\n├───nixosConfigurations\n│ └───testing: NixOS configuration\n└───nixosModules\n └───default: NixOS module\nTo show you the structure of this little flake project:
\n ~/players\n❯ tree\n .\n├── first\n│ ├── flake.lock\n│ ├── flake.nix\n│ └── result -> /nix/store/701vyaanmqchd2nnaq71y65v8ws11zx0-nixos-system-nixos-24.11.20250523.f09dede\n├── second\n│ ├── flake.lock\n│ └── flake.nix\n└── third\n ├── flake.lock\n ├── flake.nix\n └── result -> /nix/store/mlszr5ws3xaly8m4q9jslgs31w6w76y2-nixos-system-nixos-24.11.20250523.f09dede\n# flake.nix\n{\n outputs = { self }: {\n bada = \"bing\";\n };\n}\nYou can then evaluate this specific output using nix eval:
nix eval .#bada\n\"bing\"\nWhile the attribute set that outputs returns may contain arbitrary attributes,\nmeaning any valid Nix value. Some of the standard outputs are understood by\nvarious nix utilities. packages is one of these:
# flake.nix\n{\n inputs = {\n nixpkgs.url = \"github:nixos/nixpkgs\";\n };\n\n outputs = { self, nixpkgs }: {\n # this is the re-exporting part!\n packages.x86_64-linux.hello = nixpkgs.legacyPackages.x86_64-linux.hello;\n };\n}\nhello in its standard\nderivation format, exactly as nixpkgs produces it and assign it to an\nattribute in your own flake’s outputs.\npackages.x86_64-linux.hello(your flake’s output path) =\n nixpkgs.legacyPackages.x86_64-linux.hello(the source from the nixpkgs\nflake’s output)
We’re saying, My flakes hello package is exactly the same as the hello\npackage found inside the nixpkgs input flake.
It’s important to understand that within the scope of the outputs function\n(i.e. within your flake), nixpkgs is available at the top-level (i.e. the\n= nixpkgs part) because we explicitly passed it as an argument but for\nindividual modules outside of this flake the scope is lost, and\ninputs.nixpkgs is needed.
The following command builds the reexported package:
\nnix build .#hello\nor run it with:
\nnix run .#hello\nYou might notice x86_64-linux appearing in the package path, and there’s a\ngood reason for it. Flakes are designed to provide hermetic evaluation,\nmeaning their outputs should be identical regardless of the environment where\nthey’re built. A key factor in any build system is the platform (which combines\nthe architecture and operating system, like x86_64-linux or aarch64-darwin).
Because of Nix’s commitment to reproducibility across different systems, any\nflake output that involves building software packages must explicitly specify\nthe platform. The standard approach is to structure these outputs as an\nattribute set where the names are platforms, and the values are the outputs\nspecific to that platform. For the packages output, each platform-specific value\nis itself an attribute set containing the various packages built for that\nparticular system.
\nThis example outputs a sayGoodbye function, via the lib attribute, that\ntakes a name for its input and outputs a string saying Goodbye very nicely to\nthe person with that name:
{\n outputs = { self }: {\n lib = {\n sayGoodbye = name: \"Goodbye F*** Off, ${name}!\";\n };\n };\n}\nYou could then specify this flake as an input to another flake and use\nsayGoodbye however you’d like.
Or load it into the nix repl like so:
nix repl\nnix-repl> :lf .\nnix-repl> lib.sayGoodbye\n«lambda sayGoodbye @ /nix/store/665rwfvkwdx6kwvk9ldijp2a6jvcgv1n-source/flake.nix:4:20»\nnix-repl> lib.sayGoodbye \"Jr\"\n\"Goodbye F*** Off, Jr!\"\nlib.sayGoodbye without any arguments returns a\nfunction. (a lambda function)Manually repeating these platform definitions for every output (packages,\ndevShells, checks, etc.) can quickly become verbose. This is where the\nflake-utils helper flake comes in handy. It provides utilities to reduce\nboilerplate when defining outputs for multiple systems.
A commonly used function is flake-utils.lib.eachDefaultSystem, which\nautomatically generates outputs for common platforms (like x86_64-linux,\naarch64-linux, x86_64-darwin, aarch64-darwin). This transforms your\noutputs definition from manually listing each system to a more concise\nstructure:
{\n inputs = {\n nixpkgs.url = \"github:NixOS/nixpkgs/nixos-unstable\";\n flake-utils.url = \"github:numtide/flake-utils\"; # Don't forget to add flake-utils to inputs!\n };\n\n outputs = {\n self,\n nixpkgs,\n flake-utils,\n ...\n }:\n flake-utils.lib.eachDefaultSystem (\n system: let\n pkgs = import nixpkgs {inherit system;};\n in {\n packages.hello = pkgs.hello; # Now directly defines 'hello' for the current 'system' # packages.default = self.packages.${system}.hello; # Optional default alias\n devShells.default = pkgs.mkShell {\n packages = [pkgs.hello];\n };\n }\n );\n}\nnix develop in the flake’s directory.This is a minimal flake for demonstration with a hardcoded system, for more\nportability:
{\n description = \"NixOS configuration\";\n\n inputs = {\n nixpkgs.url = \"github:nixos/nixpkgs/nixos-unstable\";\n home-manager.url = \"github:nix-community/home-manager\";\n home-manager.inputs.nixpkgs.follows = \"nixpkgs\";\n treefmt-nix.url = \"github:numtide/treefmt-nix\";\n };\n\n outputs = inputs@{ nixpkgs, home-manager, treefmt-nix, ... }: let\n\n system = \"x86_64-linux\";\n host = \"your-hostname-goes-here\";\n # Define pkgs with allowUnfree\n pkgs = import inputs.nixpkgs {\n inherit system;\n config.allowUnfree = true;\n };\n\n # Formatter configuration\n treefmtEval = treefmt-nix.lib.evalModule pkgs ./lib/treefmt.nix;\n\nin {\n\n formatter.${system} = treefmtEval.config.build.wrapper;\n\n # Style check for CI\n checks.${system}.style = treefmtEval.config.build.check self;\n\n # Development shell\n devShells.${system}.default = import ./lib/dev-shell.nix {\n inherit inputs;\n };\n\n\n nixosConfigurations = {\n hostname = nixpkgs.lib.nixosSystem {\n system = \"x86_64-linux\";\n modules = [\n ./configuration.nix\n home-manager.nixosModules.home-manager\n {\n home-manager.useGlobalPkgs = true;\n home-manager.useUserPackages = true;\n home-manager.users.jdoe = ./home.nix;\n\n # Optionally, use home-manager.extraSpecialArgs to pass\n # arguments to home.nix\n }\n ];\n };\n };\n };\n}\nAnd in lib/treefmt.nix:
# treefmt.nix\n{\n projectRootFile = \"flake.nix\";\n programs = {\n alejandra.enable = true;\n deadnix.enable = true;\n # rustfmt.enable = true;\n # shellcheck.enable = true;\n # prettier.enable = true;\n statix.enable = true;\n keep-sorted.enable = true;\n # nixfmt = {\n # enable = true;\n # # strict = true;\n # };\n };\n settings = {\n global.excludes = [\n \"LICENSE\"\n \"README.md\"\n \".adr-dir\"\n \"nu_scripts\"\n # unsupported extensions\n \"*.{gif,png,svg,tape,mts,lock,mod,sum,toml,env,envrc,gitignore,sql,conf,pem,*.so.2,key,pub,py,narHash}\"\n \"data-mesher/test/networks/*\"\n \"nss-datamesher/test/dns.json\"\n \"*.age\"\n \"*.jpg\"\n \"*.nu\"\n \"*.png\"\n \".jj/*\"\n \"Cargo.lock\"\n \"flake.lock\"\n \"hive/moonrise/borg-key-backup\"\n \"justfile\"\n ];\n formatter = {\n deadnix = {\n priority = 1;\n };\n statix = {\n priority = 2;\n };\n alejandra = {\n priority = 3;\n };\n };\n };\n}\nNow we have a few commands available to us in our flake directory:
\nnix fmt: Will format your whole configuration consistently
nix flake check: While this command was already available, it is now tied to\ntreefmt’s check which will check the style of your syntax and provide\nsuggestions.
And this is lib/dev-shell.nix:
{\n inputs,\n system ? \"x86_64-linux\",\n}: let\n # Instantiate nixpkgs with the given system and allow unfree packages\n pkgs = import inputs.nixpkgs {\n inherit system;\n config.allowUnfree = true;\n overlays = [\n # Add overlays if needed, e.g., inputs.neovim-nightly-overlay.overlays.default\n ];\n };\nin\n pkgs.mkShell {\n name = \"nixos-dev\";\n packages = with pkgs; [\n # Nix tools\n nixfmt-rfc-style # Formatter\n deadnix # Dead code detection\n nixd # Nix language server\n nil # Alternative Nix language server\n nh # Nix helper\n nix-diff # Compare Nix derivations\n nix-tree # Visualize Nix dependencies\n\n # Code editing\n helix # Your editor\n\n # General utilities\n git\n ripgrep\n jq\n tree\n ];\n\n shellHook = ''\n echo \"Welcome to the NixOS development shell!\"\n echo \"System: ${system}\"\n echo \"Tools available: nixfmt, deadnix, nixd, nil, nh, nix-diff, nix-tree, helix, git, ripgrep, jq, tree\"\n '';\n }\nNow you can run nix develop in the flake directory and if successfull, you’ll\nsee the echo commands above and you will have all the tools available in your\nenvironment without having to explicitly install them.
This chapter provides practical examples to illustrate the concepts discussed in\n“Nix Flakes Explained.”
\nNixOS modules and configurations offer us a powerful and composable way to\ndefine and share system configurations. Imagine we have several independent\n“players,” each with their own unique set of configurations or modules. How do\nwe combine these individual contributions into a single, cohesive system without\ndirectly altering each player’s original flake?
\nThis example demonstrates how flakes can extend and compose each other, allowing\nyou to layer configurations on top of existing ones. This is particularly useful\nwhen you want to:
\nBuild upon a base configuration without modifying its source.
\nCombine features from multiple independent flakes into a single system.
\nCreate specialized versions of an existing configuration.
\nLet’s simulate this by creating a players directory with three sub-directories:\nfirst, second, and third. Each of these will contain its own flake.nix.
mkdir players\ncd players\nmkdir first\nmkdir second\nmkdir third\ncd first\nNow create a flake.nix with the following contents:
# flake.nix\n{\n inputs = {\n nixpkgs.url = \"github:nixos/nixpkgs/nixos-24.11\";\n };\n\n outputs = {\n self,\n nixpkgs,\n }: {\n nixosModules.default = {\n config,\n pkgs,\n lib,\n ...\n }: {\n # Create a file `/etc/first-file`\n environment.etc.first-file.text = \"Hello player # 1!\";\n boot.initrd.includeDefaultModules = false;\n documentation.man.enable = false;\n boot.loader.grub.enable = false;\n fileSystems.\"/\".device = \"/dev/null\";\n system.stateVersion = \"24.11\";\n };\n nixosConfigurations.testing = nixpkgs.lib.nixosSystem {\n system = \"x86_64-linux\";\n modules = [\n self.nixosModules.default\n ];\n };\n };\n}\nself to reference this flake from within its own\noutputs. This is the main use for self with flakes. Without self, I\nwouldn’t have a direct way to refer to the nixosModules.default that’s\ndefined within the same flake.Now in the players/second directory create this flake.nix:
# flake.nix\n{\n inputs = {\n nixpkgs.url = \"github:nixos/nixpkgs/nixos-24.11\";\n };\n\n outputs = {\n self,\n nixpkgs,\n }: {\n nixosModules.default = {\n config,\n pkgs,\n lib,\n ...\n }: {\n # Create a file `/etc/second-file`\n environment.etc.second-file.text = \"Hello player # 2!\";\n };\n };\n}\nnixosModules.default is a module which is a function that, when called by\nthe NixOS module system, returns an attribute set representing a piece of\nsystem configuration.\n/etc/second-file\nshould exist with “Hello player # 2!” as its content.And finally in players/third create another flake.nix:
# flake.nix\n{\n inputs = {\n first.url = \"/home/jr/players/first\";\n nixpkgs.follows = \"first/nixpkgs\";\n second = {\n url = \"/home/jr/players/second\";\n inputs.nixpkgs.follows = \"first/nixpkgs\";\n };\n };\n\n outputs = {\n self,\n nixpkgs,\n first,\n second,\n }:\n first.outputs\n // {\n nixosConfigurations.testing = first.nixosConfigurations.testing.extendModules {\n modules = [\n second.nixosModules.default\n ];\n };\n };\n}\nplayers\ndirectory in the inputs above.In your third directory inspect it with:
~/players/third\n❯ nix flake show\npath:/home/jr/players/third?lastModified=1748271697&narHash=sha256-oNzkC6X9hA0MpOBmJSZ89w4znXxv4Q5EkFhp0ewehY0%3D\n├───nixosConfigurations\n│ └───testing: NixOS configuration\n└───nixosModules\n └───default: NixOS module\nand build it with:
\nnix build .#nixosConfigurations.testing.config.system.build.toplevel\ncat result/etc/first-file\nHello player # 1!\ncat result/etc/second-file\nHello player # 2!\nUnderstanding the Extension
\nAs you saw in the flake.nix for the third player, we leveraged two key flake\nfeatures to combine and extend the previous configurations:
// operator):outputs = { ..., first, second, ... }:\nfirst.outputs // { # ... your extensions here ...\n};\nThe // (attribute set union) operator allows us to take all the outputs from\nfirst.outputs (which includes its nixosConfigurations and nixosModules)\nand then overlay or add to them on the right-hand side. This means our third\nflake will inherit all the outputs from first, but we can then modify or add new\nones without changing the first flake itself.
config.extendModules: nixosConfigurations.testing = first.nixosConfigurations.testing.extendModules {\n modules = [\n second.nixosModules.default\n ];\n };\nThis is the core of the extension. We’re taking the testing NixOS configuration\ndefined in the first flake (first.nixosConfigurations.testing) and then\ncalling its extendModules function. This function allows us to inject\nadditional NixOS modules into an already defined system configuration. In this\ncase, we’re adding the default module from the second flake\n(second.nixosModules.default).
By combining these techniques, the third flake successfully creates a NixOS\nconfiguration that includes both the settings from first (like /etc/first-file\nand the base system options) and the settings from second (like\n/etc/second-file), all without directly altering the first or second flakes.\nThis demonstrates the incredible power of flake extensibility for building\ncomplex, modular, and composable systems.
![\"gruv16\"](\"https://saylesss88.github.io/images/gruv16.png\")
Pull requests communicate changes to a branch in a repository. Once a pull\nrequest is opened, you can review changes with collaborators and add follow-up\ncommits.
\nA pull request is a proposal to merge a set of changes from one branch\ninto another. In a pull request, collaborators can review and discuss the\nproposed set of changes before they integrate the changes into the main\ncodebase.
\nPull requests display the differences, or diffs, between the content in the\nsource branch and the content in the target branch.
\ngraph LR\n A[Your Local Repository] --> B(Feature Branch);\n B --> C{GitHub Repository};\n C -- \"Open Pull Request\" --> D[Pull Request on GitHub];\n D -- \"Review & Discussion\" --> D;\n D -- \"Merge\" --> E(Main Branch on GitHub);\n E --> F[Nixpkgs Users];\nExplanation of the Diagram:
\nA[Your Local Repository]: This represents the copy of the Nixpkgs repo on\nyour computer where you make changes.
\nB (Feature Branch): You create a dedicated branch (e.g.my-pack-update)\nto isolate your changes.
C {GitHub Repository}: This is the central online repo for Nixpkgs on\nGithub. You push your feature branch to this repo.
\nC – “Open Pull Request” – D [Pull Request on Github]: You initiate a\npull request from your feature branch to the main branch (usually master or\nmain) through the GitHub interface.
D [Pull Request on GitHub]: This is where collaborators can see your\nproposed changes, discuss them, and provide feedback.
\nD – “Review & Discussion” –> D: The pull request facilitates\ncommunication and potential revisions based on the review.
\nD – “Merge” –> E (Main Branch on GitHub): Once the changes are approved,\nthey are merged into the main branch of the Nixpkgs repository.
\nE (Main Branch on GitHub): The main branch now contains the integrated\nchanges.
\nE –> F [Nixpkgs Users]): Eventually, these changes become available to\nall Nixpkgs users through updates to their Nix installations.
\nFlakes often rely on having access to the full history of the Git repository to\ncorrectly determine dependencies, identify specific revisions of inputs, and\nevaluate the flake. Not in all situations will a shallow clone work and this is\none of them.
\nIf you have any changes to your local copy of Nixpkgs make sure to stash them\nbefore the following:
\ngit stash -u\ngit stash popStep 1 Clone Nixpkgs Locally
\nIf you don’t have Nixpkgs locally, you’ll need to clone it:
\ngit clone https://github.com/NixOS/nixpkgs.git\nStep 2 Find a Relevant Pull Request
\nTo find specifig commits and releases:
\nstatus.nixos.org provides the latest tested commits\nfor each release - use when pinning to specific commits. List of active release\nchannels - use when tracking latest channel versions.
\nThe complete list of channels is available at\nnixos.org/channels
\nTo find a relevant PR you can go to:
\nThe following example actually uses the\nNix Pull Requests the process is the\nsame, but that is an important distinction.
\nIn the Filters enter stack trace for this example.
The pull request I chose was 8623
\nStep 3 Add the Remote Repository (if necessary)
\nIf the pull request is from a different repository than your local clone (as in\nthe case of the nix PR while working in a nixpkgs clone), you need to add\nthat repository as a remote. It’s common to name the main Nixpkgs remote\norigin and other related repositories like nix as upstream.
Assuming you are in your nixpkgs clone and want to test a PR from the nix\nrepository:
git remote add upstream https://github.com/NixOS/nix.git\nStep 4 Fetch the Pull Request Changes
\nFetch the Pull Request Information:
\ngit fetch upstream refs/pull/8623/head:pr-8623\nhead from the pull request 8623 in\nthe upstream remote and creates a local branch named pr-8623 that tracks\nit.Output:
\nremote: Enumerating objects: 104651, done.\nremote: Counting objects: 100% (45/45), done.\nremote: Compressing objects: 100% (27/27), done.\nremote: Total 104651 (delta 33), reused 20 (delta 18), pack-reused 104606 (from 1)\nReceiving objects: 100% (104651/104651), 61.64 MiB | 12.56 MiB/s, done.\nResolving deltas: 100% (74755/74755), done.\nFrom https://github.com/NixOS/nix\n * [new ref] refs/pull/8623/head -> pr-8623\n * [new tag] 1.0 -> 1.0\n * [new tag] 1.1 -> 1.1\n * [new tag] 1.10 -> 1.10\n * [new tag] 1.11 -> 1.11\n * [new tag] 1.11.1 -> 1.11.1\n * [new tag] 1.2 -> 1.2\n * [new tag] 1.3 -> 1.3\n * [new tag] 1.4 -> 1.4\n * [new tag] 1.5 -> 1.5\n * [new tag] 1.5.1 -> 1.5.1\n * [new tag] 1.5.2 -> 1.5.2\n * [new tag] 1.5.3 -> 1.5.3\n * [new tag] 1.6 -> 1.6\n * [new tag] 1.6.1 -> 1.6.1\n * [new tag] 1.7 -> 1.7\n * [new tag] 1.8 -> 1.8\n * [new tag] 1.9 -> 1.9\n * [new tag] 2.0 -> 2.0\n * [new tag] 2.2 -> 2.2\nStep 5 Checkout the Local Branch:
\ngit checkout pr-8623\nOr with the gh cli:
gh pr checkout 8623\nnix build\nOutput:
\nerror: builder for '/nix/store/rk86daqgf6a9v6pdx6vcc5b580lr9f09-nix-2.20.0pre20240115_20b4959.drv' failed with exit code 2;\n last 25 log lines:\n >\n > _NIX_TEST_ACCEPT=1 make tests/functional/lang.sh.test\n >\n > to regenerate the files containing the expected output,\n > and then view the git diff to decide whether a change is\n > good/intentional or bad/unintentional.\n > If the diff contains arbitrary or impure information,\n > please improve the normalization that the test applies to the output.\n > make: *** [mk/lib.mk:90: tests/functional/lang.sh.test] Error 1\n > make: *** Waiting for unfinished jobs....\n > ran test tests/functional/selfref-gc.sh... [PASS]\n > ran test tests/functional/store-info.sh... [PASS]\n > ran test tests/functional/suggestions.sh... [PASS]\n > ran test tests/functional/path-from-hash-part.sh... [PASS]\n > ran test tests/functional/gc-auto.sh... [PASS]\n > ran test tests/functional/path-info.sh... [PASS]\n > ran test tests/functional/flakes/show.sh... [PASS]\n > ran test tests/functional/fetchClosure.sh... [PASS]\n > ran test tests/functional/completions.sh... [PASS]\n > ran test tests/functional/build.sh... [PASS]\n > ran test tests/functional/impure-derivations.sh... [PASS]\n > ran test tests/functional/build-delete.sh... [PASS]\n > ran test tests/functional/build-remote-trustless-should-fail-0.sh... [PASS]\n > ran test tests/functional/build-remote-trustless-should-pass-2.sh... [PASS]\n > ran test tests/functional/nix-profile.sh... [PASS]\n For full logs, run:\n nix log /nix/store/rk86daqgf6a9v6pdx6vcc5b580lr9f09-nix-2.20.0pre20240115_20b4959.drv\nnix build (Part of the Nix Unified CLI):\nDeclarative: when used within a Nix flake (flake.nix), nix build is a\nbit more declarative. It understands the outputs defined in your flake.
Clearer Output Paths: nix build typically places build outputs in the\n./result directory by default (similar to nix-build’s result symlink)
Better Error Reporting: It gives more informative error messages.
\nFuture Direction
\nBenefits 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\nthe more idiomatic way to build packages defined in your dev environment.
Consistency: Using the unified CLI promotes a more consistent workflow.
\nAs you can see this build failed, as for why the build failed, the key part of\nthe error message is:
\nmake: *** [mk/lib.mk:90: tests/functional/lang.sh.test] Error 1\nlang.sh.test) failed. This\nhappens when the expected output of the test doesn’t match the actual output.This can heppen when:
\nThe test expectations are outdated due to changes in the codebase.
\nThe test captures environment-specific or transient outputs that are not\nproperly normalized.
\nThe test includes impure or non-deterministic information, making it hard to\nverify.
\nTo address this, _NIX_TEST_ACCEPT=1 is used as an override mechanism that tells\nthe test framework: > “Accept whatever output is generated as the new expected\nresult.”
\nThe message advises running:
\n_NIX_TEST_ACCEPT=1 make tests/functional/lang.sh.test\ngit diff:git diff tests/functional/lang.sh.test\nIf the changes seem valid, commit them:
\ngit add tests/functional/lang.sh.test\ngit commit -m \"Update expected test output for lang.sh.test\"\nRunning the following will provide the full logs:
\nnix log /nix/store/rk86daqgf6a9v6pdx6vcc5b580lr9f09-nix-2.20.0pre20240115_20b4959.drv\nTesting Nixpkgs pull requests is a vital part of contributing to a healthy and\nreliable Nix ecosystem. By following these steps, you can help ensure that\nchanges are well-vetted before being merged, ultimately benefiting all Nix\nusers. Your efforts in testing contribute significantly to the quality and\nstability of Nixpkgs.
\n", "date_published": "2025-11-27T00:00:00+00:00", "author": { "name": "saylesss87@proton.me (saylesss88)" } }, { "id": "https://saylesss88.github.io/installation/unenc/unenc_impermanence.html", "url": "https://saylesss88.github.io/installation/unenc/unenc_impermanence.html", "title": "Unencrypted BTRFS Impermanence with Flakes", "content_html": "Figure 1: Impermanence Logo: Image of the Impermanence logo. Sourced from the
\n\nThis guide is for an unencrypted setup, there are a few links at the end for\nencrypted setups. This guide follows the previous\nminimal install guide\nbut you should be able to adjust it carefully to meet your needs.
\nThis section details how to set up impermanence on your NixOS system using BTRFS\nsubvolumes. With impermanence, your operating system’s root filesystem will\nreset to a pristine state on each reboot, while designated directories and files\nremain persistent. This provides a highly reliable and rollback-friendly system.
\nIn NixOS, “state” is any data or condition of the system that isn’t defined in\nyour declarative configuration. The impermanence approach aims to make this\nstate temporary (ephemeral) or easily resettable, so your system always matches\nyour configuration and can recover from unwanted changes or corruption.
\nIn a traditional Linux system, most of this state is stored on the disk and\npersists indefinitely unless manually deleted or modified. However, this can\nlead to configuration drift, where the system accumulates changes (e.g., log\nfiles, temporary files, or unintended configuration tweaks) that make it harder\nto reproduce or maintain.
\nImpermanence, in the context of operating systems, refers to a setup where the\nmajority of the system’s root filesystem (/) is reset to a pristine state on\nevery reboot. This means any changes made to the system (e.g., installing new\npackages, modifying system files outside of configuration management, creating\ntemporary files) are discarded upon shutdown or reboot.
Impermanence is a NixOS approach that makes the system stateless (or nearly\nstateless) by wiping the root filesystem (/) on each boot, ensuring a clean,\npredictable starting point. Only explicitly designated data (persistent state)\nis preserved across reboots, typically stored in specific locations like the\n/nix/persist subvolume. This is possible because NixOS can boot with only the\n/boot, and /nix directories. This achieves:
The root subvolume is deleted and recreated on each boot, erasing transient\nstate (e.g., temporary files, runtime data).
\nThis ensures the system starts fresh, reducing clutter and making it behave\ncloser to a declarative system defined by your NixOS configuration.
\nCritical state (e.g., user files, logs, system configuration) is preserved in\ndesignated persistent subvolumes (e.g., /nix/persist, /var/log, /var/lib) or\nfiles.
\nYou control exactly what state persists by configuring\nenvironment.persistence.\"/nix/persist\" or other mechanisms.
❗ The understanding around persisting /var/lib/nixos seems to be evolving.\nSee,The importance of persisting /var/lib/nixos See also necessary system\nstate
By wiping transient state, impermanence prevents unintended changes from\naccumulating, making the system more reproducible.
\nIt enhances security by ensuring sensitive temporary data (e.g., /tmp, runtime\ncredentials) is erased on reboot.
\n# flake.nix\n{\n description = \"NixOS configuration\";\n\n inputs = {\n nixpkgs.url = \"github:nixos/nixpkgs/nixos-unstable\";\n disko.url = \"github:nix-community/disko/latest\";\n disko.inputs.nixpkgs.follows = \"nixpkgs\";\n impermanence.url = \"github:nix-community/impermanence\";\n };\n\n outputs = inputs@{ nixpkgs, ... }: {\n nixosConfigurations = {\n hostname = nixpkgs.lib.nixosSystem {\n system = \"x86_64-linux\";\n modules = [\n ./configuration.nix\n inputs.disko.nixosModules.disko\n inputs.impermanence.nixosModules.impermanence\n ];\n };\n };\n };\n}\nfindmnt:Before configuring impermanence, it’s crucial to know the device path and\nsubvolume path of your main BTRFS partition where the root filesystem (/) is\nlocated. This information is needed for the mount command within the\nimpermanence script.
\nfindmnt /\nTARGET SOURCE FSTYPE OPTIONS\n/ /dev/disk/by-partlabel/disk-main-root[/root]\n btrfs rw,noatime,compress=zstd:3,ssd,discard=async,space_cache=v2,subvolid=275,sub\nFrom the SOURCE column, note the full path, including the device (e.g.,\n/dev/disk/by-partlabel/disk-main-root) and the subvolume in brackets (e.g.,\n[/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\n(e.g. /dev/nvme0n1p2), but using the partlabel is generally more robust for\nscripts.
Now, create a new file named impermanence.nix in your configuration directory\n(i.e. your flake directory). This file will contain all the specific settings\nfor your impermanent setup, including BTRFS subvolume management and persistent\ndata locations. Since this file is right next to your configuration.nix,\nyou’ll just add an imports = [ ./impermanence.nix ] to your\nconfiguration.nix apply it to your configuration.
{lib, ...}: {\n # Reset root subvolume on boot\n boot.initrd.postResumeCommands = lib.mkAfter ''\n mkdir /btrfs_tmp\n mount /dev/disk/by-partlabel/disk-main-root /btrfs_tmp # CONFIRM THIS IS CORRECT FROM findmnt\n if [[ -e /btrfs_tmp/root ]]; then\n mkdir -p /btrfs_tmp/old_roots\n timestamp=$(date --date=\"@$(stat -c %Y /btrfs_tmp/root)\" \"+%Y-%m-%-d_%H:%M:%S\")\n mv /btrfs_tmp/root \"/btrfs_tmp/old_roots/$timestamp\"\n fi\n\n delete_subvolume_recursively() {\n IFS=$'\\n'\n for i in $(btrfs subvolume list -o \"$1\" | cut -f 9- -d ' '); do\n delete_subvolume_recursively \"/btrfs_tmp/$i\"\n done\n btrfs subvolume delete \"$1\"\n }\n\n for i in $(find /btrfs_tmp/old_roots/ -maxdepth 1 -mtime +30); do\n delete_subvolume_recursively \"$i\"\n done\n\n btrfs subvolume create /btrfs_tmp/root\n umount /btrfs_tmp\n '';\n\n # Use /persist as the persistence root, matching Disko's mountpoint\n environment.persistence.\"/nix/persist\" = {\n hideMounts = true;\n directories = [\n \"/etc\" # System configuration (Keep this here for persistence via bind-mount)\n \"/var/spool\" # Mail queues, cron jobs\n \"/srv\" # Web server data, etc.\n \"/root\"\n ];\n files = [\n ];\n };\n}\nWith btrfs subvolumes since each directory is its own subvolume, when the root\nis wiped on reboot the subvolumes are untouched.
\nOnce you have completed all the steps and created or modified the necessary\nfiles (flake.nix, impermanence.nix), you need to apply these changes to your\nNixOS system.
cd /path/to/your/flake\nnixos-rebuild switch command. This command\nwill:Evaluate your flake.nix and the modules it imports (including your new\nimpermanence.nix).
\nBuild a new NixOS system closure based on your updated configuration.
\nActivate the new system configuration, making it the current running system.
\n\n\n❗ NOTE: On the first rebuild after setting up impermanence, you may find that\nyou’re not in the password database or cannot log in/sudo. This occurs because\nthe initial state of your new ephemeral root filesystem, including /etc (where\nuser passwords are stored), is fresh. It has to do with the timing of when\nenvironment.persistence takes effect during the first boot.
\n
\n\nTo avoid this password issue, before your first nixos-rebuild switch for\nimpermanence, run:
\n\nsudo mkdir -p /nix/persist/etc # Ensure the target directory exists\nsudo cp -a /etc/* /nix/persist/etc\n\n
\n- This copies your current /etc directory contents (including existing user\npasswords) into your persistent >>storage.
\n- Crucially: You must also ensure that
\n/etcis explicitly included in your\nenvironment.persistence.\"/nix/persist\".directories list in your\nimpermanence.nixlike we did above, (or main configuration). This\nconfigures >NixOS to persistently bind-mount/nix/persist/etcover/etc\non every subsequent boot. Once these steps are done and you reboot, your\nuser passwords should function correctly, and future rebuilds will > not\npresent this problem.
sudo nixos-rebuild switch --flake .#hostname # Replace 'hostname' with your actual system hostname\n/imperm_test to your\nenvironment.persistence.\"/nix/persist\" directories, this file should not\nsurvive a reboot.mkdir /imperm_test\necho \"This should be Gone after Reboot\" | sudo tee /imperm_test/testfile\nls -l /imperm_test/testfile # Verify the file exists\ncat /imperm_test/testfile # Verify content\nsudo reboot\nls -l /imperm_test/testfile\nYou should see an output like ls: cannot access '/imperm_test/testfile': No\nsuch file or directory. This confirms that the /imperm_test directory and its\ncontents were indeed ephemeral and were removed during the reboot process,\nindicating your impermanence setup is working correctly!
Your system should now come up with a fresh root filesystem, and only the data\nspecified in your environment.persistence.\"/nix/persist\" configuration will be\npersistent.
This is if you followed the minimal_install guide, it will need to be changed\nfor a different disk layout.
\nChroot is an operation that changes the\napparent root directory for the current running process and their children. A\nprogram that is run in such a modified environment cannot access files and\ncommands outside that environmental directory tree. This modified environment is\ncalled a chroot jail. –NixOS wiki
\nnixos-enter allows you to access a NixOS installation from a NixOS rescue\nsystem. To use, setup /mnt as described in the\ninstallation manual
🛠️ Recovery: Chroot into Your NixOS Btrfs+Impermanence System
\nTake note of your layout from commands like:
\nsudo fdisk -l\nlsblk\nsudo btrfs subvol list /\nAlso inspect your disk-config.nix to ensure you refer to the correct subvol=\nnames.
If you need to repair your system (e.g., forgot root password, fix a broken\nconfig, etc.), follow these steps to chroot into your NixOS install:
\nBoot from a NixOS (or any recent Linux) live USB.
\nOpen a terminal and become root:
\nsudo -i\nYour main disk is /dev/nvme0n1
EFI partition: /dev/nvme0n1p1 (mounted at /boot)
Root partition: /dev/nvme0n1p2 (Btrfs, with subvolumes)
First, mount the Btrfs partition somewhere temporary (not as / yet):
\nmount -o subvol=root,compress=zstd,noatime /dev/nvme0n1p2 /mnt\nNow mount your other subvolumes as defined in your disko.nix:
# Mount Other Subvolumes\n# (Ensure /mnt directories are created for each *mountpoint*)\n\n# Home\nmkdir -p /mnt/home\nmount -o subvol=home,compress=zstd,noatime /dev/nvme0n1p2 /mnt/home\n\n# IMPORTANT: No separate mount for /mnt/home/user, as it's a nested subvolume\n# and handled by the /home mount.\n\n# Nix store\nmkdir -p /mnt/nix\nmount -o subvol=nix,compress=zstd,noatime /dev/nvme0n1p2 /mnt/nix\n\n# Nix persist\nmkdir -p /mnt/nix/persist\n# CRITICAL: Based our disko.nix, the subvolume name is 'persist', not 'nix/persist'\nmount -o subvol=persist,compress=zstd,noatime /dev/nvme0n1p2 /mnt/nix/persist\n\n# /var/log\nmkdir -p /mnt/var/log\nmount -o subvol=log,compress=zstd,noatime /dev/nvme0n1p2 /mnt/var/log\n\n# /var/lib\nmkdir -p /mnt/var/lib\n# Confirmed: The subvolume named 'lib' is mounted to /var/lib\nmount -o subvol=lib,compress=zstd,noatime /dev/nvme0n1p2 /mnt/var/lib\nNote: If you get “subvolume not found,” check the subvolume names with\nbtrfs subvol list /mnt.
mkdir -p /mnt/boot mount /dev/nvme0n1p1 /mnt/boot\nmount --bind /dev /mnt/dev mount --bind /proc /mnt/proc mount --bind /sys\n/mnt/sys mount --bind /run /mnt/run\nchroot /mnt /run/current-system/sw/bin/bash\nor, if using a non-NixOS live system:
\nnixos-enter\n(You may need to install nixos-enter with nix-shell -p nixos-enter.) 8. You’re\nIn!
\nYou can now run nixos-rebuild, reset passwords, or fix configs as needed. 🔎
\n📓 Notes
\nAdjust compress=zstd,noatime if your config uses different mount options.
For impermanence, make sure to mount all persistent subvolumes you need.
\nIf you use swap, you may want to enable it too (e.g., swapon /dev/zram0 if\nrelevant).
\nYou can now recover, repair, or maintain your NixOS system as needed!
\nThe Nix language is designed for conveniently creating and composing\nderivations precise descriptions of how contents of files are used to derive\nnew files. –Nix Reference Manual
\nNix is often described as “JSON with functions.” It’s a declarative language\nwhere you define outcomes, not step-by-step instructions. Instead of writing\nsequential code, you create expressions that describe data structures,\nfunctions, and dependencies. These expressions are evaluated lazily, meaning Nix\ncomputes values only when needed, making it efficient for managing large\nsystems.
\nYou can plug most of the following into the nix repl I’m showing it in a\nsingle code block here for brevity:
# Comments Look Like This!\n\n# Strings\n\"This is a string\" # String literal\n\n''\none\ntwo # multi-line String\nthree\n''\n\n(\"foo\" + \"bar\") # => \"foobar\"\n\n\"foo\" != \"bar\" # Inequality test # => true\n\n!false # => true\n\n(\"Home dir is ${builtins.getEnv \"HOME\"}\") # String Interpolation\n# => \"Home dir is /home/jr\"\n\n\"3 6 ${builtins.toString 9}\"\n# => \"3 6 9\"\n\n\"goodbye ${ { d = \"world\";}.d}\"\n# => \"goodbye world\"\n\n# Booleans\n\n(false && true) # AND # => false\n\n(true || false) # OR # => true\n\n(if 6 < 9 then \"yay\" else \"nay\") # => \"yay\"\n\nnull # Null Value\n\n679 # Integer\n\n(6 + 7 + 9) # => 22 # Addition\n\n(9 - 3 - 2) # => 4 # Subtraction\n\n(6 / 3) # => 2 # Division\n6.79 # Floating Point\n\n/etc/nixos # Absolute Path\n\n../modules/nixos/boot.nix # relative\n\n# Let expressions\n\n(let a = \"2\"; in # Let expressions are a way to create variables\na + a + builtins.toString \"4\")\n# => \"224\"\n\n(let first = \"firstname\"; in\n\"lastname \" first)\n# => \"lastname firstname\"\n\n# Lists\n\n[ 1 2 \"three\" \"bar\" \"baz\" ] # lists are whitespace separated\n\nbuiltins.elemAt [ 1 2 3 4 5 ] 3\n# => 4\n\nbuiltins.length [ 1 2 3 4 ]\n# => 4\n\n# Attrsets\n\n{ first = \"Jim\"; last = \"Bo\"; }.last # Attribute selection\n# => \"Bo\"\n\n{ a = 1; b = 3; } // { c = 4; b = 2; } # Attribute Set merging\n# => { a = 1; b = 2; c = 4; } # Right Side takes precedence\n\nbuiltins.listToAttrs [ { name = \"Jr\"; value = \"Jr Juniorville\"; } {name = \"$\"; value = \"JR\"; } { name = \"jr\"; value = \"jr\nville\"; }]\n# => { \"$\" = \"JR\"; Jr = \"Jr Juniorville\"; jr = \"jrville\"; }\n\n# Control Flow\n\nif 2 * 2 == 4\nthen \"yes!\"\nelse \"no!\"\n# => \"yes!\"\n\nassert 2 * 2\n== 4; \"yes!\"\n# => \"yes!\"\n\nwith builtins;\nhead [ 5 6 7 ]\n# => 5\n\n# or\n\nbuiltins.head[ 5 6 7 ]\n\ninherit pkgs # pkgs = pkgs;\nsrc; # src = src;\nNix expressions are evaluated lazily, meaning Nix computes values only when\nneeded. This is a powerful feature that makes Nix efficient for managing large\nsystems, as it avoids unnecessary computations.
\nFor example, observe how a is never evaluated in the following nix-repl\nsession:
nix-repl> let a = builtins.div 4 0; b = 6; in b\n6\na isn’t used in the final result, there’s no division by zero error.Strings: Strings are enclosed in double quotes (\") or two single quotes\n('').
nix-repl> \"stringDaddy\"\n\"stringDaddy\"\nnix-repl> ''\n This is a\n multi-line\n string\n''\n\"This is a\\nmulti-line\\nstring.\\n\"\nstring interpolation.\nis a language feature where a string, path, or attribute name can contain an\nexpressions enclosed in ${ }. This construct is called an interpolated\nstring, and the expression inside is an interpolated expression.
Rather than writing:
\nlet path = \"/usr/local\"; in \"--prefix=${path}\"\nThis evaluates to \"--prefix=/usr/local\". Interpolated expressions must\nevaluate to a string, path, or an attribute set with an outPath or\n__toString attribute.
Attribute sets are all over Nix code and deserve their own section, they are\nname-value pairs wrapped in curly braces, where the names must be unique:
\n{\n string = \"hello\";\n int = 8;\n}\nAttribute names usually don’t need quotes.
\nYou can access attributes using dot notation:
\nlet person = { name = \"Alice\"; age = 30; }; in person.name\n\"Alice\"\nYou will sometimes see attribute sets with rec prepended. This allows access\nto attributes within the set:
rec {\n x = y;\n y = 123;\n}.x\nOutput: 123
or
\nrec {\n one = 1;\n two = one + 1;\n three = two + 1;\n}\nOutput:
\n {\n one = 1;\n three = 3;\n two = 2;\n }\n# This would fail:\n{\n one = 1;\n two = one + 1; # Error: undefined variable 'one'\n three = two + 1;\n}\nRecursive sets introduce the danger of infinite recursion For example:
\nrec {\n x = y;\n y = x;\n}.x\nWill crash with an infinite recursion encountered error message.
The\nattribute set update operator\nmerges two attribute sets.
\nExample:
\n{ a = 1; b = 2; } // { b = 3; c = 4; }\nOutput:
\n{ a = 1; b = 3; c = 4; }\nHowever, names on the right take precedence, and updates are shallow.
\nExample:
\n{ a = { b = 1; }; } // { a = { c = 3; }; }\nOutput:
\n{ a = { c = 3; }; }\nAbove, key b was completely removed, because the whole a value was replaced.
Inheriting Attributes
\nlet x = 123; in\n{\n inherit x;\n y = 456;\n}\nis equivalent to
\nlet x = 123; in\n{\n x = x;\n y = 456;\n}\nwhich are both equivalent to
\n{\n x = 123;\n y = 456;\n}\n\n\n❗: This works because
\nxis added to the lexical scope by thelet\nconstruct.
Now that we understand attribute sets lets move on to functions, a powerful\nfeature of the Nix language that gives you the ability to reuse and share\nlogical pieces of code.
\nFunctions in Nix help you build reusable components and are the the building\nblocks of Nix. In the next chapter we’ll go even further into Nix functions and\nhow to use them but I will touch on them here.
\nNix functions have this form:
\npattern: body\nThe following is a function that expects an integer and returns it increased by\n1:
\nx: x + 1 # lambda function, not bound to a variable\nThe pattern tells us what the argument of the function has to look like, and\nbinds variables in the body to (parts of) the argument.
\n(x: x + 5) 200\n205\nThey are all lambdas (i.e. anonymous functions without names) until we assign\nthem to a variable like the following example.
\nFunctions are defined using this syntax, where x and y are attributes passed\ninto the function:
{\n my_function = x: y: x + y;\n}\nThe code below calls a function called my_function with the parameters 2 and\n3, and assigns its output to the my_value field:
{\n my_value = my_function 2 3;\n}\nmy_value\n5\nThe body of the function automatically returns the result of the function.\nFunctions are called by spaces between it and its parameters. No commas are\nneeded to separate parameters.
\nThe following is a function that expects an attribute set with required\nattributes a and b and concatenates them:
{ a, b }: a + b\nDefault Values in Functions:
\nFunctions in Nix can define default values for their arguments. This allows\nfor more flexible function calls where some arguments are optional.
\n{ x, y ? \"foo\", z ? \"bar\" }: z + y + x\nx, but optionally\naccepts y and z.@-patterns in functions:
\nAn @-pattern provides a means of referring to the whole value being matched by\nthe function’s argument pattern, in addition to destructuring it. This is\nespecially useful when you want to access attributes that are not explicitly\ndestructured in the pattern:
args@{ x, y, z, ... }: z + y + x + args.a\n# or\n{ x, y, z, ... } @ args: z + y + x + args.a\nHere, args is bound to the argument as passed, which is further matched\nagainst the pattern { x, y, z, ... }. The @-pattern makes mainly sense\nwith an ellipsis(...) as you can access attribute names as a, using\nargs.a, which was given as an additional attribute to the function.
We will expand on Functions in\nThis Chapter
\nNix is a pure expression language, meaning every construct evaluates to a value\n— there are no statements. Because of this, if expressions in Nix work\ndifferently than in imperative languages, where conditional logic often relies\non statements (if, elsif, etc.).
If expressions in Nix:
\nSince everything in Nix is an expression, an if expression must always produce\na value:
nix-repl> a = 6\nnix-repl> b = 10\nnix-repl> if a > b then \"yes\" else \"no\"\n\"no\"\nHere, \"no\" is the result because a(6) is not greater than b(10). Notice\nthat there’s no separate conditional statement – the entire construct evaluates\nto a value.
Another example, integrating built-in functions:
\n{\n key = if builtins.pathExists ./path then \"YES\" else \"NO!\";\n}\nIf ./path exists it will evaluate to the value \"YES\" or else it will\nevaluate to \"NO!\".
Thus, the final result of the expression would be:
\n{ key = \"YES\"; }\n# or\n{ key = \"NO!\"; }\nSince Nix does not have statements, Nix’s if statements behave more like\nternary operators\n(condition ? value_if_true : value_if_false) in other languages.
Let expressions:
\nLet expressions in Nix is primarily a mechanism for local variable binding and\nscoping. It allows you to define named values that are only accessible within\nthe in block of the let expression. This is useful for keeping code clean\nand avoiding repitition.
For example:
\nlet\n a = \"foo\";\n b = \"fighter\";\nin a + b\n\"foofighter\"\nHere, a and b are defined inside the let block, and their values are used\nin the in expression. Since everything in Nix is an expression, a + b\nevaluates to \"foofighter\"
Using Let Expressions Inside Attribute Sets
\nLet expressions are commonly used when defining attribute sets (Click for\noutput):
\nlet\n appName = \"nix-app\";\n version = \"1.0\";\nin {\n name = appName;\n fullName = appName + \"-\" + version;\n}\n~{\n~ name = \"nix-app\";\n~ fullName = \"nix-app-1.0\";\n~}\nThis allows you to reuse values within an attribute set, making the code more\nmodular and preventing duplication.
\nLet Expressions in Function Arguments
\nYou can also use let expressions within function arguments to define\nintermediate values before returning an output:
\n{ pkgs, lib }:\nlet\n someVar = \"hello\";\n otherVar = \"world\";\nin\n{ inherit pkgs lib someVar otherVar; }\nResult:
\n{\n pkgs = <value>;\n lib = <value>;\n someVar = \"hello\";\n otherVar = \"world\";\n}\nHere, inherit brings pkgs and lib into the resulting attribute set,\nalongside the locally defined variables someVar and otherVar.
Key Takeaways:
\nLet expressions allow local variable bindings that are only visible inside the\nin block. They also help avoid repitition and improve readability.
\nCommonly used inside attribute sets or function arguments.
\nTheir scope is limited to the expression in which they are declared.
\nWith expressions:
\nA with expression in Nix is primarily used to simplify access to attributes\nwithin an attribute set. Instead of repeatedly referring to a long attribute\npath, with temporarily brings the attributes into scope, allowing direct access\nwithout prefixing them.
Basic Example: Reducing Attribute Path Usage
\nConsider the following expressions:
\nnix-repl> longName = { a = 3; b = 4; }\nnix-repl> longName.a + longName.b\n7\nHere, we must explicitly reference longName.a and longName.b. Using a with\nexpression simplifies this:
nix-repl> with longName; a + b\n7\nNow, within the scope of the with expression, a and b are accessible without\nprefixing 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\npackages from nixpkgs is writing the following:
{ pkgs }:\nwith pkgs; {\n myPackages = [ vim git neofetch ];\n}\nInstead of writing this:
\n{ pkgs }:\n{\n myPackages = [ pkgs.vim pkgs.git pkgs.neofetch ];\n}\n\n\nTip: Overusing
\nwith lib;orwith pkgs;can reduce clarity, it may be fine\nfor smaller modules where the scope is limited. For larger configurations,\nexplicit references (pkgs.something) often make dependencies clearer and\nprevent ambiguity.
with gets less priority than let. This can be confusing, especially if\nyou like to write with pkgs;:nix-repl> pkgs = { x = 2; }\n\nnix-repl> with pkgs; x\n2\n\nnix-repl> with pkgs; let x = 4; in x\n4\nThis shows us that the let binding overrides the with binding.
let x = 4; in with pkgs; x\n4\nStill returns 4, but the reasoning is different. The with expression doesn’t\ndefine new bindings; it simply makes attributes from pkgs available as\nunqualified names. However, because let x = 4 is outside the with, it\nalready extablished x = 4, so when with pkgs; x is evaluated inside, x\nstill refers to the outer let binding, not the one from pkgs.
@-patternsIn the following example, calling a function that binds a default value \"baz\"\nto the attribute b of an argument using an alias (@) pattern, with an empty\nattribute set as argument, results in the alias variable inputs being bound to\nthe original empty attribute set instead of including the default value:
(inputs@(b ? \"baz\"): inputs) {}\nOutput:
\n{}\nThis happens because the alias inputs@ binds to the argument as passed, before\nthe default value for b is applied.
The syntax requires curly brackets around the attribute set pattern for\ncorrectness, so the fixed syntax would be:
\n(inputs@{b ? \"baz\"}: inputs) {}\nHowever, even with this fix, the inputs alias still refers to the original\nargument without defaults applied. So the quirk persists, showing how default\nvalues in @-patterns do not propagate into the aliased variable.
nix-repl> f = { x ? 2, y ? 4 }: x + y\n\nnix-repl> f { }\n6\nThe 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\n(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\nafter destructuring:
nix-repl> f = { x ? 1, y ? 2, ... }@args: with args; x + y + z\n\nnix-repl> f { z = 3; }\n6\nThe { x ? 1, y ? 2, ... } syntax means x and y have defaults, while ...\nallows additional attributes.
@args binds the entire attribute set (args) so that we can access z, which\nwouldn’t be destructured by default.
When calling f { z = 3; }, we pass an extra attribute (z = 3), making\nx + y + z → 1 + 2 + 3 = 6.
There is a keyword import, but it’s equivalent in other languages is eval. It\ncan be used for namespacing too:
\nlet\n pkgs = import <nixpkgs> {};\n lib = import <nixpkgs/lib>;\nin\n pkgs.runCommand (lib.strings.removePrefix \"....\nconsider using import here as using qualified import ... in Haskell or\nimport ... in Python.
Another way of importing is with import ...;, which corresponds to Python\nfrom ... import *.
But because of not very great IDE support in Nix, with import ...; is\ndiscouraged. Rather use inherit, especially if you are targeting source code for\nNix newcomers:
let\n lib = import <nixpkgs/lib>;\n inherit (lib.strings)\n removePrefix removeSuffix\n ;\n inherit (lib.lists)\n isList init drop\n ;\nin\n removePrefix ...\ninherit has higher priority than with, and conflicts with let
nix-repl> let pkgs = { x = 1; }; x = 2; x = 3; inherit (pkgs) x; in x\nerror: attribute ‘x’ at (string):1:31 already defined at (string):1:24\nThis makes it a sane citizen of Nix lanugage… except it has a twin, called\n{ inherit ...; }. They DON’T do the same - let inherit ... adds\nlet-bindings, and { inherit ...; } adds attributes to a record.\n–https://nixos.wiki/wiki/Nix_Language_Quirks
nix-repl> let ${\"y\"} = 4; in y\n4\n\nnix-repl> with { ${\"y\"} = 4; }; y\n4\n\nlet y = 1; x = ${y}; in x\nerror: syntax error, unexpected DOLLAR_CURLY\nConclusion
\nlet bindings introduce new local values and override anything from with.
with doesn’t create bindings - it only makes attributes available within its\nscope.
The order matters: If let x = 4 is outside with, then x = 4 already\nexists before with runs, so with pkgs; x resolves to 4, not the value\nfrom pkgs.
A few resources to help get you started with the Nix Language, I have actually\ngrown to love the language. I find it fairly simple but powerful!
\nbuiltins.head[ 5 6 7 ]\nNix is a purely functional package manager. This means that it treats packages\nlike values in purely functional programming languages – they are built by\nfunctions that don’t have side-effects, and they never change after they have\nbeen built.
\nNix stores packages in the Nix store, usually the directory /nix/store,\nwhere each package has its own unique subdirectory such as:
/nix/store/y53c0lamag5wpx7vsiv7wmnjdgq97yd6-yazi-25.5.14pre20250526_74a8ea9\nYou can use the Nix on most Linux distributions and Mac OS also has good support\nfor Nix. It should work on most platforms that support POSIX threads and have a\nC++11 compiler.
\nWhen I install Nix on a distro like Arch Linux I usually use the Zero to Nix\ninstaller as it automates several steps, such as enabling flakes by default:
\ncurl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install\nIf you have concerns about the “curl to Bash” approach you could examine the\ninstallation script\nhere\nthen download and run it:
\ncurl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix > nix-installer.sh\nchmod +x nix-installer.sh\n./nix-installer.sh install\nI got the above commands from\nzero-to-nix
\nThe main difference between using the nix package manager on another\ndistribution and NixOS is that NixOS uses Nix not just for package management\nbut also to manage the system configuration (e.g., to build config files in\n/etc).
Home Manager is a Nix-powered\ntool for reproducible management of the contents of the users’ home directories.\nThis includes programs, configuration files, environment variables, and\narbitrary files. Home manager uses the same module system as NixOS.
\nNow that we’ve discussed some of the basics of the Nix package manager, lets see\nhow it is used to build and manage software in NixOS.
\nNix packages are distributed through Nix channels; mechanisms for distributing\nNix expressions and the associated binary caches for them. Channels are what\ndetermine which versions your packages have. (i.e. stable or unstable). A\nchannel is a name for the latest “verified” git commits in Nixpkgs. Each channel\nrepresents a different policy for what “verified” means. Whenever a new commit\nin Nixpkgs passes the verification process, the respective channel is updated\nto point to that new commit.
While channels provide a convenient way to get the latest stable or unstable\npackages, they introduce a challenge for strict reproducibility. Because a\nchannel like nixos-unstable is constantly updated, fetching packages from it\ntoday might give you a different set of package versions than fetching from it\ntomorrow, even if your configuration remains unchanged. This “rolling release”\nnature at a global level can make it harder to share and reproduce exact\ndevelopment environments or system configurations across different machines or\nat different points in time.
Before the introduction of Nix Flakes, channels were the primary mechanism\nfor sourcing Nixpkgs. While functional, they posed a challenge for exact\nreproducibility because they point to a moving target (the latest commit on a\nbranch). This meant that a nix-build command run yesterday might produce a\ndifferent result than one run today, simply because the channel updated.
Nix Flakes were introduced to address this. Flakes bring a built-in,\nstandardized way to define the exact inputs to a Nix build, including the\nprecise Git revision of Nixpkgs or any other dependency.
Here’s a quick comparison:
\n| 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\nflake.lock file is a game-changer for collaboration and long-term\nreproducibility, ensuring that your Nix configuration builds the same way, every\ntime, everywhere.
Nixpkgs is the largest repository of Nix packages and NixOS modules.
\nFor NixOS users, nixos-unstable channel branch is the rolling release,\nwhere the packages are tested and must pass integration tests.
For standalone Nix users, nixpkgs-unstable channel branch is the rolling\nrelease, 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\nlisted as an input to your flake. (e.g.,\ninputs.nixpkgs.url = \"github:nixos/nixpkgs/nixos-unstable\";) When using flakes\nyou can actually disable channels and actually recommended to avoid conflicts\nbetween traditional channel-based workflows and the flake system.
The mechanism for updating your Nix environment differs fundamentally between\nchannels and flakes, directly impacting reproducibility and control.
\nWith channels, updates are a global operation that pulls the latest state of a\nspecific branch.
\nHow it works: You typically use nix-channel --update to fetch the latest\ncommit from the channels you’ve subscribed to. For instance,\nsudo nix-channel --update nixos (for NixOS) or nix-channel --update nixpkgs\n(for nix-env on other Linux distributions).
Implication: This command updates your local system’s understanding of what\n“nixos” or “nixpkgs-unstable” means. From that point on, any\nnixos-rebuild switch, nix-env -iA, or nix-build commands that implicitly\nor explicitly refer to nixpkgs will use this newly updated version.
Reproducibility Challenge: The update itself is not recorded in your\nconfiguration files. If you share your configuration.nix with someone, they\nmight run nix-channel --update on a different day and get a different set of\npackage versions because the channel has moved. This makes it challenging to\nguarantee that two users building the “same” configuration will get identical\nresults. You’re effectively relying on the implicit, globally managed state of\nyour channels.
Flakes, by contrast, use a more explicit and localized update mechanism tied\nto your flake.lock file.
How it works: When you define a flake.nix, you specify the exact URL\n(e.g., a Git repository with a specific branch or tag) for each input. When you\nfirst use a flake, Nix resolves these URLs to a precise Git commit hash and\nrecords 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.,\ngithub:NixOS/nixpkgs/nixos-unstable) and fetches the latest commit for that\ninput. It then updates your flake.lock file with the new, precise Git commit\nhash and content hash for that input. Your flake.nix itself doesn’t change,\nbut the flake.lock file now points to newer versions of your dependencies.
Reproducibility Advantage: The flake.lock file acts as a manifest of your\nexact dependency versions.
Sharing: When you share your flake (the flake.nix and flake.lock files),\nanyone using it will fetch precisely the same Git commit hashes recorded in the\nflake.lock, guaranteeing identical inputs and thus, identical builds (assuming\nthe same system architecture).
Updating Selectively: You can update individual inputs within your flake by\nspecifying them: nix flake update nixpkgs. This provides fine-grained control\nover which parts of your dependency graph you want to advance.
Rolling Back: Because the flake.lock explicitly records the versions, you\ncan easily revert to a previous state by checking out an older flake.lock from\nyour version control system.
In essence: Channels involve a global “pull” of the latest branch state,\nmaking reproducibility harder to guarantee across time and machines. Flakes,\nhowever, explicitly pin all inputs in flake.lock, and updates involve\nexplicitly refreshing these pins, providing strong reproducibility and version\ncontrol out of the box.
Derivation Overview
\nIn Nix, the process of managing software starts with package definitions.\nThese are files written in the Nix language that describe how a particular piece\nof software should be built. These package definitions, when processed by Nix,\nare translated into derivations.
\nAt its core, a derivation in Nix is a blueprint or a recipe that describes how\nto build a specific software package or any other kind of file or directory.\nIt’s a declarative specification of:
\nInputs: What existing files or other derivations are needed as\ndependencies.
\nBuild Steps: The commands that need to be executed to produce the desired\noutput.
\nEnvironment: The specific environment (e.g., build tools, environment\nvariables) required for the build process.
\nOutputs: The resulting files or directories that the derivation produces.
\nThink of a package definition as the initial instructions, and the derivation as\nthe detailed, low-level plan that Nix uses to actually perform the build.
\nAgain, a derivation is like a blueprint that describes how to build a specific\nsoftware package or any other kind of file or directory.
\nKey Characteristics of Derivations:
\nDeclarative: You describe the desired outcome and the inputs, not the\nexact sequence of imperative steps. Nix figures out the necessary steps based\non the builder and args.
\nReproducible: Given the same inputs and build instructions, a derivation\nwill always produce the same output. This is a cornerstone of Nix’s\nreproducibility.
\nTracked by Nix: Nix keeps track of all derivations and their outputs in\nthe Nix store. This allows for efficient management of dependencies and\nensures that different packages don’t interfere with each other.
\nContent-Addressed: The output of a derivation is stored in the Nix store\nunder a unique path that is derived from the hash of all its inputs and build\ninstructions. This means that if anything changes in the derivation, the\noutput will have a different path.
\nHere’s a simple Nix derivation that creates a file named hello in the Nix store\ncontaining the text “Hello, World!”:
\n{pkgs ? import <nixpkgs> {}}:\npkgs.stdenv.mkDerivation {\n name = \"hello-world\";\n\n dontUnpack = true;\n\n # No need for src = null; when dontUnpack = true;\n # src = null;\n\n buildPhase = ''\n # Create a shell script that prints \"Hello, World!\"\n echo '#!${pkgs.bash}/bin/bash' > hello-output-file # Shebang line\n echo 'echo \"Hello, World!\"' >> hello-output-file # The command to execute\n chmod +x hello-output-file # Make it executable\n '';\n\n installPhase = ''\n mkdir -p $out/bin\n cp hello-output-file $out/bin/hello # Copy the file from build directory to $out/bin\n '';\n\n meta = {\n description = \"A simple Hello World program built with Nix\";\n homepage = null;\n license = pkgs.lib.licenses.unfree; # licenses.mit is often used as well\n maintainers = [];\n };\n}\nAnd a default.nix with the following contents:
{ pkgs ? import <nixpkgs> {} }:\n\nimport ./hello.nix { pkgs = pkgs; }\n{ pkgs ? import <nixpkgs> {} }: This is a function that takes an optional\nargument pkgs. We need Nixpkgs to access standard build environments like\nstdenv.
pkgs.stdenv.mkDerivation { ... }: This calls the mkDerivation function from\nthe standard environment (stdenv). mkDerivation is the most common way to\ndefine software packages in Nix.
name = \"hello-world\";: Human-readable name of the derivation
The rest are the build phases and package metadata.
\nTo use the above derivation, save it as a .nix file (e.g. hello.nix). Then\nbuild the derivation using,:
nix-build\nthis derivation will be built:\n /nix/store/9mc855ijjdy3r6rdvrbs90cg2gf2q160-hello-world.drv\nbuilding '/nix/store/9mc855ijjdy3r6rdvrbs90cg2gf2q160-hello-world.drv'...\nRunning phase: patchPhase\nRunning phase: updateAutotoolsGnuConfigScriptsPhase\nRunning phase: configurePhase\nno configure script, doing nothing\nRunning phase: buildPhase\nRunning phase: installPhase\nRunning phase: fixupPhase\nshrinking RPATHs of ELF executables and libraries in /nix/store/2ydxh5pd9a6djv7npaqi9rm6gmz2f73b-hello-world\nchecking for references to /build/ in /nix/store/2ydxh5pd9a6djv7npaqi9rm6gmz2f73b-hello-world...\npatching script interpreter paths in /nix/store/2ydxh5pd9a6djv7npaqi9rm6gmz2f73b-hello-world\nstripping (with command strip and flags -S -p) in /nix/store/2ydxh5pd9a6djv7npaqi9rm6gmz2f73b-hello-world/bin\n/nix/store/2ydxh5pd9a6djv7npaqi9rm6gmz2f73b-hello-world\nNix will execute the buildPhase and installPhase
After a successful build, the output will be in the Nix store. You can find\nthe exact path by looking at the output of the nix build command (it will be\nsomething like /nix/store/your-hash-hello-world).
Run the “installed” program:
\n./result/bin/hello\nhello file from the Nix store and print\n\"Hello, World!\".The following examples are done with a local nixpkgs clone located at\n~/src/nixpkgs
Paths in Nix always need a / in them and always expand to absolute paths\nrelative to your current directory.
nix repl\nnix-repl> ./.\n/home/jr/src/nixpkgs\nnix-repl> ./. + \"/lib\"\n/home/jr/src/nixpkgs/lib\nNix does path normalization every time you append strings, so if you just add\na slash / its not actually there:
nix-repl> ./.\n/home/jr/src/nixpkgs\nnix-repl> ./. + \"/\"\n/home/jr/src/nixpkgs\nnix-repl> ./. + \"/\" + \"lib\"\n/home/jr/src/nixpkgslib\nnix-repl> \"${./.}/lib\"\n# using ${./.} causes a store copy\ncopying '/homr/jr/src/nixpkgs' to the store\n\"/nix/store/3z9fzx8z03wslxvri5syv3jnnhn5fkbd-nixpkgs/lib\"\nnix-repl> \"${toString ./.}/lib\"\n# using toString avoids making a store copy\n\"/home/jr/src/nixpkgs/lib\"\nnix-repl> ./lib/.. # nix removes all `..` to avoid redundant path resolutions\n/home/jr/src/nixpkgs\nnix-repl> :q\nrealpath ./lib/..\n/home/jr/src/nixpkgs\nln -s pkgs/applications lib-symlink\nrealpath ./lib-symlink/..\n/home/jr/src/nixpkgs/pkgs\nnix repl\nnix-repl> ./lib-symlink/.. # Nix doesn't read this file at all like realpath did\n/home/jr/src/nixpkgs\nnix-repl> builtins.readDir ./. # listing of all entries in current dir and their types\n{\n \".devcontainer\" = \"directory\";\n \".editorconfig\" = \"regular\";\n \".git\" = \"directory\";\n \".git-blame-ignore-revs\" = \"regular\";\n \".gitattributes\" = \"regular\";\n \".github\" = \"directory\";\n \".gitignore\" = \"regular\";\n \".mailmap\" = \"regular\";\n \".mergify.yml\" = \"regular\";\n \".version\" = \"symlink\";\n \"CONTRIBUTING.md\" = \"regular\";\n COPYING = \"regular\";\n \"README.md\" = \"regular\";\n ci = \"directory\";\n \"default.nix\" = \"regular\";\n doc = \"directory\";\n \"flake.nix\" = \"regular\";\n lib = \"directory\";\n maintainers = \"directory\";\n nixos = \"directory\";\n pkgs = \"directory\";\n \"shell.nix\" = \"regular\";\n}\nnix-repl> builtins.readFile ./default.nix\n\"let\\n requiredVersion = import ./lib/minver.nix;\\nin\\n\\nif !builtins ? nixVersion\n || builtins.compareVersions requiredVersion builtins.nixVersion == 1 then\\n\\n abort\n ''\\n\\n This version of Nixpkgs requires Nix >= \\${requiredVersion}, please\n upgrade:\\n\\n - If you are running NixOS, `nixos-rebuild' can be used to upgrade\n your system.\\n\\n - Alternatively, with Nix > 2.0 `nix upgrade-nix' can be used\n to imperatively\\n upgrade Nix. You may use `nix-env --version' to check which\n version you have.\\n\\n - If you installed Nix using the install script (https://nixos.org/nix/install),\\n\n it is safe to upgrade by running it again:\\n\\n curl -L https://nixos.org/nix/install | sh\\n\\n\nFor more information, please see the NixOS release notes at\\n https://nixos.org/nixos/manual\n or locally at\\n \\${toString ./nixos/doc/manual/release-notes}.\\n\\n If you need further help,\n see https://nixos.org/nixos/support.html\\n ''\\n\\nelse\\n\\n import ./pkgs/top-level/impure.nix\\n\"\nnix-repl> :l <nixpkgs/lib>\nnix-repl> importJSON ./pkgs/development/python-modules/notebook/missing-hashes.json # Return the nix value for JSON\n{\n \"@nx/nx-darwin-arm64@npm:16.10.0\" = \"aabcc8499602b98c9fc3b768fe46dfd4e1b818caa84b740bd4f73a2e4528c719b979ecb1c10a0d793a1fead83073a08bc86417588046aa3e587e80af880bffd3\";\n \"@nx/nx-darwin-x64@npm:16.10.0\" = \"9dd20f45f646d05306f23f5abb7ade69dcb962e23a013101e93365847722079656d30a19c735fdcfa5c4e0fdf08691f9d621073c58aef2861c26741ff4638375\";\n \"@nx/nx-freebsd-x64@npm:16.10.0\" = \"35b93aabe3b3274d53157a6fc10fec7e341e75e6818e96cfbc89c3d5b955d225ca80a173630b6aa43c448c6b53b23f06a2699a25c0c8bc71396ee20a023d035f\";\n \"@nx/nx-linux-arm-gnueabihf@npm:16.10.0\" = \"697b9fa4c70f84d3ea8fe32d47635864f2e40b0ceeb1484126598c61851a2ec34b56bb3eeb9654c37d9b14e81ce85a36ac38946b4b90ca403c57fe448be51ccb\";\n \"@nx/nx-linux-arm64-gnu@npm:16.10.0\" = \"001e71fedfc763a4dedd6c5901b66a4a790d388673fb74675235e19bb8fe031ff3755568ed867513dd003f873901fabda31a7d5628b39095535cb9f6d1dc7191\";\n \"@nx/nx-linux-arm64-musl@npm:16.10.0\" = \"58e3b71571bdadd2b0ddd24ea6e30cd795e706ada69f685403412c518fba1a2011ac8c2ac46145eab14649aa5a78e0cedcdb4d327ccb3b6ec12e055171f3840b\";\n \"@nx/nx-linux-x64-gnu@npm:16.10.0\" = \"97729a7efb27301a67ebf34739784114528ddb54047e63ca110a985eaa0763c5b1ea7c623ead1a2266d07107951be81e82ffa0a30e6e4d97506659303f2c8c78\";\n \"@nx/nx-linux-x64-musl@npm:16.10.0\" = \"442bdbd5e61324a850e4e7bd6f54204108580299d3c7c4ebcec324da9a63e23f48d797a87593400fc32af78a3a03a3c104bfb360f107fe732e6a6c289863853a\";\n \"@nx/nx-win32-arm64-msvc@npm:16.10.0\" = \"b5c74184ebfc70294e85f8e309f81c3d40b5cf99068891e613f3bef5ddb946bef7c9942d9e6c7688e22006d45d786342359af3b4fc87aadf369afcda55c73187\";\n \"@nx/nx-win32-x64-msvc@npm:16.10.0\" = \"c5b174ebd7a5916246088e17d3761804b88f010b6b3f930034fa49af00da33b6d1352728c733024f736e4c2287def75bafdc3d60d8738bd24b67e9a4f11763f8\";\n}\nnix-repl> builtins.toJSON # serialize\n«primop toJSON»\nnix-repl> builtins.fromTOML\n«primop fromTOML»\nnix-repl> builtins.toXML\nFor more serialization formats see nixpkgs/lib/generators.nix as well as in\nnixpkgs/pkgs/pkgs-lib/formats/ we can see them with the nix repl as follows:
cd ~/src/nixpkgs\nnix repl\nnix-repl> :l .\nnix-repl> lib.generators.toYAML {} { a = 10; }\n\"{\\\"a\\\":10}\"\nnix-repl> lib.generators.toYAML {} { a.b.c = 10; }\n\"{\\\"a\\\":{\\\"b\\\":{\\\"c\\\":10}}}\"\nnix-repl> builtins.trace (lib.generators.toYAML {} { a.b.c = 10; }) null\ntrace: {\"a\":{\"b\":{\"c\":10}}}\nnull\nnix-repl> yamlFormat = pkgs.formats.yaml {}\n\nnix-repl> yamlFormat\n{\n generate = «lambda generate @ /home/jr/src/nixpkgs/pkgs/pkgs-lib/formats.nix:111:9»;\n type = { ... };\n}\ngenerate function that we can use. generate\ndoesn’t just generate a string anymore because if we want to lift the\nrestriction at evaluation time we can’t return the formatted form at\nevaluation time anymore. We need a name to return a derivation continued\nbelow:yamlFormat.generate \"name\" { a.b.c = 10; }\n«derivation /nix/store/xakajb2rzbmqqkjbh08bxwqdf0xqvjly-name.drv»\nnix-repl> :b yamlFormat.generate \"name\" { a.b.c = 10; }\nThis derivation produced the following outputs:\nout -> /nix/store/y4c5029k6w3l0qmdw7cq396zrdy5x8yj-name\nnix-repl> :q\nLet’s cat the result to see if it’s formatted correctly as YAML:
\ncat /nix/store/y4c5029k6w3l0qmdw7cq396zrdy5x8yj-name\n───────┬───────────────────────────────────────────────────────────────\n │ File: /nix/store/y4c5029k6w3l0qmdw7cq396zrdy5x8yj-name\n───────┼──────────────────────────────────────────────────────────────\n 1 │ a:\n 2 │ b:\n 3 │ c: 10\n───────┴───────────────────────────────────────────────────────────\nLooks good. There is also a type:
nix repl\nnix-repl> :l .\nnix-repl> yamlFormat = pkgs.format.yaml {}\nnix-repl> yamlFormat.type\n{\n _type = \"option-type\";\n check = «lambda check @ /home/jr/src/nixpkgs/lib/types.nix:1029:19»;\n deprecationMessage = null;\n description = \"YAML value\";\n descriptionClass = \"conjunction\";\n emptyValue = { ... };\n functor = { ... };\n getSubModules = null;\n getSubOptions = «lambda @ /home/jr/src/nixpkgs/lib/types.nix:214:25»;\n merge = «lambda merge @ /home/jr/src/nixpkgs/lib/types.nix:1031:13»;\n name = \"nullOr\";\n nestedTypes = { ... };\n substSubModules = «lambda substSubModules @ /home/jr/src/nixpkgs/lib/types.nix:1046:29»;\n typeMerge = «lambda defaultTypeMerge @ /home/jr/src/nixpkgs/lib/types.nix:115:10»;\n}\nnix-repl> lib.modules.mergeDefinitions [] yamlFormat.type [ { value = null; } ]\n{\n defsFinal = [ ... ];\n defsFinal' = { ... };\n isDefined = true;\n mergedValue = null;\n optionalValue = { ... };\n}\nnix-repl> (lib.modules.mergeDefinitions [] yamlFormat.type [ { value = null; } ]).mergedValue\nnull\nnix-repl> :p (lib.modules.mergeDefinitions [] yamlFormat.type [ { value = { a.b.c = 10; }; } ]).mergedValue\n{\n a = {\n b = { c = 10; };\n };\n}\nnix-repl> :p (lib.modules.mergeDefinitions [] yamlFormat.type [ { value = { a.b.c = 10; }; } { value = { a.b.d = 20; }; } ]).mergedValue\n{\n a = {\n b = {\n c = 10;\n d = 20;\n };\n };\n}\nlib can’t access any packages, it is entirely at evaluation time. It can’t\naccess any formatters or things like that. If we lift that restriction as is\ndone in pkgs.formats we can make it look much nicer.cd ~/src/nixpkgs\nnix-build -A hello\nwarning: Nix search path entry '/nix/var/nix/profiles/per-user/root/channels' does not exist, ignoring\nthis path will be fetched (0.06 MiB download, 0.26 MiB unpacked):\n /nix/store/29mhfr5g4dsv07d80b7n4bgs45syk3wl-hello-2.12.2\ncopying path '/nix/store/29mhfr5g4dsv07d80b7n4bgs45syk3wl-hello-2.12.2' from 'https://cache.nixos.org'...\n/nix/store/29mhfr5g4dsv07d80b7n4bgs45syk3wl-hello-2.12.2\nSay we rely on this store path in a derivation:
\nnix-repl> thePath = \"/nix/store/29mhfr5g4dsv07d80b7n4bgs45syk3wl-hello-2.12.2\"\nnix-repl> thePath + \"/bin/hello\"\n\"/nix/store/29mhfr5g4dsv07d80b7n4bgs45syk3wl-hello-2.12.2/bin/hello\"\nhx ~/src/nixpkgs/test2.nix\n# test2.nix\nwith import ./. {};\n\nrunCommand \"test\" {\n nativeBuildInputs = [\n hello\n ];\n}''\n hello > $out\n''\nTry building it:
\nnix-build test2.nix && cat result\nwarning: Nix search path entry '/nix/var/nix/profiles/per-user/root/channels' does not exist, ignoring\n/nix/store/m55p4vpb8s7s28s20vs89i467kxbrdac-test\nHello, world!\nNow if we try it with the store path:
\n# test2.nix\nwith import ./. {};\n\nrunCommand \"test\" {\n}''\n /nix/store/29mhfr5g4dsv07d80b7n4bgs45syk3wl-hello-2.12.2/bin/hello > $out\n''\nThis doesn’t work
\nnix-build test2.nix\nlast 1 log lines:\n> /build/.attr-0l2nkwhif96f51f4amnlf414lhl4rv9vh8iffyp431v6s28gsr90: line 1: /nix/store/29mhfr5g4dsv07d80b7n4bgs45syk3wl-hello-2.12.2/bin/hello: No such file or directory\nFor full logs, run:\nnix log /nix/store/58zcp9xwgf1sirmzf9sh61j8gz9lkw34-test.drv\nnix-instantiate test2.nix\n/nix/store/58zcp9xwgf1sirmzf9sh61j8gz9lkw34-test.drv\nnix derivation show /nix/store/58zcp9xwgf1sirmzf9sh61j8gz9lkw34-test.drv | jq\n{\n \"/nix/store/58zcp9xwgf1sirmzf9sh61j8gz9lkw34-test.drv\": {\n \"args\": [\n \"-e\",\n \"/nix/store/vj1c3wf9c11a0qs6p3ymfvrnsdgsdcbq-source-stdenv.sh\",\n \"/nix/store/shkw4qm9qcw5sc5n1k5jznc83ny02r39-default-builder.sh\"\n ],\n \"builder\": \"/nix/store/xy4jjgw87sbgwylm5kn047d9gkbhsr9x-bash-5.2p37/bin/bash\",\n \"env\": {\n \"__structuredAttrs\": \"\",\n \"buildCommand\": \"/nix/store/29mhfr5g4dsv07d80b7n4bgs45syk3wl-hello-2.12.2/bin/hello > $out\\n\",\n \"buildInputs\": \"\",\n \"builder\": \"/nix/store/xy4jjgw87sbgwylm5kn047d9gkbhsr9x-bash-5.2p37/bin/bash\",\n \"cmakeFlags\": \"\",\n \"configureFlags\": \"\",\n \"depsBuildBuild\": \"\",\n \"depsBuildBuildPropagated\": \"\",\n \"depsBuildTarget\": \"\",\n \"depsBuildTargetPropagated\": \"\",\n \"depsHostHost\": \"\",\n \"depsHostHostPropagated\": \"\",\n \"depsTargetTarget\": \"\",\n \"depsTargetTargetPropagated\": \"\",\n \"doCheck\": \"\",\n \"doInstallCheck\": \"\",\n \"enableParallelBuilding\": \"1\",\n \"enableParallelChecking\": \"1\",\n \"enableParallelInstalling\": \"1\",\n \"mesonFlags\": \"\",\n \"name\": \"test\",\n \"nativeBuildInputs\": \"\",\n \"out\": \"/nix/store/ljrkx5midby3j7p4g96d74jrq8f9rpya-test\",\n \"outputs\": \"out\",\n \"passAsFile\": \"buildCommand\",\n \"patches\": \"\",\n \"propagatedBuildInputs\": \"\",\n \"propagatedNativeBuildInputs\": \"\",\n \"stdenv\": \"/nix/store/aq801xbgs98nxx3lckrym06qfvl8mfsf-stdenv-linux\",\n \"strictDeps\": \"\",\n \"system\": \"x86_64-linux\"\n },\n \"inputDrvs\": {\n \"/nix/store/bmncp7arkdhrl6nkyg0g420935x792gl-stdenv-linux.drv\": {\n \"dynamicOutputs\": {},\n \"outputs\": [\n \"out\"\n ]\n },\n \"/nix/store/rfkzz952hz2d58d90mscxvk87v5wa5bz-bash-5.2p37.drv\": {\n \"dynamicOutputs\": {},\n \"outputs\": [\n \"out\"\n ]\n }\n },\n \"inputSrcs\": [\n \"/nix/store/shkw4qm9qcw5sc5n1k5jznc83ny02r39-default-builder.sh\",\n \"/nix/store/vj1c3wf9c11a0qs6p3ymfvrnsdgsdcbq-source-stdenv.sh\"\n ],\n \"name\": \"test\",\n \"outputs\": {\n \"out\": {\n \"path\": \"/nix/store/ljrkx5midby3j7p4g96d74jrq8f9rpya-test\"\n }\n },\n \"system\": \"x86_64-linux\"\n }\n}\nYou see the \"inputDrvs\", they are the derivations that we depend on and it\ndoesn’t know about the hello.drv. In Nix for the builder sandbox it creates a\nsandbox that only contains the derivations that you depend on which ensures that\nyou 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\nkind of an anti pattern.
# test2.nix\n# test2.nix\n# test2.nix\nwith import ./. {};\n runCommand \"test\" {\n } ''\n ${builtins.storePath \"/nix/store/29mhfr5g4dsv07d80b7n4bgs45syk3wl-hello-2.12.2\"}/bin/hello > $out\n ''\nbuiltins.storePath: Turns a store path into the thing that it represents in\nthe store.
nix-build test2.nix && cat result\n/nix/store/x48741w0k9hgqywzv6wc7rk90r1y75js-test\nHello, world!\nTo demonstrate what builtins.storePath does:
nix-repl> builtins.storePath \"/nix/store/29mhfr5g4dsv07d80b7n4bgs45syk3wl-hello-2.12.2/bin/hello\"\n\"/nix/store/29mhfr5g4dsv07d80b7n4bgs45syk3wl-hello-2.12.2/bin/hello\"\nnix-repl> builtins.getContext \"/nix/store/29mhfr5g4dsv07d80b7n4bgs45syk3wl-hello-2.12.2\"\n{ }\nnix-repl> builtins.getContext (builtins.storePath \"/nix/store/29mhfr5g4dsv07d80b7n4bgs45syk3wl-hello-2.12.2\")\n{\n \"/nix/store/29mhfr5g4dsv07d80b7n4bgs45syk3wl-hello-2.12.2\" = { ... };\n}\nnix-repl> :p builtins.getContext (builtins.storePath \"/nix/store/29mhfr5g4dsv07d80b7n4bgs45syk3wl-hello-2.12.2\")\n{\n \"/nix/store/29mhfr5g4dsv07d80b7n4bgs45syk3wl-hello-2.12.2\" = { path = true; };\n}\nnix-repl> :l .\nwarning: Nix search path entry '/nix/var/nix/profiles/per-user/root/channels' does not exist, ignoring\nAdded 24878 variables.\n\nnix-repl> hello.outPath\n# this is the output path of the hello derivation\n\"/nix/store/29mhfr5g4dsv07d80b7n4bgs45syk3wl-hello-2.12.2\"\nnix-repl> :p builtins.getContext hello.outPath\n# we see that this is a `.drv`, this is because derivations can have multiple outputs\n{\n \"/nix/store/ljxsxdy1syy03b9kfnnh8x7zsk21fdcq-hello-2.12.2.drv\" = {\n outputs = [ \"out\" ];\n };\n}\n# for example\nnix-repl> openssl.outputs\n[\n \"bin\"\n \"dev\"\n \"out\"\n \"man\"\n \"doc\"\n \"debug\"\n]\nnix-repl> openssl.all\n# a list of all the derivations\n[\n «derivation /nix/store/rw3y8k94ib37dc86n0wivr551wyzxgsk-openssl-3.4.1.drv»\n «derivation /nix/store/rw3y8k94ib37dc86n0wivr551wyzxgsk-openssl-3.4.1.drv»\n «derivation /nix/store/rw3y8k94ib37dc86n0wivr551wyzxgsk-openssl-3.4.1.drv»\n «derivation /nix/store/rw3y8k94ib37dc86n0wivr551wyzxgsk-openssl-3.4.1.drv»\n «derivation /nix/store/rw3y8k94ib37dc86n0wivr551wyzxgsk-openssl-3.4.1.drv»\n «derivation /nix/store/rw3y8k94ib37dc86n0wivr551wyzxgsk-openssl-3.4.1.drv»\n]\nnix-repl> lib.concatStringsSep \" \" openssl.all\n\"/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\"\nnix-repl> :p builtins.getContext (builtins.unsafeDiscardOutputDependency (lib.concatStringsSep \" \" openssl.all))\n{\n \"/nix/store/rw3y8k94ib37dc86n0wivr551wyzxgsk-openssl-3.4.1.drv\" = {\n outputs = [\n \"bin\"\n \"debug\"\n \"dev\"\n \"doc\"\n \"man\"\n \"out\"\n ];\n };\n}\nnix-repl> :p builtins.getContext openssl.drvPath\n{\n \"/nix/store/rw3y8k94ib37dc86n0wivr551wyzxgsk-openssl-3.4.1.drv\" = { allOutputs = true; };\n}\n# useful if you need to create a derivation that copies this derivation to another machine\n# remote builders usually take care of this but you may need it occasionally\nnix-repl> :p builtins.getContext (builtins.unsafeDiscardOutputDependency openssl.drvPath)\n{\n \"/nix/store/rw3y8k94ib37dc86n0wivr551wyzxgsk-openssl-3.4.1.drv\" = { path = true; };\n}\nRelying on paths outside of the nix store is generally not recommended because\nof garbage collection and it’s considered unsafe.
\n", "date_published": "2025-11-22T00:00:00+00:00", "author": { "name": "saylesss87@proton.me (saylesss88)" } }, { "id": "https://saylesss88.github.io/functions/practical_functions_2.1.html", "url": "https://saylesss88.github.io/functions/practical_functions_2.1.html", "title": "Practical Nix Functions", "content_html": "![\"coding6\"](\"https://saylesss88.github.io/images/coding6.png\")
# autotools.nix\npkgs: attrs:\nwith pkgs; let\n defaultAttrs = {\n builder = \"${bash}/bin/bash\";\n args = [./builder.sh];\n setup = ./setup.sh;\n baseInputs = [gnutar gzip gnumake gcc binutils-unwrapped coreutils gawk gnused gnugrep patchelf findutils];\n buildInputs = [];\n system = builtins.currentSystem;\n };\nin\n derivation (defaultAttrs // attrs)\nsetup.sh:# setup.sh (This is a library of functions setting up the environment, not directly executable)\nunset PATH\nfor p in $baseInputs $buildInputs; do\n if [ -d $p/bin ]; then\n export PATH=\"$p/bin${PATH:+:}$PATH\"\n fi\n if [ -d $p/lib/pkgconfig ]; then\n export PKG_CONFIG_PATH=\"$p/lib/pkgconfig${PKG_CONFIG_PATH:+:}$PKG_CONFIG_PATH\"\n fi\ndone\n\nfunction unpackPhase() {\n tar -xzf $src\n\n for d in *; do\n if [ -d \"$d\" ]; then\n cd \"$d\"\n break\n fi\n done\n}\n\nfunction configurePhase() {\n ./configure --prefix=$out\n}\n\nfunction buildPhase() {\n make\n}\n\nfunction installPhase() {\n make install\n}\n\nfunction fixupPhase() {\n find $out -type f -exec patchelf --shrink-rpath '{}' \\; -exec strip '{}' \\; 2>/dev/null\n}\n\nfunction genericBuild() {\n unpackPhase\n configurePhase\n buildPhase\n installPhase\n fixupPhase\n}\nbuilder.sh:# builder.sh (This is the actual builder script specified in the derivation and\n# what `nix-build` expects)\nset -e\nsource $setup\ngenericBuild\nThis is another example from the Nix-Pill series shown in another way to show\nsome powerful aspects of functions.
\nIf you have a default.nix like this:
# default.nix\n{\n hello = import ./hello.nix;\n graphviz = import ./graphviz.nix;\n}\nIt expects the files that it imports to look like this:
\n# graphviz.nix\nlet\n pkgs = import <nixpkgs> { };\n mkDerivation = import ./autotools.nix pkgs;\nin\nmkDerivation {\n name = \"graphviz\";\n src = ./graphviz-2.49.3.tar.gz;\n}\nAnd hello.nix:
# hello.nix\nlet\n pkgs = import <nixpkgs> { };\n mkDerivation = import ./autotools.nix pkgs;\nin\nmkDerivation {\n name = \"hello\";\n src = ./hello-2.12.1.tar.gz;\n}\nYou would build these with:
\nnix-build -A hello\nnix-build -A graphviz\nAs you can see both derivations are dependendent on nixpkgs which they\nboth import directly. To centralize our dependencies and avoid redundant\nimports, we’ll refactor our individual package definitions (hello.nix,\ngraphviz.nix) into functions. Our default.nix will then be responsible for\nsetting up the common inputs (like pkgs and mkDerivation) and passing them\nas arguments when it imports and calls these package functions.
Here is what our default.nix will look like:
let\n pkgs = import <nixpkgs> { };\n mkDerivation = import ./autotools.nix pkgs;\nin\nwith pkgs;\n{\n hello = import ./hello.nix { inherit mkDerivation; };\n graphviz = import ./graphviz.nix {\n inherit\n mkDerivation\n lib\n gd\n pkg-config\n ;\n };\n graphvizCore = import ./graphviz.nix {\n inherit\n mkDerivation\n lib\n gd\n pkg-config\n ;\n gdSupport = false;\n };\n}\nWe 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\nthe keys hello, graphviz, and graphvizCore
We import hello.nix and graphviz.nix, which both return a function. We call\nthe 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\nexpects.
# hello.nix\n{mkDerivation}:\nmkDerivation {\n name = \"hello\";\n src = ./hello-2.12.1.tar.gz;\n}\nNow our graphviz attribute expects graphviz.nix to be a function that takes\nthe arguments listed in the above default.nix, here’s what graphviz.nix will\nlook like as a function:
# graphviz.nix\n{\n mkDerivation,\n lib,\n gdSupport ? true,\n gd,\n pkg-config,\n}:\nmkDerivation {\n name = \"graphviz\";\n src = ./graphviz-2.49.3.tar.gz;\n buildInputs =\n if gdSupport\n then [\n pkg-config\n (lib.getLib gd)\n (lib.getDev gd)\n ]\n else [];\n}\nWe factorized the import of nixpkgs and mkDerivation, and also added a\nvariant of graphviz with gd support disabled. The result is that both\nhello.nix and graphviz.nix are independent of the repository and\ncustomizable by passing specific inputs.
Now, we can build the package with gd support disabled with the graphvizCore\nattribute:
nix-build -A graphvizCore\n# or we can still build the package that now defaults to gd support\nnix-build -A graphviz\nThis example showed us how to turn expressions into functions. We saw how\nfunctions are passed around and shared between Nix expressions and derivations.
\n", "date_published": "2025-11-22T00:00:00+00:00", "author": { "name": "saylesss87@proton.me (saylesss88)" } }, { "id": "https://saylesss88.github.io/flakes/overlays_4.5.html", "url": "https://saylesss88.github.io/flakes/overlays_4.5.html", "title": "Overlays", "content_html": "Overlays are Nix functions that accept two arguments, final and prev and\nreturn a set of packages. Overlays are similar to packageOverrides as a way to\ncustomize Nixpkgs, packageOverrides acts as an overlay with only the prev\nargument. Therefore, packageOverrides is appropriate for basic use, but\noverlays are more powerful and easier to distribute.
Example:
\n![\"Pokego](\"https://saylesss88.github.io/../images/pokego.png\")
–final: prev: {\n firefox = prev.firefox.overrideAttrs (old: {\n buildInputs = (old.buildInputs or []) ++ [ prev.vlc ];\n env.FIREFOX_DISABLE_GMP_UPDATER = \"1\";\n });\n}\nTo see the original derivation, run nix edit -f \"<nixpkgs>\" firefox.
This modifies Firefox by:
\nAdding vlc to buildInputs, useful if a package requires additional\ndependencies.
Setting an environment variable (FIREFOX_DISABLE_GMP_UPDATER=1) to disable\nautomatic updates of the Gecko Media Plugin.
It is very common to use overlays in Nix to install packages that aren’t\navailable in the standard Nixpkgs repository.
\nOverlays are one of the primary and recommended ways to extend and customize\nyour Nix environment. It’s important to remember that Nix overlays are made to\nallow you to modify or extend the package set provided by Nixpkgs (or other Nix\nsources) without directly altering the original package definitions. This is\ncrucial for maintaining reproducibility and avoiding conflicts. Overlays are\nessentially functions that take the previous package set and allow you to add,\nmodify, or remove packages.
\nflake.nix it may be helpful to\nfirst read This blog\npost first.I’ll show the process of adding the pokego package that is not in Nixpkgs:
flake.nix I have a custom inputs variable within my let block of my\nflake like so just showing the necessary parts for brevity:# flake.nix\n outputs = my-inputs @ {\n self,\n nixpkgs,\n treefmt-nix,\n ...\n }: let\n system = \"x86_64-linux\";\n host = \"magic\";\n userVars = {\n username = \"jr\";\n gitUsername = \"saylesss88\";\n editor = \"hx\";\n term = \"ghostty\";\n keys = \"us\";\n browser = \"firefox\";\n flake = builtins.getEnv \"HOME\" + \"/flake\";\n };\n\n inputs =\n my-inputs\n // {\n pkgs = import inputs.nixpkgs {\n inherit system;\n };\n lib = {\n overlays = import ./lib/overlay.nix;\n nixOsModules = import ./nixos;\n homeModules = import ./home;\n inherit system;\n };\n };\n # ... snip ...\ninputs.lib in My flake.nix. In the above example, you’ll\nnotice a lib attribute defined within the main let block.\nThis might seem a bit unusual at first, as inputs are typically defined at\nthe top level of a flake. However, this structure provides a powerful way to\norganize and reuse common Nix functions and configurations across my flake.
\nBy bundling my custom logic and modules into inputs.lib, I can pass\ninputs (which now includes my custom lib) as a specialArgs to other\nmodules. This provides a clean way for all modules to access these shared\nresources. For example, in configuration.nix, inputs.lib.overlays\ndirectly references my custom overlay set.
My inputs.lib is my own project-specific library, designed to hold\nfunctions and attribute sets relevant to my flake’s custom configurations.\nWhile nixpkgs.lib is globally available, my custom lib contains my\nunique additions.
While defining inputs within the let block to achieve this structure is a\npersonal preference and works well for my setup, the core benefit is the\ncreation of a dedicated, centralized lib attribute that encapsulates my\nflake’s reusable Nix code, leading to a more organized and maintainable\nconfiguration.
overlay.nix I have this helper function and the defined package:# overlay.nix\n_final: prev: let\n # Helper function to import a package\n callPackage = prev.lib.callPackageWith (prev // packages);\n\n # Define all packages\n packages = {\n # Additional packages\n pokego = callPackage ./pac_defs/pokego.nix {};\n };\nin\n packages\n_final: prev:: This is the function definition of the overlay._final: This argument represents the final, merged package set after all\noverlays have been applied. It’s often unused within a single overlay, hence\nthe _ prefix (a Nix convention for unused variables).
prev: This is the crucial argument. It represents the package set before\nthis overlay is applied. This allows you to refer to existing packages and\nfunctions from Nixpkgs.
let ... in packages: This introduces a let expression, which defines\nlocal variables within the scope of this overlay function. The in packages\npart means that the overlay function will ultimately return the packages\nattribute set defined within the let block.
callPackage = prev.lib.callPackageWith (prev // packages): This line\ndefines a helper function called callPackage.
prev.lib.callPackageWith Is a function provided by Nixpkgs’ lib.\ncallPackageWith is like prev.lib.callPackage, but allows the passing of\nadditional arguments that will then be passed to the package definition.
(prev // packages): This is an attribute set merge operation. It takes the\nprev package set (Nixpkgs before this overlay) and merges it with the\npackages attribute set defined later in this overlay.
By using callPackageWith with this merged attribute set, the callPackage\nfunction defined here is set up to correctly import package definitions,\nensuring they have access to both the original Nixpkgs and any other packages\ndefined within this overlay.
packages = { ... };: This defines an attribute set named packages. This\nset will contain all the new or modified packages introduced by this overlay.
pokego = callPackages ./pac_defs/pokego.nix { };: This is the core of how\nthe pokego package is added.
pokego =: This defines a new attribute named pokego within the packages\nattribute set. This name will be used to refer to the pokego package later.
callPackage ./pac_defs/pokego.nix {}: This calls the callPackage helper\nfunction defined earlier.
./pac_defs/pokego.nix: This is the path to another Nix file(pokego.nix)\nthat contains the actual package definition for pokego. This file would define\nhow to fetch, build, and install the pokego software
{}: This is an empty attribute set passed as additional arguments to the\npokego.nix package definition. If pokego.nix expected any specific\nparameters (like versions or dependencies), you would provide them here. Since\nit’s empty, it implies pokego.nix either has no required arguments or uses\ndefault values.
in packages: As mentioned earlier, the overlay function returns the\npackages attribute set. When this overlay is applied, the packages defined\nwithin this packages set (including pokego) will be added to the overall Nix\npackage set.The following is the ./pac_defs/pokego.nix:
# pokego.nix\n{\n lib,\n buildGoModule,\n fetchFromGitHub,\n}:\nbuildGoModule rec {\n pname = \"pokego\";\n version = \"0.3.0\";\n\n src = fetchFromGitHub {\n owner = \"rubiin\";\n repo = \"pokego\";\n rev = \"v${version}\";\n hash = \"sha256-cFpEi8wBdCzAl9dputoCwy8LeGyK3UF2vyylft7/1wY=\";\n };\n\n vendorHash = \"sha256-7SoKHH+tDJKhUQDoVwAzVZXoPuKNJEHDEyQ77BPEDQ0=\";\n\n # Install shell completions\n postInstall = ''\n install -Dm644 completions/pokego.bash \"$out/share/bash-completion/completions/pokego\"\n install -Dm644 completions/pokego.fish \"$out/share/fish/vendor_completions.d/pokego.fish\"\n install -Dm644 completions/pokego.zsh \"$out/share/zsh/site-functions/_pokego\"\n '';\n\n meta = with lib; {\n description = \"Command-line tool that lets you display Pokémon sprites in color directly in your terminal\";\n homepage = \"https://github.com/rubiin/pokego\";\n license = licenses.gpl3Only;\n maintainers = with maintainers; [\n rubiin\n jameskim0987\n vinibispo\n ];\n mainProgram = \"pokego\";\n platforms = platforms.all;\n };\n}\nThere are a few places you could choose to put the following, I choose to use my\nconfiguration.nix because of my setup:
# configuration.nix\nnixpkgs.overlays = [inputs.lib.overlays]\npokego to your environment.systemPackages.# configuration.nix\nenvironment.systemPackages = with pkgs; [\n pokego\n]\npokego with home-manager also:# home.nix\nhome.packages = [\n pkgs.pokego\n]\n{\n inputs = {\n nixpkgs.url = \"https://flakehub.com/NixOS/nixpkgs/*.tar.gz\";\n\n nix.url = \"https://flakehub.com/f/NixOS/nix/2.17.0.tar.gz\";\n };\n\n outputs = { self, nixpkgs, nix }:\n\n let\n system = \"aarch64-darwin\";\n pkgs = import nixpkgs {\n inherit system;\n overlays = [\n nix.overlays.default\n ];\n };\n in\n {\n # `pkgs` is nixpkgs for the system, with nix's overlay applied\n };\n}\nNormally,\npkgs = import nixpkgs { }`` imports Nixpkgs with default settings. However, the example above customizes this import by passing arguments: pkgs\n= import nixpkgs { inherit system; overlays = [\nnix.overlays.default];}. This makes the pkgs variable represent nixpkgs specifically for the aarch64-darwin`\nsystem, with the overlay from the nix flake applied.
Consequently, any packages built using this customized pkgs will now depend\non or use the specific nix version (2.17.0) provided by the nix flake,\ninstead of the version that comes with the fetched nixpkgs. This technique\ncan be useful for ensuring a consistent environment or testing specific\npackage versions.
While overlays are typically used to add or modify packages within a single\nnixpkgs instance, Nix’s lazy evaluation and flake inputs allow for even more\npowerful scenarios. You can have multiple versions of nixpkgs in a single flake,\nand they will only be evaluated when a package from that specific version is\nactually referenced. This complements overlays by giving you fine-grained\ncontrol over which nixpkgs instance an overlay applies to, or which nixpkgs\nversion a specific part of your project depends on.
Consider this example where we import nixpkgs with a specific overlay applied\ndirectly at the import site:
\n{\n inputs = {\n nixpkgs.url = \"[https://flakehub.com/NixOS/nixpkgs/*.tar.gz](https://flakehub.com/NixOS/nixpkgs/*.tar.gz)\"; # This will be the base nixpkgs\n\n 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\n };\n\n outputs = { self, nixpkgs, nix }:\n\n let\n system = \"aarch64-darwin\";\n # Here, we import nixpkgs and apply the 'nix' flake's overlay.\n # This 'pkgs' variable now holds a customized Nix package set.\n # In this 'pkgs' set, the 'nix' package (and anything that depends on it)\n # will be version 2.17.0 as defined by the 'nix' flake's overlay.\n pkgs_with_custom_nix = import nixpkgs {\n inherit system;\n overlays = [\n nix.overlays.default # Apply the overlay from the 'nix' flake here\n ];\n };\n in\n {\n # We can then expose packages or devShells that use this customized `pkgs` set.\n devShells.${system}.default = pkgs_with_custom_nix.mkShell {\n packages = [\n pkgs_with_custom_nix.nix # This 'nix' package is now version 2.17.0 due to the overlay!\n ];\n shellHook = ''\n echo \"Using Nix version: <span class=\"math-inline\">\\(nix \\-\\-version\\)\"\n'';\n};\n# You can also make this customized package set available as a top-level overlay\n# if other parts of your flake or configuration want to use it.\n# overlays.custom-nix-version = final: prev: {\n# inherit (pkgs_with_custom_nix) nix; # Expose the specific nix package from our overlayed pkgs\n# };\n# You can also import multiple versions of nixpkgs and select packages from them:\n# pkgs-2505 = import (inputs.nixpkgs-2505 or nixpkgs) { inherit system; }; # Example, assuming 2505 is an input\n# packages.</span>{system}.my-tool-2505 = pkgs-2505.myTool; # Using a package from a specific stable version\n };\n}\nNormally, pkgs = import nixpkgs { } imports Nixpkgs with default settings.\nHowever, the example above customizes this import by passing arguments:\npkgs = import nixpkgs { inherit system; overlays = [ nix.overlays.default];}.\nThis makes the pkgs_with_custom_nix variable represent Nixpkgs specifically\nfor the aarch64-darwin system, with the overlay from the nix flake applied at\nthe time of import.
Consequently, any packages built using this customized pkgs_with_custom_nix\nwill now depend on or use the specific Nix version (2.17.0) provided by the\nnix flake’s overlay, instead of the version that comes with the base nixpkgs\ninput. This technique is highly useful for ensuring a consistent environment or\ntesting specific package versions without affecting the entire system’s\nnixpkgs set.
NixOS specialisations are a powerful feature that allow you to define\nalternative system configurations variations within a single NixOS setup. Each\nspecialisation can modify or extend the base configuration, and NixOS will\ngenerate separate boot entries for each, letting you choose at boot time (or\nswitch at runtime) which environment to use. This is ideal for testing,\nhardware-specific tweaks, or separating work and personal environments without\nmaintaining multiple configuration files
\nSpecialisations are defined as attributes under the specialisation option in\nyour configuration. Each key (e.g., niri-test) represents a named\nspecialisation, and its configuration attribute contains the NixOS options to\napply on top of the base system
By default, a specialisation inherits the parent configuration and applies its\nchanges on top. You can also set inheritParentConfig = false; to create a\ncompletely separate configuration.
After running nixos-rebuild boot, your bootloader will present extra entries\nfor each specialisation. Selecting one boots into the system with that\nspecialisation’s settings applied
Runtime Switching: You can switch to a specialisation at runtime using\nactivation scripts, e.g.:
\nnixos-rebuild switch --specialisation niri-test\nor
\n/run/current-system/specialisation/niri-test/bin/switch-to-configuration switch\n\n\nNote: Some changes (like kernel switches) require a reboot to take effect
\n
Example: Let’s create a basic specialisation to try out the Niri Window Manager:
\nFirst we have to add the niri-flake as an input to our flake.nix and add the\nmodule to install it:
# flake.nix\ninputs = {\n niri.url = \"github:sodiboo/niri-flake\";\n};\n# configuration.nix\n{ pkgs, inputs, ... }: {\n# ... snip ...\nimports = [\n inputs.niri.nixosModules.niri\n];\n\n# This is the top-level overlay\n nixpkgs.overlays = [inputs.niri.overlays.niri];\n\n# ... snip ...\n\n specialisation = {\n niri-test.configuration = {\n system.nixos.tags = [\"niri\"];\n\n # Add the Niri overlay for this specialisation\n nixpkgs.overlays = [inputs.niri.overlays.niri];\n\n # Enable Niri session\n programs.niri = {\n enable = true;\n package = pkgs.niri-unstable;\n };\n\n # Optionally, add a test user and greetd for login\n users.users.niri = {\n isNormalUser = true;\n extraGroups = [\"networkmanager\" \"video\" \"wheel\"];\n initialPassword = \"test\"; # for testing only!\n createHome = true;\n };\n\n services.greetd = {\n enable = true;\n settings = rec {\n initial_session = {\n command = lib.mkForce \"${pkgs.niri}/bin/niri\";\n user = lib.mkForce \"niri\";\n };\n default_session = initial_session;\n };\n };\n\n environment.etc.\"niri/config.kdl\".text = ''\n binds {\n Mod+T { spawn \"alacritty\"; }\n Mod+D { spawn \"fuzzel\"; }\n Mod+Q { close-window; }\n Mod+Shift+Q { exit; }\n }\n '';\n environment.systemPackages = with pkgs; [\n alacritty\n waybar\n fuzzel\n mako\n firefox\n ];\n\n programs.firefox.enable = true;\n\n services.pipewire = {\n enable = true;\n alsa.enable = true;\n pulse.enable = true;\n # Optionally:\n jack.enable = true;\n };\n\n hardware.alsa.enablePersistence = true;\n\n networking.networkmanager.enable = true;\n };\n };\n}\nI chose to use the nightly version so it was required to add the overlay at the\ntop-level as well as inside the specialisation block.
On my system it sped up build times to first run:
\nsudo nixos-rebuild switch --flake .\n# And Then Run\nsudo nixos-rebuild boot --flake .\nWhat this does:
\nCreates a boot entry called niri-test with the Niri Wayland compositor, a\ntest user, and a greetd login manager.
Installs a set of packages and enables PipeWire with ALSA, PulseAudio, and\nJACK support.
\nProvides a custom Niri configuration file for a few keybinds and enables\nNetworkManager.
\nOnce you have rebooted and selected your specialisation from the boot menu, you\ncan use your system as usual. If you want to add or remove programs, change\nsettings, or update your environment within a specialisation, simply:
\nEdit your configuration: Add or remove packages (e.g., add ghostty to\nenvironment.systemPackages) or change any other options inside the\nrelevant specialisation block in your NixOS configuration.
Apply changes with a rebuild: Run the standard NixOS rebuild command. If you\nare currently running the specialisation you want to update, use:
\nsudo nixos-rebuild switch\nThis will apply your changes to the current specialisation
\nIf you want to build and activate a different specialisation from your current\nsession, use:
\nsudo nixos-rebuild switch --specialisation name\nOr, you can activate a specialisation directly with:
\nsudo /run/current-system/specialisation/<name>/bin/switch-to-configuration switch\nReplace <name> with your specialisation’s name.
Reboot if needed: Most changes apply immediately, but some (like kernel or\ninitrd changes) require a reboot for the specialisation to fully take effect
Tip:
\nEach specialisation can have its own set of installed programs. Only those\nlisted in the environment.systemPackages (or enabled via modules) inside the\nspecialisation block will be available when you boot into that context.
You manage and update your specialisation just like your main NixOS system no\nspecial commands or workflow are required beyond specifying the specialisation\nwhen rebuilding or switching.
\nHardware Profiles: Enable/disable drivers or services for specific\nhardware (e.g., eGPU, WiFi, or SR-IOV setups)
\nDesktop Environments: Quickly switch between different desktop\nenvironments or compositors (e.g., GNOME, Plasma, Niri)
\nTesting: Safely try out unstable packages, new kernels, or experimental\nfeatures without risking your main environment
\nUser Separation: Create profiles for different users, each with their own\nsettings, packages, and auto-login
\nSecure Environments: Combine with encrypted partitions for more secure,\nisolated setups
\nI will just explain the concept here for completeness, if you want to implement\nthis I recommend following:
\nTweag Hard User Separation with NixOS
\nIf you use the same computer in different contexts such as for work and for your\nprivate life you may worry about the risks of mixing sensitive environments. For\nexample, a cryptolocker received through a compromised work email could\npotentially encrypt your personal files, including irreplaceable family photos.
\nA common solution is to install two different operating systems and dual-boot\nbetween them, keeping work and personal data isolated. However, this approach\nmeans you have two systems to maintain, update, and configure, which can be a\nsignificant hassle.
\nNixOS offers a third alternative: With NixOS specialisations, you can manage two\n(or more) securely separated contexts within a single operating system. At boot\ntime, you select which context you want to use work or personal. Each context\ncan have its own encrypted root partition, user accounts, and configuration, but\nboth share the same Nix store for packages. This means:
\nNo duplicated packages: Both contexts use the same system-wide package store,\nsaving space and simplifying updates.
\nSingle system to maintain: You update and manage only one NixOS installation,\nnot two.
\nStrong security boundaries: Each context can have its own encrypted root, so a\ncompromise in one context (such as malware in your work environment) cannot\naccess the data in the other context.
\nFlexible management: You can configure both contexts from either environment,\nmaking administration easier.
\nThis approach combines the security of dual-booting with the convenience and\nefficiency of a single, unified system.
\nHow It Works:
\nEncrypted Partitions: Each context (work and personal) has its own encrypted\nroot partition. The shared /nix/store partition is also encrypted, but can be\nunlocked by either context.
\nSpecialisations at Boot: NixOS generates multiple boot entries, one for each\ncontext. You simply choose your desired environment at boot time.
\nSeparation of Data: Your work and personal home directories, settings, and\ndocuments remain isolated from each other, while still benefiting from shared\nsystem packages.
\nBenefits Over Traditional Dual-Boot
\nOnly one system to update and configure.
\nNo wasted disk space on duplicate packages.
\nSeamless switching between contexts with a reboot.
\nConsistent NixOS tooling and workflows in both environments.
\nWhat You Need
\nA physical or virtual machine supported by NixOS.
\nWillingness to erase the system disk during setup.
\nLVM (Logical Volume Manager) support: This setup requires using LVM for disk\npartitioning and management. LVM allows you to create multiple logical volumes\non a single physical disk, making it possible to securely separate your work\nand personal environments while sharing a common Nix store. You will use LVM\ncommands such as pvcreate, vgcreate, and lvcreate to prepare your disk\nlayout
In summary: With NixOS specialisations and careful disk partitioning, you can\nachieve secure, convenient, and efficient context separation—no need to\ncompromise between security and manageability.
\nOverriding Values: Use lib.mkDefault or lib.mkForce to make options\noverridable or forced in specialisations. I had to do it above because I have\ngreetd setup for my main configuration as well.
Selective Configuration: If you want certain options only in the default\n(non-specialised) system, use:
\nconfig = lib.mkIf (config.specialisation != {}) { ... }\nThis condition checks if you’re in a specialisation.
\nAny settings inside this block will not be inherited by specialisations,\nkeeping them exclusive to the main system.
\nRuntime Limitations: Not all changes (e.g., kernel or initrd) can be fully\napplied at runtime; a reboot is required for those.
Modularity: Specialisations work well with modular NixOS configs keep\nhardware, user, and service configs in separate files for easier management
\nReferences to Official Documentation and Community Resources
\nA key benefit of Nix Flakes is their default enforcement of pure\nevaluation.
\nIn Nix, an impure operation depends on something outside its explicit\ninputs. Examples include:
\nImpurity leads to unpredictable builds that may differ across systems or time.
\nSetup:
\nmkdir hello && cd hello/\nCreate flake.nix (Initial Impure Example):
# flake.nix\n{\n outputs = { self, nixpkgs }: {\n myHello = (import nixpkgs {}).hello;\n };\n}\nbuiltins.currentSystem directly.Impure Build (Fails):
\nnix build .#myHello\nForce Impure Build:
\nnix build .#myHello --impure\nMaking the Flake Pure:
\n# flake.nix\n{\n inputs = {\n nixpkgs.url = \"github:NixOS/nixpkgs\";\n flake-utils.url = \"github:numtide/flake-utils\";\n };\n\n outputs = { self, nixpkgs, flake-utils }:\n flake-utils.lib.eachDefaultSystem (system:\n let\n pkgs = nixpkgs.legacyPackages.${system};\n in {\n packages.myHello = pkgs.hello;\n }\n );\n}\nflake-utils simplifies making flakes system-agnostic and provides the\nsystem attribute.Pure Build (Success):
\nnix build .#myHello\nSetup:
\nmkdir hello2 && cd hello2/\nCreate default.nix (Initial Impure Example):
# default.nix\n{ myHello = (import <nixpkgs> { }).hello; }\nBuild (Impure):
\nnix-build -A myHello\nImpurity Explained:
\nnix repl\nnix-repl> <nixpkgs>\n/nix/var/nix/profiles/per-user/root/channels/nixos\n<nixpkgs> depends on the user’s environment (Nixpkgs channel), making it\nimpure. Even with channels disabled, it relies on a specific Nixpkgs\nversion in the store.Achieving Purity: Using fetchTarball
GitHub allows downloading repository snapshots at specific commits,\ncrucial for reproducibility.
\nGet Nixpkgs Revision from flake.lock (from the Flake example):
# flake.lock\n\"nixpkgs\": {\n \"locked\": {\n \"lastModified\": 1746372124,\n \"narHash\": \"sha256-n7W8Y6bL7mgHYW1vkXKi9zi/sV4UZqcBovICQu0rdNU=\",\n \"owner\": \"NixOS\",\n \"repo\": \"nixpkgs\",\n \"rev\": \"f5cbfa4dbbe026c155cf5a9204f3e9121d3a5fe0\",\n \"type\": \"github\"\n },\nModify default.nix for Purity:
# default.nix\nlet\n nixpkgs = fetchTarball {\n url = \"[https://github.com/NixOS/nixpkgs/archive/f5cbfa4dbbe026c155cf5a9204f3e9121d3a5fe0.tar.gz](https://github.com/NixOS/nixpkgs/archive/f5cbfa4dbbe026c155cf5a9204f3e9121d3a5fe0.tar.gz)\";\n sha256 = \"0000000000000000000000000000000000000000000000000000\"; # Placeholder\n };\nin {\n myHello = (import nixpkgs {}).hello;\n}\n<nixpkgs> with fetchTarball and a specific revision. A\nplaceholder sha256 is used initially.Build (Nix provides the correct sha256):
nix-build -A myHello\nVerification: Both Flake and Traditional Nix builds now produce the same\noutput path.
\nRemaining Impurities in Traditional Nix:
\nimport <nixpkgs> {} can introduce impurity:\noverlays: ~/.config/nixpkgs/overlays (user-specific)config: ~/.config/nixpkgs/config.nix (user-specific)system: builtins.currentSystem (machine-specific)Making Traditional Nix Fully Pure:
\n# default.nix\n{system ? builtins.currentSystem}:\nlet\n nixpkgs = fetchTarball {\n url =\n \"[https://github.com/NixOS/nixpkgs/archive/0243fb86a6f43e506b24b4c0533bd0b0de211c19.tar.gz](https://github.com/NixOS/nixpkgs/archive/0243fb86a6f43e506b24b4c0533bd0b0de211c19.tar.gz)\";\n sha256 = \"1qvdbvdza7hsqhra0yg7xs252pr1q70nyrsdj6570qv66vq0fjnh\";\n };\nin {\n myHello = (import nixpkgs {\n overlays = [];\n config = {};\n inherit system;\n }).hello;\n}\noverlays, config, and make system an\nargument.Building with a Specific System:
\nnix-build -A myHello --argstr system x86_64-linux\nPure Evaluation Mode in Traditional Nix:
\nnix-instantiate --eval --pure-eval --expr 'fetchGit { url = ./.; rev = \"b4fe677e255c6f89c9a6fdd3ddd9319b0982b1ad\"; }'\n--pure-eval.nix-build --pure-eval --expr '(import (fetchGit { url = ./.; rev = \"b4fe677e255c6f89c9a6fdd3ddd9319b0982b1ad\"; }) { system = \"x86_64-linux\"; }).myHello'\nnix flake update\nnix build .#myHello --override-input nixpkgs github:NixOS/nixpkgs/nixos-24.11\nniv)nix-shell -p niv\nniv init\n# default.nix\n{ system ? builtins.currentSystem,\n sources ? import nix/sources.nix,\n nixpkgs ? sources.nixpkgs,\n pkgs ? import nixpkgs {\n overlays = [ ];\n config = { };\n inherit system;\n }, }: {\n myHello = pkgs.hello;\n}\nAnd build it with:
\nnix-build -A myHello\nniv update nixpkgs --branch=nixos-unstable\nnix-build -A myHello\n# flake.nix\n{\n inputs = {\n nixpkgs.url = \"github:NixOS/nixpkgs\";\n flake-utils.url = \"github:numtide/flake-utils\";\n home-manager.url = \"github:nix-community/home-manager\";\n };\n\n outputs = { self, nixpkgs, flake-utils, home-manager, ... }:\n flake-utils.lib.eachDefaultSystem (system:\n let pkgs = nixpkgs.legacyPackages.${system};\n in {\n packages.myHello = pkgs.hello;\n packages.x86_64-linux.homeManagerDocs =\n home-manager.packages.x86_64-linux.docs-html;\n });\n}\nnix flake update\nnix flake show github:nix-community/home-manager\nhome-manager.inputs.follows = \"nixpkgs\";\nnix repl\nnix-repl> s = import ./nix/sources.nix\nnix-repl> s.home-manager\n{ system ? builtins.currentSystem, sources ? import nix/sources.nix\n , nixpkgs ? sources.nixpkgs, pkgs ? import nixpkgs {\n overlays = [ ];\n config = { };\n inherit system;\n }, }: {\n homeManagerDocs = (import sources.home-manager { pkgs = pkgs; }).docs;\n\n myHello = pkgs.hello;\n}\nnix-build -A homeManagerDocs\nIn this chapter, we’ve explored the key differences between traditional Nix and\nNix Flakes, particularly focusing on how each approach handles purity,\ndependency management, and project structure. We’ve seen that while traditional\nNix can achieve purity with careful configuration, Flakes enforce it by default,\noffering a more robust and standardized way to build reproducible environments.\nFlakes also streamline dependency management and provide a more structured\nproject layout compared to the often ad-hoc nature of traditional Nix projects.
\nHowever, regardless of whether you’re working with Flakes or traditional Nix,\nunderstanding how to debug and trace issues within your Nix code is crucial.\nWhen things go wrong, you’ll need tools and techniques to inspect the evaluation\nprocess, identify the source of errors, and understand how your modules and\nderivations are being constructed.
\nIn our next chapter,\nDebugging and Tracing Modules,\nwe will delve into the world of Nix debugging. We’ll explore various techniques\nand tools that can help you understand the evaluation process, inspect the\nvalues of expressions, and trace the execution of your Nix code, enabling you to\neffectively troubleshoot and resolve issues in both Flake-based and traditional\nNix projects.
\n", "date_published": "2025-11-22T00:00:00+00:00", "author": { "name": "saylesss87@proton.me (saylesss88)" } }, { "id": "https://saylesss88.github.io/installation/index.html", "url": "https://saylesss88.github.io/installation/index.html", "title": "My Chapter", "content_html": "This section provides detailed guides for installing NixOS. You’ll choose\nbetween an unencrypted or encrypted base setup. After your core\ninstallation, you can explore adding optional features like sops for encrypted\nsecrets, lanzaboote for Secure Boot, or impermanence for a stateless system.
Best for:
\nUsers who want a straightforward and quick setup.
\nYou can still add Lanzaboote and sops secrets after the install for a more\nsecure system. To get the full benefits of Lanzaboote it is recommended to\nuse full disk encryption.
\nEncrypted Install Guide:\nEncrypted Install
\nImportant Considerations:
\nSecure Boot with Lanzaboote\nFor the full benefit of Secure Boot (with Lanzaboote), it’s highly\nrecommended to have a second stage of protection, such as an encrypted disk.
\nAdding Sops\nYou can easily add sops (for managing encrypted secrets) to your\nconfiguration after the initial encrypted installation and reboot. This\ncan simplify the initial setup process. However, always remember the core\ngoal of using encrypted secrets: never commit unencrypted or even hashed\nsensitive data directly into your Git repository. With modern equipment\nbrute force attacks are a real threat.
Once your base NixOS system is installed, consider these powerful additions:
\nsops-nix: For managing encrypted secrets directly within your NixOS\nconfiguration, ensuring sensitive data is never stored in plain text.
lanzaboote: For enabling Secure Boot, verifying the integrity of your\nboot chain (requires UEFI and custom keys).
impermanence: For setting up a stateless NixOS system, where the root\nfilesystem reverts to a clean state on every reboot.
Figure 1: BTRFS Logo: Image of the BTRFS logo. Sourced from the BTRFS repo BTRFS\nlogo
\nWhy I Chose BTRFS I chose BTRFS because I was already familiar with it from\nusing it with Arch Linux and I found it to be very easy to use. From what I’ve\nread, there are licensing issues between the Linux Kernel and ZFS which means\nthat ZFS is not part of the Linux Kernel; it’s maintained by the OpenZFS project\nand available as a separate kernel module. This can cause issues and make you\nthink more about your filesystem than I personally want to at this point.
\nA Btrfs subvolume is essentially a distinct section within a Btrfs\nfilesystem that maintains its own set of files and directories, along with a\nseparate inode numbering system. Unlike block-level partitions (such as LVM\nlogical volumes), Btrfs subvolumes operate at the file level and are based on\nfile extents.
\nExtents in Btrfs are contiguous blocks of data on disk that store the actual\ncontents of files. When files are created or modified, Btrfs manages these\nextents efficiently, allowing features like deduplication and snapshots.\nMultiple subvolumes can reference the same extents, meaning that identical data\nis not duplicated on disk, which saves space and improves performance.
\nA snapshot in Btrfs is a special kind of subvolume that starts with the same\ncontent as another subvolume at the time the snapshot is taken. Snapshots are\ntypically writable by default, so you can make changes in the snapshot without\naffecting the original subvolume. This is possible because Btrfs tracks changes\nat the extent level, only creating new extents when files are modified (a\ntechnique called copy-on-write).
\nSubvolumes in Btrfs behave much like regular directories from a user’s\nperspective, but they support additional operations such as renaming, moving,\nand nesting (placing subvolumes within other subvolumes). There are no\nrestrictions on nesting, though it can affect how snapshots are created and\nmanaged. Each subvolume is assigned a unique and unchangeable numeric ID\n(subvolid or rootid).
\nYou can access a Btrfs subvolume in two main ways:
\nAs a normal directory within the filesystem.
\nBy mounting it directly as if it were a separate filesystem, using the subvol\nor subvolid mount options. When mounted this way, you only see the contents of\nthat subvolume, similar to how a bind mount works.
\nWhen a new Btrfs filesystem is created, it starts with a “top-level” subvolume\n(with an internal ID of 5). This subvolume is always present and cannot be\ndeleted or replaced, and it is the default mount point unless changed with btrfs\nsubvolume set-default.
\nSubvolumes can also have storage quotas set using Btrfs’s quota groups , but\notherwise, they all draw from the same underlying storage pool. Thanks to\nfeatures like deduplication and snapshots, subvolumes can share data efficiently\nat the extent level.While ZFS is a solid choice and offers some benefits over\nBTRFS, I recommend looking into it before making your own decision.
\nIf you have a ton of RAM you could most likely skip the minimal install and just\nset your system up as needed or just use\ntmpfs as root
\nDisko allows you to declaratively partition and format your disks, and then\nmount them to your system. I recommend checking out the\nREADME\nas it is a disk destroyer if used incorrectly.
\nWe will mainly be following the\ndisko quickstart guide
\nFigure 2: Disko Logo: Image of the logo for Disko, the NixOS declarative\ndisk partitioning tool. Sourced from the\nDisko project disko logo
\ntar -xzf ventoy-1.1.05-linux.tar.gz, and make it\nexecutable with chmod +x Ventoy2Disk.sh, and finally execute it with\nsudo ./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\nby unplugging the USB stick and running lsblk, then plug it in again and run:
lsblk -f\nNAME FSTYPE FSVER LABEL UUID FSAVAIL FSUSE% MOUNTPOINTS\nsda\n└─sda1 vfat FAT32 MYUSB 46E8-9304\nsdb vfat FAT12 F054-697D 1.4M 0% /run/media/jr/F054-697D\nnvme0n1\n├─nvme0n1p1 vfat FAT32 BCD8-8C51 1.8G 12% /boot\nsdb is a USB plugin for a mouse. sda is the USB stick that I want to\ntarget here:sudo ./Ventoy2Disk.sh -i /dev/sda\n# Or to force overwrite an existing Ventoy entry\nsudo ./Ventoy2Disk.sh -I /dev/sda\nsudo systemctl start wpa_supplicant\nwpa_cli\n> add_network\n0\n\n> set_network 0 ssid \"myhomenetwork\"\nOK\n\n> set_network 0 psk \"mypassword\"\nOK\n\n> enable_network 0\nOK\nTo 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\nmethod after starting wpa_supplicant:
# Alternative for quick setup (less interactive, but often faster)\nsudo wpa_passphrase \"myhomenetwork\" \"mypassword\" >> /etc/wpa_supplicant/wpa_supplicant-wlan0.conf\nsudo systemctl restart wpa_supplicant@wlan0.service\nThe output should be something like:
\nNAME MAJ:MIN RM SIZE RO TYPE MOUNTPOINTS\nnvme0n1 259:0 0 1,8T 0 disk\ncd ~\ngit clone https://github.com/saylesss88/my-flake.git\n\n\nMake sure to change line 7 in disk-config.nix to what you got from step 3\ndevice = “/dev/nvme0n1”;
\n
cd /tmp\ncurl https://raw.githubusercontent.com/nix-community/disko/refs/heads/master/example/btrfs-subvolumes.nix -o /tmp/disk-config.nix\nnano /tmp/disk-config.nix\n{\n disko.devices = {\n disk = {\n main = {\n type = \"disk\";\n device = \"/dev/nvme0n1\";\n content = {\n type = \"gpt\";\n partitions = {\n ESP = {\n priority = 1;\n name = \"ESP\";\n start = \"1M\";\n end = \"512M\";\n type = \"EF00\";\n content = {\n type = \"filesystem\";\n format = \"vfat\";\n mountpoint = \"/boot\";\n mountOptions = [\"umask=0077\"];\n };\n };\n root = {\n size = \"100%\";\n content = {\n type = \"btrfs\";\n extraArgs = [\"-f\"]; # Override existing partition\n # Subvolumes must set a mountpoint in order to be mounted,\n # unless their parent is mounted\n subvolumes = {\n # Subvolume name is different from mountpoint\n \"/root\" = {\n mountpoint = \"/\";\n mountOptions = [\"subvol=root\" \"compress=zstd\" \"noatime\"];\n };\n # Subvolume name is the same as the mountpoint\n \"/home\" = {\n mountOptions = [\"subvol=home\" \"compress=zstd\" \"noatime\"];\n mountpoint = \"/home\";\n };\n # Sub(sub)volume doesn't need a mountpoint as its parent is mounted\n \"/home/user\" = {};\n # Parent is not mounted so the mountpoint must be set\n \"/nix\" = {\n mountOptions = [\n \"subvol=nix\"\n \"compress=zstd\"\n \"noatime\"\n ];\n mountpoint = \"/nix\";\n };\n \"/nix/persist\" = {\n mountpoint = \"/nix/persist\";\n mountOptions = [\"subvol=persist\" \"compress=zstd\" \"noatime\"];\n };\n \"/log\" = {\n mountpoint = \"/var/log\";\n mountOptions = [\"subvol=log\" \"compress=zstd\" \"noatime\"];\n };\n \"/lib\" = {\n mountpoint = \"/var/lib\";\n mountOptions = [\"subvol=lib\" \"compress=zstd\" \"noatime\"];\n };\n # This subvolume will be created but not mounted\n \"/test\" = {};\n };\n };\n };\n };\n };\n };\n };\n };\n fileSystems.\"/nix/persist\".neededForBoot = true;\n fileSystems.\"/var/log\".neededForBoot = true;\n fileSystems.\"/var/lib\".neededForBoot = true;\n}\n/tmp on RAM use something like the following. I’ve found that having\ndisko manage swaps causes unnecessary issues. Using zram follows the ephemeral\nroute:{\n lib,\n config,\n ...\n}: let\n cfg = config.custom.zram;\nin {\n options.custom.zram = {\n enable = lib.mkEnableOption \"Enable utils module\";\n };\n\n config = lib.mkIf cfg.enable {\n zramSwap = {\n enable = true;\n # one of \"lzo\", \"lz4\", \"zstd\"\n algorithm = \"zstd\";\n priority = 5;\n memoryPercent = 50;\n };\n };\n}\nAnd in your configuration.nix you would add:
# configuration.nix\ncustom = {\n zram.enable = true;\n};\nAfter adding the above module, you can see it with:
\nswapon --show\nNAME TYPE SIZE USED PRIO\n/dev/zram0 partition 7.5G 0B 5\nsudo nix --experimental-features \"nix-command flakes\" run github:nix-community/disko/latest -- --mode destroy,format,mount /tmp/disk-config.nix\nCheck it with the following:
\nmount | grep /mnt\nThe output for an nvme0n1 disk would be similar to the following:
\n#... snip ...\n/dev/nvme0n1p2 on /mnt type btrfs (rw,noatime,compress=zstd:3,ssd,discard=async,space_cache=v2,subvolid=285,subvol=/root)\n/dev/nvme0n1p2 on /mnt/persist type btrfs (rw,noatime,compress=zstd:3,ssd,discard=async,space_cache=v2,subvolid=261,subvol=/persist)\n/dev/nvme0n1p2 on /mnt/etc type btrfs (rw,noatime,compress=zstd:3,ssd,discard=async,space_cache=v2,subvolid=261,subvol=/persist)\n/dev/nvme0n1p2 on /mnt/nix type btrfs (rw,noatime,compress=zstd:3,ssd,discard=async,space_cache=v2,subvolid=260,subvol=/nix)\n/dev/nvme0n1p2 on /mnt/var/lib type btrfs (rw,noatime,compress=zstd:3,ssd,discard=async,space_cache=v2,subvolid=258,subvol=/lib)\n/dev/nvme0n1p2 on /mnt/var/log type btrfs (rw,noatime,compress=zstd:3,ssd,discard=async,space_cache=v2,subvolid=259,subvol=/log)\n/dev/nvme0n1p2 on /mnt/nix/store type btrfs (ro,noatime,compress=zstd:3,ssd,discard=async,space_cache=v2,subvolid=260,subvol=/nix)\n# ... snip ...\nnixos-generate-config --no-filesystems --root /mnt\nIt may be helpful to add a couple things to your configuration.nix now,\nrebuild and then move on. Such as, your hostname, git, an editor of your choice.\nAfter your additions run sudo nixos-rebuild switch to apply the changes. If\nyou do this, you can skip the nix-shell -p command coming up.
sudo mv /tmp/disk-config.nix /mnt/etc/nixos\ncd ~\nmkdir flake && cd flake\nnix-shell -p git yazi helix\nexport NIX_CONFIG='experimental-features = nix-command flakes'\nexport EDITOR='hx'\nhx flake.nix\n\n\nYou’ll change hostname = nixpkgs.lib.nixosSystem to your chosen hostname,\n(e.g. magic = nixpkgs.lib.nixosSystem). This will be the same as your\nnetworking.hostName = “magic”; in your configuration.nix that we will set up\nshortly.
\n
# flake.nix\n{\n description = \"NixOS configuration\";\n\n inputs = {\n nixpkgs.url = \"github:nixos/nixpkgs/nixos-unstable\";\n disko.url = \"github:nix-community/disko/latest\";\n disko.inputs.nixpkgs.follows = \"nixpkgs\";\n # impermanence.url = \"github:nix-community/impermanence\";\n };\n\n outputs = inputs@{ nixpkgs, ... }: {\n nixosConfigurations = {\n # Change `my-hostname` to match `networking.hostName`\n my-hostname = nixpkgs.lib.nixosSystem {\n system = \"x86_64-linux\";\n modules = [\n ./configuration.nix\n inputs.disko.nixosModules.disko\n # inputs.impermanence.nixosModules.impermanence\n ];\n };\n };\n };\n}\nMove all the files into your flake:
\ncd /mnt/etc/nixos/\nsudo mv disk-config.nix hardware-configuration.nix configuration.nix ~/flake\nBootloader, (e.g., boot.loader.systemd-boot.enable = true;)
\nUser, the example uses username change this to your chosen username. If you\ndon’t set your hostname it will be nixos.
\nNetworking, networking.networkmanager.enable = true;
\nhardware-configuration.nix & disk-config.nix for this setup
initialHashedPassword: Run mkpasswd --method=yescrypt, then enter your\ndesired password. Example output,
mkpasswd --method=yescrypt > /tmp/pass.txt\nnix-shell -p libpwquality\n\npwscore\nvery-secure-password\n100\nread the hashed password into the file with :r /tmp/pass.txt and move it into\nplace.
\n# configuration.nix\n{\n config,\n lib,\n pkgs,\n inputs,\n ...\n}: {\n imports = [\n # Include the results of the hardware scan.\n ./hardware-configuration.nix\n ./disk-config.nix\n ];\n\n networking.hostName = \"my-hostname\"; # This will match the `hostname` of your flake\n\n networking.networkmanager.enable = true;\n\n boot.loader.systemd-boot.enable = true; # (for UEFI systems only)\n # List packages installed in system profile.\n # You can use https://search.nixos.org/ to find more packages (and options).\n environment.systemPackages = with pkgs; [\n vim # Do not forget to add an editor to edit configuration.nix! The Nano editor is also installed by default.\n # wget\n git\n ];\n\n time.timeZone = \"America/New_York\";\n\n# Change `nixos` to your chosen username, change the group to match\n users.users.nixos = {\n isNormalUser = true;\n extraGroups = [ \"wheel\" \"networkmanager\" ]; # Add \"wheel\" for sudo access\n initialHashedPassword = \"COPY_YOUR_MKPASSWD_OUTPUT_HERE\"; # <-- This is where it goes!\n # home = \"/home/nixos\"; # Optional: Disko typically handles home subvolumes\n };\n # Create a matching group\n users.groups.nixos = {};\n\n console.keyMap = \"us\";\n\n nixpkgs.config.allowUnfree = true;\n\n system.stateVersion = \"25.05\";\n}\nShred pass.txt:
\nshred /tmp/pass.txt\nrm /tmp/pass.txt\nsudo mv ~/flake /mnt/etc/nixos/\nsudo nixos-install --flake /mnt/etc/nixos/flake .#hostname\n# if the above command doesn't work try this:\nsudo nixos-install --flake /mnt/etc/nixos/flake#hostname\nYou will be prompted to enter a new password if everything succeeds.
\nIf everything checks out, reboot the system and you should be prompted to enter\nyour user and password to login to a shell to get started.
\nThe flake will be placed at /etc/nixos/flake, I choose to move it to my home\ndirectory. Since the file was first in /etc you’ll need to adjust the\npermissions with something like sudo chown nixos:nixos ~/flake. This is based\noff of the example above where we created both a nixos user and group.
You can check the layout of your btrfs system with:
\nsudo btrfs subvolume list /\nTo continue following along and set up impermanence\nClick Here
\n", "date_published": "2025-11-22T00:00:00+00:00", "author": { "name": "saylesss87@proton.me (saylesss88)" } }, { "id": "https://saylesss88.github.io/installation/enc/enc_install.html", "url": "https://saylesss88.github.io/installation/enc/enc_install.html", "title": "Encrypted Install (BTRFS)", "content_html": "NixOS supports file systems that are encrypted using LUKS (Linux Unified Key\nSetup). This guide walks you through an encrypted NixOS installation using Disko\nfor disk management and Btrfs for subvolumes. It is designed for users who want\nfull disk encryption and a modern filesystem layout. If you prefer an\nunencrypted setup, you can skip the LUKS and encryption steps, but this guide\nfocuses on security and flexibility.
\nIf you choose to set up impermanence, ensure it matches your install. Encrypted\nSetup with Encrypted Impermanence and Unencrypted Setup with Unencrypted\nImpermanence.
\n\n\n❗ NOTE: This is a bit convoluted, there are a few paths you can follow. If\nyou choose to use the starter repo (https://github.com/saylesss88/my-flake)\njust follow the included README and use this for reference.
\n
It’s important to understand what disk encryption protects and what it doesn’t\nprotect so you don’t have any misconceptions about how safe your data is.
\nWhat LUKS Protects:
\nData Confidentiality at Rest: LUKS encrypts entire block devices (such as\ndisk partitions or whole drives), ensuring that all data stored on the\nencrypted device is unreadable without the correct decryption key or\npassphrase. This protects sensitive information from unauthorized access if\nthe device is lost, stolen, or physically accessed by an attacker.
\nPhysical Security: If someone gains physical possession of your device\n(for example, by stealing your laptop or removing a hard drive), LUKS ensures\nthe data remains inaccessible and appears as random, meaningless bytes without\nthe correct credentials.
\nProtection Against Offline Attacks: LUKS defends against attackers who\nattempt to bypass the operating system by booting from another device or\nremoving the drive and mounting it elsewhere. Without the decryption key, the\ndata remains protected.
\nWhat LUKS Does Not Protect:
\nData in Use: Once the system is booted and the encrypted device is\nunlocked, the data becomes accessible to the operating system and any user or\nprocess with the necessary permissions. LUKS does not protect against attacks\non a running system, such as malware, remote exploits, or unauthorized users\nwith access to an unlocked session.
\nFile-Level Access Control: LUKS encrypts entire partitions or disks, not\nindividual files or directories. It does not provide granular file-level\nencryption or access control within the operating system.
\nNetwork Attacks: LUKS only protects data stored on disk. It does not\nencrypt data transmitted over networks or protect against network-based\nattacks.
\nBootloader and EFI Partitions: The initial bootloader or EFI system\npartition cannot be encrypted with LUKS, so some parts of the boot process may\nremain exposed unless additional measures are taken. (i.e., Secure Boot,\nadditional passwords, TPM2)
\nTo Sum it Up: LUKS encryption protects the confidentiality of all data stored on\nan encrypted block device by making it unreadable without the correct passphrase\nor key. This ensures that, if your device is lost or stolen, your data remains\nsecure and inaccessible to unauthorized users. However, LUKS does not protect\ndata once the system is unlocked and running, nor does it provide file-level\nencryption or protect against malware and network attacks. For comprehensive\nsecurity, LUKS should be combined with strong access controls and other security\nbest practices.
\nGet the\nNixos Minimal ISO\nGet it on a usb stick, I use Ventoy with Ventoy2Disk.sh. The following is the\nlink to the\nVentoy TarBall\ndownload, untar it with tar -xzf ventoy-1.1.05-linux.tar.gz, and make it\nexecutable with chmod +x Ventoy2Disk.sh, and finally execute it with\nsudo bash Ventoy2Disk.sh Follow the prompts to finish the install.
Configuring Networking
\nThe minimal installer uses wpa_supplicant instead of NetworkManager. Choose\none of the following methods to enable networking:
sudo systemctl start wpa_supplicant\nwpa_cli\nwpa_cli> add_network\n0\n\n> set_network 0 ssid \"myhomenetwork\"\nOK\n\n> set_network 0 psk \"mypassword\"\nOK\n\n> enable_network 0\nOK\nTo exit type quit, then check your connection with ping google.com.
wpa_passphraseThis method is quicker for known networks and persists the configuration for the\nlive environment.
\nFirst, identify your wireless interface name (e.g., wlan0) using ip a.
sudo systemctl start wpa_supplicant # Ensure wpa_supplicant is running\n# This command generates the config and appends it to a file specific to wlan0\nsudo wpa_passphrase \"myhomenetwork\" \"mypassword\" | sudo tee /etc/wpa_supplicant/wpa_supplicant-wlan0.conf\nsudo systemctl restart wpa_supplicant@wlan0.service\nAfter either method, exit wpa_cli with quit. Then test your connection:
ping 1.1.1.1\nlsblkThe output should be something like:
\nNAME MAJ:MIN RM SIZE RO TYPE MOUNTPOINTS\nnvme0n1 259:0 0 1,8T 0 disk\n\n\n❗ From here, you can either
\n
There is still a starter repo that can save you some typing, make sure to\ncarefully review if you decide to use it:
\nexport NIX_CONFIG='experimental-features = nix-command flakes'\nexport EDITOR='hx' # or 'vi'\nnix-shell -p git yazi helix mkpasswd\ngit config --global user.name \"gitUsername\"\ngit config --global user.email \"gitEmail\"\n# OPTIONAL starter repo containing disk-config set up for impermanence\ngit clone https://github.com/saylesss88/my-flake.git\nI prefer helix here as it’s defaults are great. (i.e., auto closing brackets\nand much more)
If you choose to use the starter repo you won’t need to run the next command as\nit is already populated in the repo and should use the\nStarter Repo README most of the rest\nof the guide is for manual disko without the starter repo.
\nIf you click on the layout you want then click the Raw button near the top,\nthen copy the url and use it in the following command:
cd /tmp\ncurl https://raw.githubusercontent.com/nix-community/disko/refs/heads/master/example/luks-btrfs-subvolumes.nix -o /tmp/disk-config.nix\nThe above curl command is to the luks-btrfs-subvolumes.nix layout.
hx /tmp/disk-config.nix\nMake sure you identify your system disk name with lsblk and change the\ndevice attribute below to match your disk.
lsblk\nnvme0n1 259:0 0 476.9G 0 disk\n├─nvme0n1p1 259:1 0 512M 0 part /boot\n└─nvme0n1p2 259:2 0 476.4G 0 part\nMy disk is nvme0n1, change below to match yours:
{\n disko.devices = {\n disk = {\n nvme0n1 = {\n type = \"disk\";\n # Make sure this is correct with `lsblk`\n device = \"/dev/nvme0n1\";\n content = {\n type = \"gpt\";\n partitions = {\n ESP = {\n label = \"boot\";\n name = \"ESP\";\n size = \"1G\";\n type = \"EF00\";\n content = {\n type = \"filesystem\";\n format = \"vfat\";\n mountpoint = \"/boot\";\n mountOptions = [\n \"defaults\"\n ];\n };\n };\n luks = {\n size = \"100%\";\n label = \"luks\";\n content = {\n type = \"luks\";\n name = \"cryptroot\";\n content = {\n type = \"btrfs\";\n extraArgs = [\"-L\" \"nixos\" \"-f\"];\n subvolumes = {\n \"/root\" = {\n mountpoint = \"/\";\n mountOptions = [\"subvol=root\" \"compress=zstd\" \"noatime\"];\n };\n \"/root-blank\" = {\n mountOptions = [\"subvol=root-blank\" \"nodatacow\" \"noatime\"];\n };\n \"/home\" = {\n mountpoint = \"/home\";\n mountOptions = [\"subvol=home\" \"compress=zstd\" \"noatime\"];\n };\n \"/nix\" = {\n mountpoint = \"/nix\";\n mountOptions = [\"subvol=nix\" \"compress=zstd\" \"noatime\"];\n };\n \"/persist\" = {\n mountpoint = \"/persist\";\n mountOptions = [\"subvol=persist\" \"compress=zstd\" \"noatime\"];\n };\n \"/log\" = {\n mountpoint = \"/var/log\";\n mountOptions = [\"subvol=log\" \"compress=zstd\" \"noatime\"];\n };\n \"/lib\" = {\n mountpoint = \"/var/lib\";\n mountOptions = [\"subvol=lib\" \"compress=zstd\" \"noatime\"];\n };\n \"/persist/swap\" = {\n mountpoint = \"/persist/swap\";\n mountOptions = [\"subvol=swap\" \"noatime\" \"nodatacow\" \"compress=no\"];\n swap.swapfile.size = \"18G\";\n };\n };\n };\n };\n };\n };\n };\n };\n };\n };\n\n fileSystems.\"/persist\".neededForBoot = true;\n fileSystems.\"/var/log\".neededForBoot = true;\n fileSystems.\"/var/lib\".neededForBoot = true;\n}\nI have 16G of RAM so to be safe for hibernation I chose to give it some extra\nspace. The boot partition is 1G, this extra space is for specialisations and\nlanzaboote.
\nor for a swapfile:
\nswapDevices = [\n {\n device = \"/persist/swap/swapfile\";\n size = 18 * 1024; # Size in MB (18GB)\n # or\n # size = 16384; # Size in MB (16G);\n }\n];\nWhile /tmp is handled by tmpfs (as shown the below configuration.nix), you\ncan further enhance memory efficiency with zram for compressed swap, as shown\nbelow.
\n\n\n{\n lib,\n config,\n ...\n}: let\n cfg = config.custom.zram;\nin {\n options.custom.zram = {\n enable = lib.mkEnableOption \"Enable utils module\";\n };\n\n config = lib.mkIf cfg.enable {\n zramSwap = {\n enable = true;\n # one of \"lzo\", \"lz4\", \"zstd\"\n algorithm = \"zstd\";\n priority = 5;\n memoryPercent = 50;\n };\n };\n}\nAnd in your
\nconfiguration.nixyou would add:\n# configuration.nix\ncustom = {\n zram.enable = true;\n};\n
After adding the above module and rebuilding, you can see it with:
\nswapon --show\nNAME TYPE SIZE USED PRIO\n/dev/zram0 partition 7.5G 0B 5\nsudo nix --experimental-features \"nix-command flakes\" run github:nix-community/disko/latest -- --mode destroy,format,mount /tmp/disk-config.nix\nCheck it with the following:
\nmount | grep /mnt\nThe output for an nvme0n1 disk would be similar to the following:
#... snip ...\n/dev/nvme0n1p2 on /mnt type btrfs (rw,noatime,compress=zstd:3,ssd,discard=async,space_cache=v2,subvolid=285,subvol=/root)\n/dev/nvme0n1p2 on /mnt/persist type btrfs (rw,noatime,compress=zstd:3,ssd,discard=async,space_cache=v2,subvolid=261,subvol=/persist)\n/dev/nvme0n1p2 on /mnt/etc type btrfs (rw,noatime,compress=zstd:3,ssd,discard=async,space_cache=v2,subvolid=261,subvol=/persist)\n/dev/nvme0n1p2 on /mnt/nix type btrfs (rw,noatime,compress=zstd:3,ssd,discard=async,space_cache=v2,subvolid=260,subvol=/nix)\n/dev/nvme0n1p2 on /mnt/var/lib type btrfs (rw,noatime,compress=zstd:3,ssd,discard=async,space_cache=v2,subvolid=258,subvol=/lib)\n/dev/nvme0n1p2 on /mnt/var/log type btrfs (rw,noatime,compress=zstd:3,ssd,discard=async,space_cache=v2,subvolid=259,subvol=/log)\n/dev/nvme0n1p2 on /mnt/nix/store type btrfs (ro,noatime,compress=zstd:3,ssd,discard=async,space_cache=v2,subvolid=260,subvol=/nix)\n# ... snip ...\n--no-filesystems because disko\nhandles the fileSystems attribute for us.nixos-generate-config --no-filesystems --root /mnt\nconfiguration.nix and\nhardware-configuration.nix in /mnt/etc/nixos/It may be helpful to add a couple things to your configuration.nix now, while\nit’s in its default location. You can just add what you want and rebuild once\nwith sudo nixos-rebuild switch and move on. (i.e. git, an editor, etc.).
cd # Move to home directory\nmkdir flake\ncd /mnt/etc/nixos/\nsudo mv hardware-configuration.nix configuration.nix ~/flake/\nsudo mv /tmp/disk-config.nix ~/flake/\ncd flake\nhx flake.nix\n\n\nYou’ll change
\nhostName = nixpkgs.lib.nixosSystemto your chosen hostname,\n(e.g.magic = nixpkgs.lib.nixosSystem). This will be the same as your\nnetworking.hostName = \"magic\";in yourconfiguration.nixthat we will set\nup shortly.
# flake.nix\n{\n description = \"NixOS configuration\";\n\n inputs = {\n nixpkgs.url = \"github:nixos/nixpkgs/nixos-unstable\";\n disko.url = \"github:nix-community/disko/latest\";\n disko.inputs.nixpkgs.follows = \"nixpkgs\";\n # impermanence.url = \"github:nix-community/impermanence\";\n };\n\n outputs = inputs@{ nixpkgs, ... }: {\n nixosConfigurations = {\n # Change `hostName` to your chosen host name\n nixos = nixpkgs.lib.nixosSystem {\n system = \"x86_64-linux\";\n modules = [\n ./configuration.nix\n inputs.disko.nixosModules.disko\n # inputs.impermanence.nixosModules.impermanence\n ];\n };\n };\n };\n}\nconfiguration.nix with what is required, the following are required, I\nclone my original flake repo and move the pieces into place but it’s fairly\neasy 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\ndon’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\nstart over completely. A fairly safe way to do this is with vim or hx and\nredirect the hashed pass to a /tmp/pass.txt, you can then read it into your\nusers.nix:
mkpasswd --method=yescrypt > /tmp/pass.txt\n# Enter your chosen password\nAnd then when inside configuration.nix, move to the line where you want the\nhashed password and type :r /tmp/pass.txt to read the hash into your current\nfile.
# configuration.nix\n{\n config,\n lib,\n pkgs,\n inputs,\n ...\n}: {\n imports = [\n # Include the results of the hardware scan.\n ./hardware-configuration.nix\n ./disk-config.nix\n ];\n\n # systemd Stage 1: if enabled, it handles unlocking of LUKS-encrypted volumes during boot.\n boot.initrd.luks.devices = {\n cryptroot = {\n device = \"/dev/disk/by-partlabel/luks\";\n allowDiscards = true;\n };\n };\n\n # This complements using zram, putting /tmp on RAM\n boot = {\n tmp = {\n useTmpfs = true;\n tmpfsSize = \"50%\";\n };\n };\n\n # Enable autoScrub for btrfs\n services.btrfs.autoScrub = {\n enable = true;\n interval = \"weekly\";\n fileSystems = [\"/\"];\n };\n\n\n # Change me!\n networking.hostName = \"nixos\"; # This will match the `hostname` of your flake\n\n networking.networkmanager.enable = true;\n\n boot.loader.systemd-boot.enable = true; # (for UEFI systems only)\n # List packages installed in system profile.\n # You can use https://search.nixos.org/ to find more packages (and options).\n environment.systemPackages = with pkgs; [\n vim # Do not forget to add an editor to edit configuration.nix! The Nano editor is also installed by default.\n # wget\n git\n ];\n\n time.timeZone = \"America/New_York\";\n\n# Change me to your chosen username (i.e. change nixosUser to your username)\n users.users.nixosUser = {\n isNormalUser = true;\n extraGroups = [ \"wheel\" \"networkmanager\" ]; # Add \"wheel\" for sudo access\n initialHashedPassword = \"READ_MKPASSWD_OUTPUT_HERE\"; # <-- This is where it goes!\n # home = \"/home/nixos\"; # Optional: Disko typically handles home subvolumes\n };\n # Change me to match your chosen username\n users.group.nixosUser = {};\n\n console.keyMap = \"us\";\n\n nixpkgs.config.allowUnfree = true;\n\n system.stateVersion = \"25.05\";\n}\nAlthough, just adding the disk-config.nix works for prompting you for your\nencryption passphrase adding the following is a more robust way of ensuring Nix\nis aware of this:
boot.initrd.luks.devices = {\n cryptroot = {\n device = \"/dev/disk/by-partlabel/luks\";\n allowDiscards = true;\n };\n };\n/mnt/etc/nixos and run nixos-install:sudo mv ~/flake /mnt/etc/nixos/\nflake.nix, and configuration.nix. Ensure you changed the username in the\nconfiguration.nix from nixos to your chosen name, this is the name you’ll\nuse to login after you enter your encryption passphrase.The below command uses #nixos because that’s what the defaults are, you’ll\nchange it to your chosen hostname.
sudo nixos-install --flake /mnt/etc/nixos/flake#nixos\nThis is essential if you plan on using impermanence with this encrypted setup.\nWe take a snapshot of /root while it’s a clean slate, right after we run disko\nto format the disk.
To access all of the subvolumes, we have to mount the Btrfs partitions\ntop-level.
\nsudo cryptsetup open /dev/disk/by-partlabel/luks cryptroot\nsubvolid=5):sudo mount -o subvolid=5 /dev/mapper/cryptroot /mnt\nls /mnt\n# you should see something like\nroot home nix persist log lib ...\nroot subvolume:sudo btrfs subvolume snapshot -r /mnt/root /mnt/root-blank\nBefore continuing, make sure your blank snapshot exists. This is crucial for\nimpermanence to work properly.
\nsudo btrfs subvolume list /mnt\nYou should see output containing both root and root-blank subvolumes:
ID 256 gen ... path root\nID 257 gen ... path root-blank\nCheck that the snapshot is read only, this ensures that our snapshot will remain\nthe 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\n# output should be\nro=true\nsudo umount /mnt\nIf everything checks out, reboot the system and you should be prompted to\nenter 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\nchoose to move it to my home directory. Since the file was first in /etc\nyou’ll need to adjust the permissions with something like\nsudo chown -R $USER:$USER ~/flake and then you can work on it without\nprivilege escalation. This requires that you create a group for your user as\ndone in the configuration.nix above.
You can check the layout of your btrfs system with:
\nsudo btrfs subvolume list /\nThe following is a one time operation, we’re just getting it out of the way now.\nThis moves all of the important system state to a persistant location, further\npreparing for impermanence.
\nIt’s essential that you have first run the nixos-install command to populate\nthese directories before copying them over.
sudo mkdir -p /mnt/persist/etc\nsudo mkdir -p /mnt/persist/var/lib\nsudo mkdir -p /mnt/persist/var/log\nsudo mkdir -p /mnt/persist/home\nsudo mkdir -p /mnt/persist/root\nsudo cp -a /mnt/etc/. /mnt/persist/etc/\nsudo cp -a /mnt/var/lib/. /mnt/persist/var/lib\nsudo cp -a /mnt/var/log/. /mnt/persist/var/log\nsudo cp -a /mnt/home/. /mnt/persist/home/\nsudo cp -a /mnt/root/. /mnt/persist/root/\nSince we are in a live environment, after the install and reboot the /mnt\nprefix will be removed.
Now that everything is done, we can safely reboot and ensure that our LUKS\npassword/passphrase is accepted as well as our userlevel password and username.
\nAfter reboot, you can continue to setup\nSops Encrypted Secrets\nand\nLanzaboote Secure Boot
\nTo set up impermanence for this specific layout, follow the link\nEncrypted Impermanence
\nThis allows you to use a USB stick for your keyfile, with a backup in case you\nwant or need it. There is a setting fallbackToPassword that protects you in\ncase something fails with the USB key.
First, I’ll show how to set up a dedicated USB stick for a keyfile. (i.e., one\nthat is only used for this). After that I will show the process of adding the\nkeyfile to a USB stick with existing data on it that you don’t want to lose.
\nGenerate the keyfile
\nsudo dd if=/dev/urandom of=/root/usb-luks.key bs=4096 count=1\nThis is for a dedicated USB stick that we will wipe first then add the key.
\nDisko defaults to LUKS2
\n# cryptsetup works for both LUKS1 and LUKS2 formats but doesn't work for\n# TPM2, FIDO2, and smartcards\nsudo cryptsetup luksAddKey /dev/disk/by-partlabel/luks /root/usb-luks.key\nOR
\n\n\n⚠️ WARNING: Security Implications of TPM2 Auto-Unlock
\n
\n\nEnabling TPM2 auto-unlock fundamentally changes your system’s security model.\nWhile this feature protects against certain forms of malicious software\ninjection by tying the decryption key to the system’s boot state, it\neliminates the need for a user password at boot. This creates a significant\nrisk if your machine is stolen or seized, do not use this feature if the\nphysical security of your machine is a concern. This is still at a stage where\nyou can expect rough edges and workarounds.
\n
\n\n⚠️ WARNING: Do NOT use TPM auto-unlock if your CPU is vulnerable to faulTPM!\nAll AMD Zen2 and Zen3 Processors are known to be affected with AMD Zen1 likely\nalso affected and Zen4 unknown! Misconfigurations are also common, do your own\nresearch!
\n
You can add an additional layer by encrypting user data, such as individual home\nfolders, with a different mechanism, such as fscrypt-experimental or\nsystemd-homed. Or, you can use a TPM pin to benefit from the security\nproperties of the TPM, while avoiding completely unattended unlocking.\n–Arch Wiki
I am reading that fscrypt is no longer experimental.
security.pam.enableFscrypt = true;\nsudo fscrypt setup --all-users\nsudo mv /home/<user> /home/old<user>\nsudo mkdir /home/<user>\nsudo chown <user>:users /home/<user>\nsudo fscrypt encrypt --source pam_passphrase --user <user> --skip-unlock /home/<user>/\n–☝️Discourse
\nIt is fairly complex as to how TPM2 auto-unlock can improve security in some\nways, it has to do with how Linux distributions fail to authenticate the boot\nprocess past the initrd.Even with encryption and Secure Boot enabled, the initrd\nstage often remains unverified, meaning a tampered initrd could be substituted\nwithout detection.
\n\nTPMs protect secrets by releasing them only if the boot process can be\nauthenticated through “measurements.” During boot, each component involved\n(firmware, bootloader, kernel, etc.) is hashed, and these hashes are extended\ninto special TPM registers called Platform Configuration Registers (PCRs). These\nPCRs hold a cumulative, tamper-evident record of the boot process state.
\nIf any part of the boot sequence changes (even slightly), the PCR values will\ndiffer from the expected, causing the TPM to refuse to release the bound secret\n(such as a disk decryption key). This ensures that the system only boots or\nunlocks secrets when its software stack is known and trusted, providing strong\nprotection against tampering or unauthorized modifications. The values aren’t\nonly protected by these PCRs but encrypted with a “seed key” that’s generated on\nthe TPM chip itself, and cannot leave the TPM.
\nCheck TPM support:
\ncat /sys/class/tpm/tpm0/device/description\nTPM 2.0 Device\nCheck for necessary software dependencies:
\nsystemd-analyze has-tpm2\nFind your encrypted partition with lsblk:
lsblk\nFirst, you need to use the systemd-cryptenroll command to add a TPM2 key to\nyour encrypted LUKS partition. This process binds a key slot on your disk to the\nstate 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.\n# It binds the key to PCRs 0,2,7,and 15 ensuring the key is only released if the firmware\n# and Secure Boot state of your system is unchanged.\nsudo systemd-cryptenroll --tpm2-device=auto --tpm2-pcrs=0+2+7+15 /dev/disk/by-partlabel/luks\nThere are quite a few options for the above command, some use the following with\nless pcrs and a wipe feature:
\nsudo systemd-cryptenroll --wipe-slot=tpm2 --tpm2-device=auto --tpm2-pcrs=0+7 /dev/disk/by-partlabel/luks\nUsing less pcrs could prevent breakage but reduces security. Check out the PCR\nDefinitions below and decide if you require additional PCRs or less.
\nwipe-slot tells the system to delete any key associated with the TPM2 chip\nfrom 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\nconfiguration more fragile because any legitimate system update altering any\nmeasured component tied to these PCRs will prevent the TPM from releasing the\nkey and lock you out, unless you re-enroll the key with the updated PCR values.
Authenticated Boot and FDE\nThis article explains the limitations and remedies very well.
\nThat said, I do often see people mention a firmware update breaking their TPM2\nauto-unlock functionality. Keep this in mind and have a backup plan. This is\nalso incompatible with the encrypted impermanence setup shared in this book, the\nboot.initrd.postDeviceCommands conflict.
Change YourUser to your username and ensure that cryptroot is the name of\nyours, 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\n users.users.YourUser.extraGroups = [ \"tss\" ];\n # Enables TPM2 services and tools on your system\n security.tpm2.enable = true;\n # Ensure the necessary kernel modules are in the initrd\n boot.initrd.kernelModules = [\"tpm_tis\"];\n # switches the initrd to a systemd-based environment, required for TPM2\n boot.initrd.systemd.enable = true;\n # ❗ Tell the initrd to use the TPM2 key for the encrypted root\n boot.initrd.luks.devices.cryptroot = {\n device = \"/dev/disk/by-partlabel/luks\";\n # These options tell systemd-cryptsetup to automatically try to unlock the device\n # using the TPM2 key. 'tpm2-measure=yes' ensures the PCRs are verified but only works if you use one disk\n crypttabExtraOpts = [\"tpm2-device=auto\" \"tpm2-measure=yes\"];\n fallbackToPassword = true;\n };\n environment.systemPackages = [ pkgs.tpm2-tss ];\n\n\n❗ NOTE:
\ncryptrootneeds to match what your encrypted partition is named, I\nhave seen quite a few different names here.
If you use this, you can’t also use the USB Keyfile or the included impermanence\nguide.
\nDescription
\n/dev/disk/by-partlabel/luks refers to your encrypted partition by its\npartition label, which is stable and less likely to change than\n/dev/nvme0n1p2
/root/usb-luks.key is the keyfile we generated.
You’ll be prompted to enter your existing LUKS passphrase to authorize adding\nthe new key.
\nNow our LUKS volume will accept both our existing passphrase and the new\nkeyfile (from the USB stick) for unlocking.
\nlsblk\nNAME MAJ:MIN RM SIZE RO TYPE MOUNTPOINTS\nsda 8:0 1 239M 0 disk\nsdb 8:16 1 1.4M 0 disk /run/media/jr/7CD1-149A # Example USB mount\nzram0 253:0 0 7.5G 0 disk [SWAP]\nnvme0n1 259:0 0 476.9G 0 disk\n├─nvme0n1p1 259:1 0 512M 0 part /boot\n└─nvme0n1p2 259:2 0 476.4G 0 part\n └─cryptroot 254:0 0 476.4G 0 crypt /persist # Main Btrfs mount\n # (other subvolumes are within /persist and bind-mounted by impermanence)\n# unplug the device and run lsblk again so your sure\nsudo umount /dev/sda1\n# Overwrite with Zeros (fast, sufficient for most uses)\nsudo dd if=/dev/zero of=/dev/sda bs=4M status=progress\n# Or overwrite with Random Data (More Secure, Slower)\nsudo dd if=/dev/urandom of=/dev/sda bs=4M status=progress\n# Or for the most secure way run multiple passes of\nsudo shred -v -n 3 /dev/sda\nsudo fdisk /dev/sda\nPress o to create a new empty DOS partition table (if you are creating\npartitions on a fresh disk or want to wipe existing partitions and start\nover). Be very careful with this step as it will erase all existing\npartition information on the disk.
Press n to create a new partition.
You will then be prompted for the partition type:
\np 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).
\nThen, you’ll be asked for the first sector (press Enter to accept the default,\nwhich is usually the first available sector after the previous partition or\nthe beginning of the disk).
\nFinally, you’ll be asked for the last sector or size (you can specify a size\nlike +10G for 10 Gigabytes, +512M for 512 Megabytes, or press Enter to use the\nrest of the available space).
\nw 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.\nSometimes this happens automatically, but if you encounter issues, a reboot or a\ncommand like partprobe (if available and needed) can help.
Formats as FAT32:
\nsudo mkfs.vfat /dev/sda1\n# or as ext4\nsudo mkfs.ext4 /dev/sda1\nI chose vfat so I ran sudo mkfs.vfat /dev/sda1. In my case this changed the\ndevice path to /run/media/jr/7CD1-149A so it’s important to find your own UUID\nwith the following command:
sudo blkid /dev/sda1\n/dev/sda1: SEC_TYPE=\"msdos\" UUID=\"B7B4-863B\" BLOCK_SIZE=\"512\" TYPE=\"vfat\" PARTUUID=\"7d1f9d7f-01\"\nAs you can see the above UUID is \"B7B4-863B\"
Remove and re-insert the USB stick, this ensures the system recognizes the new\npartition and filesystem.
\nsudo cp /root/usb-luks.key /run/media/jr/B7B4-863B/\nsync\nNote the output of blkid /dev/sda1 and if you have a backup device list that\nalso:
The following is from the wiki edited for my setup, it was created by Tzanko\nMatev:
\nlet\n PRIMARYUSBID = \"B7B4-863B\";\n BACKUPUSBID = \"Ventoy\";\nin {\n\n boot.initrd.kernelModules = [\n \"uas\"\n \"usbcore\"\n \"usb_storage\"\n \"vfat\"\n \"nls_cp437\"\n \"nls_iso8859_1\"\n ];\n\n boot.initrd.postDeviceCommands = lib.mkBefore ''\n mkdir -p /key\n sleep 2\n mount -n -t vfat -o ro $(findfs UUID=${PRIMARYUSBID}) /key || \\\n mount -n -t vfat -o ro $(findfs UUID=${BACKUPUSBID}) /key || echo \"No USB key found\"\n '';\n\n boot.initrd.luks.devices.cryptroot = {\n device = \"/dev/disk/by-partlabel/luks\";\n keyFile = \"/key/usb-luks.key\";\n fallbackToPassword = true;\n allowDiscards = true;\n preLVM = false; # Crucial!\n };\n}\nIf you have issues or just want to remove the key take note of the path used to\nadd it so you don’t have to enter the whole key:
\nsudo cryptsetup luksRemoveKey /dev/disk/by-partlabel/luks --key-file /root/usb-luks.key\nsudo shred --remove --zero /root/usb-luks.key\nsudo dd if=/dev/urandom of=/root/usb-luks.key bs=4096 count=1\nsudo cryptsetup luksAddKey /dev/disk/by-partlabel/luks /root/usb-luks.key\n(enter your existing passphrase when prompted)
\nPlug in the USB Stick and note its mount point\n(e.g.,/run/media/$USER/YourLabel)
Copy the keyfile:
\nsudo cp /root/usb-luks.key /run/media/$USER/YourLabel/\nsync\nYou run the above as 2 commands, the second being sync.
You can rename it if you wish (e.g., luks.key)
sudo shred --remove --zero /root/usb-luks.key\n/run/media/...) does not happen in initrd, you must manually mount\nthe USB in the initrd using its UUID or label.Find the USB Partition UUID:
\nlsblk -o NAME,UUID\n# or\nblkid /dev/sda1\nSuppose the UUID is B7B4-863B
Add to your configuration.nix:
boot.initrd.kernelModules = [ \"usb_storage\" \"vfat\" \"nls_cp437\" \"nls_iso8859_1\" ];\n\nboot.initrd.postDeviceCommands = lib.mkBefore ''\n mkdir -p /key\n sleep 1\n mount -n -t vfat -o ro $(findfs UUID=B7B4-863B) /key || echo \"USB not found\"\n'';\n\nboot.initrd.luks.devices.cryptroot = {\n device = \"/dev/disk/by-partlabel/luks\";\n keyFile = \"/key/usb-luks.key\"; # or whatever you named it\n fallbackToPassword = true;\n allowDiscards = true;\n};\n\n\n❗ Important Note: This guide details a setup involving encrypted partitions\nand impermanent NixOS. While powerful, such configurations require careful\nattention to detail. Incorrect steps, especially concerning encryption keys or\npersistent data paths, can lead to permanent data loss. Please read all\ninstructions thoroughly before proceeding and consider backing up any critical\ndata beforehand. This has only been tested with the disk layout described in\nEncrypted Setups
\n
As a system operates, it gradually accumulates state on its root partition. This\nstate is stored in various directories such as /etc and /var, capturing all\nthe configuration changes, logs, and other modifications—whether they’re\nwell-documented or the result of ad-hoc adjustments made while setting up and\nrunning services.
Impermanence,in the context of operating systems, refers to a setup where\nthe majority of the system’s root filesystem (/) is reset to a pristine state\non every reboot. This means any changes made to the system (e.g., installing new\npackages, modifying system files outside of configuration management, creating\ntemporary files) are discarded upon shutdown or reboot.
Having an impermanent root and /tmp has some security benefits as well. By\nreducing your persistent footprint you reduce your chance of leaving behind\nsensitive activity or data. Since Nix can boot with only /nix and /boot,\nexperienced users familiar with “stateless” systems can take advantage of this\nsmaller attack surface.
Although this setup does not use /tmp as the root filesystem, the root itself\nis restored to its original state upon each reboot, as it was at installation.\nHowever, by configuring /tmp to reside in RAM, you ensure that temporary files\nincluding sensitive data like passwords are stored only in volatile memory and\nare automatically cleared on shutdown or reboot. This significantly enhances the\nsecurity of temporary data by preventing it from ever being written to disk.
flake.nix. You will change the hostname in the\nflake to match your networking.hostName.# flake.nix\n{\n description = \"NixOS configuration\";\n\n inputs = {\n nixpkgs.url = \"github:nixos/nixpkgs/nixos-unstable\";\n disko.url = \"github:nix-community/disko/latest\";\n disko.inputs.nixpkgs.follows = \"nixpkgs\";\n impermanence.url = \"github:nix-community/impermanence\";\n };\n\n outputs = inputs@{ nixpkgs, ... }: {\n nixosConfigurations = {\n hostname = nixpkgs.lib.nixosSystem {\n system = \"x86_64-linux\";\n modules = [\n ./configuration.nix\n inputs.disko.nixosModules.disko\n inputs.impermanence.nixosModules.impermanence\n ];\n };\n };\n };\n}\nfindmnt:If you followed the\nEncrypted Setups\nguide, your encrypted subvolume should be located at:\n/dev/mapper/cryptroot /mnt
/dev/mapper/cryptroot as configured here in the disk-config.nix:# disk-config2.nix\n# ... snip ...\n luks = {\n size = \"100%\";\n label = \"luks\";\n content = {\n type = \"luks\";\n name = \"cryptroot\";\n content = {\n# ... snip ...\nDouble check that the paths exist:
\ncd /dev/mapper/crypt<TAB> # autocomplete should fill out /dev/mapper/cryptroot\nimpermanence.nix:Now, create a new file named impermanence.nix in your configuration directory\n(i.e. your flake directory). This file will contain all the specific settings\nfor your impermanent setup, including BTRFS subvolume management and persistent\ndata locations. Since this file is right next to your configuration.nix,\nyou’ll just add an imports = [ ./impermanence.nix ] to your\nconfiguration.nix apply it to your configuration.
{\n config,\n lib,\n ...\n}: {\n boot.initrd.postDeviceCommands = lib.mkAfter ''\n echo \"Rollback running\" > /mnt/rollback.log\n mkdir -p /mnt\n mount -t btrfs /dev/mapper/cryptroot /mnt\n\n # Recursively delete all nested subvolumes inside /mnt/root\n btrfs subvolume list -o /mnt/root | cut -f9 -d' ' | while read subvolume; do\n echo \"Deleting /$subvolume subvolume...\" >> /mnt/rollback.log\n btrfs subvolume delete \"/mnt/$subvolume\"\n done\n\n echo \"Deleting /root subvolume...\" >> /mnt/rollback.log\n btrfs subvolume delete /mnt/root\n\n echo \"Restoring blank /root subvolume...\" >> /mnt/rollback.log\n btrfs subvolume snapshot /mnt/root-blank /mnt/root\n\n umount /mnt\n '';\n\n environment.persistence.\"/persist\" = {\n directories = [\n \"/etc\"\n \"/var/spool\"\n \"/srv\"\n \"/etc/NetworkManager/system-connections\"\n \"/var/lib/bluetooth\"\n ];\n files = [\n # \"/etc/machine-id\"\n # Add more files you want to persist\n ];\n };\n\n# optional quality of life setting\n security.sudo.extraConfig = ''\n Defaults lecture = never\n '';\n}\n/mnt/rollback.log: this log will be available during the boot process for\ndebugging if the rollback fails, but won’t persist.With the above impermanence script, the btrfs subvolumes are deleted recursively\nand 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\nthe files to their persistent location and the above setting would work once and\nthen cause a conflict.
# configuration.nix\n boot.initrd.luks.devices = {\n cryptroot = {\n device = \"/dev/disk/by-partlabel/luks\";\n allowDiscards = true;\n preLVM = true;\n };\n };\ninitrd) should handle a\nspecific encrypted disk during the boot process. It helps with timing and is a\nmore robust way of telling Nix that we are using an encrypted disk.The following is optional to enable autoScrub for btrfs, the wiki shows\ninterval = \"monthly\"; FYI.
# configuration.nix\n services.btrfs.autoScrub = {\n enable = true;\n interval = \"weekly\";\n fileSystems = [\"/\"];\n };\nhostname in your configuration.nix matches\nthe hostname in your flake.nix.Once you have completed all the steps and created or modified the necessary\nfiles (flake.nix, impermanence.nix), you need to apply these changes to your\nNixOS system.
flake.nix is\nlocated).cd /path/to/your/flake\nnixos-rebuild switch command. This command\nwill:Evaluate your flake.nix and the modules it imports (including your new\nimpermanence.nix).
Build a new NixOS system closure based on your updated configuration.
\nActivate the new system configuration, making it the current running system.
\nsudo nixos-rebuild switch --flake .#hostname # Replace 'hostname' with your actual system hostname\n/imperm_test to your\nenvironment.persistence.\"/persist\" directories, this file should not survive\na reboot.mkdir /imperm_test\necho \"This should be Gone after Reboot\" | sudo tee /imperm_test/testfile\nls -l /imperm_test/testfile # Verify the file exists\ncat /imperm_test/testfile # Verify content\nsudo reboot\nls -l /imperm_test/testfile\nYou should see an output like ls: cannot access '/imperm_test/testfile': No\nsuch file or directory. This confirms that the /imperm_test directory and its\ncontents were indeed ephemeral and were removed during the reboot process,\nindicating your impermanence setup is working correctly!
Your system should now come up with a fresh root filesystem, and only the data\nspecified in your environment.persistence.\"/persist\" configuration will be\npersistent.
SOPS, short for\nSecretsOPerationS, is an editor of encrypted files that supports\nquite a few BINARY formats and encrypts with AWS KMS, GCP KMS, Azure Key Vault,\nage, and PGP.
\nManaging secrets—like API keys, SSH deploy keys, and password hashes is a\ncritical part of system configuration, but it’s also one of the trickiest to do\nsecurely and reproducibly. Traditionally, secrets might be stored in ad hoc\nlocations, referenced by absolute paths, or managed manually outside of version\ncontrol. This approach makes it hard to share, rebuild, or audit your\nconfiguration, and increases the risk of accidental leaks or inconsistencies\nbetween systems.
\nsops-nix solves these problems by integrating Mozilla SOPS directly into your\nNixOS configuration. Instead of relying on hardcoded file paths or copying\nsecrets around, you declare your secrets in your Nix code, encrypt them with\nstrong keys, and let sops-nix handle decryption and placement at activation\ntime.
Encryption with strong keys, as used by sops-nix, makes brute force attacks\ncomputationally unfeasible with current technology—the time and resources\nrequired to try every possible key would be astronomically high. However, this\nprotection relies on using strong, secret keys and good security practices;\nadvances in technology or poor key management can weaken this defense.
\n\n\n❗ CRITICAL SECURITY NOTE: While the encryption itself is robust, this\nprotection fundamentally relies on using strong, secret keys and\ndiligent security practices. If your PGP passphrase is weak, your Age\nprivate key is easily guessable, or the cleartext secret itself is very short\nand has low entropy (e.g., “12345”, “true”, “admin”), an attacker might be\nable to compromise your secrets regardless of the encryption.
\n
flake.nix:{\n inputs.sops-nix.url = \"github:Mic92/sops-nix\";\n inputs.sops-nix.inputs.nixpkgs.follows = \"nixpkgs\";\n\n outputs = { self, nixpkgs, sops-nix }: {\n # change `yourhostname` to your actual hostname\n nixosConfigurations.yourhostname = nixpkgs.lib.nixosSystem {\n # customize to your system\n system = \"x86_64-linux\";\n modules = [\n ./configuration.nix\n sops-nix.nixosModules.sops\n ];\n };\n };\n}\nsops and age to your environment.systemPackages:environment.systemPackages = [\n pkgs.sops\n pkgs.age\n];\nmkdir -p ~/.config/sops/age\nage-keygen -o ~/.config/sops/age/keys.txt\nTo get the Public Keys Value, run the following command:
\nage-keygen -y ~/.config/sops/age/keys.txt\nage12zlz6lvcdk6eqaewfylg35w0syh58sm7gh53q5vvn7hd7c6nngyseftjxl\nCopy the age value it gives you back.
.sops.yaml in the same directory as your flake.nix:# .sops.yaml\nkeys:\n # Your personal age public key (from age-keygen -y ~/.config/sops/age/keys.txt)\n - &personal_age_key age12zlz6lvcdk6eqaewfylg35w0syh58sm7gh53q5vvn7hd7c6nngyseftjxl\n\n # You can also use PGP keys if you prefer, but age is often simpler\n # - &personal_pgp_key 0xDEADBEEFCAFE0123\n\ncreation_rules:\n # This rule applies to any file named 'secrets.yaml' directly in the 'secrets/' directory\n # or 'secrets/github-deploy-key.yaml' etc.\n - path_regex: \"secrets/.*\\\\.yaml$\"\n key_groups:\n - age:\n - *personal_age_key\n # Add host keys for decryption on the target system\n # sops-nix will automatically pick up the system's SSH host keys\n # as decryption keys if enabled in your NixOS config.\n # So you typically don't list them explicitly here unless you\n # want to restrict it to specific fingerprints, which is rare.\n # This part ensures your *personal* key can decrypt it.\nSave it and move on, this file and sops.nix are safe to version control.
ssh-keygen -t ed25519 -C \"your_email@example.com\"\n# for multiple keys run something like\nssh-keygen -t ed25519 -f ~/nix-book-deploy-key -C \"deploy-key-nix-book-repo\"\nWhile in your flake directory:
\nmkdir secrets\nsops secrets/github-deploy-key.yaml # For your github ssh key\nWhen you call a sops command, it will handle the encryption/decryption\ntransparently and open the cleartext file in an editor.
Editing will happen in the editor that $SOPS_EDITOR or $EDITOR is set to,\nsops 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\n$EDITOR:
Erase the default sops filler and type github_deploy_key_ed25519: |, move\nyour cursor 1 line down and type :r ~/.ssh/id_ed25519 to read the private key\ninto the file and repeat as needed.
github_deploy_key_ed25519: |\n -----BEGIN OPENSSH PRIVATE KEY-----\n ...\n -----END OPENSSH PRIVATE KEY-----\n\ngithub_deploy_key_ed25519_nix-book: |\n -----BEGIN OPENSSH PRIVATE KEY-----\n ...\n -----END OPENSSH PRIVATE KEY-----\nThe -----BEGIN and the rest of the private key must be indented 2 spaces
Ensure sops can decrypt it:
\nsops -d secrets/github-deploy-key.yaml\n\n\n❗ WARNING: Only ever enter your private keys through the
\nsopscommand. If\nyou forget and paste them in without thesopscommand then rungit addat\nany point, your git history will have contained an unencrypted secret which is\na nono. Always use thesopscommand when dealing with files in thesecrets\ndirectory, save the file and inspect that it is encrypted on save. If not\nsomething went wrong with thesopsprocess, do not add it to Git. If you\ndo, you will be required to rewrite your entire history which can be bad if\nyou’re collaborating with others.git-filter-repois one such solution that\nrewrites your history. Just keep this in mind. This happens because Git has a\nprotection that stops you from doing stupid things.
Generate an encrypted password hash with:
\nmkpasswd --method=yescrypt > /tmp/password-hash.txt\n# Enter your chosen password and copy the encrypted hash it gives you back\nsops secrets/password-hash.yaml # For your `hashedPasswordFile`\nThe above command will open your $EDITOR with the file password-hash.yaml,\nadd the following content to it. Replace PasteEncryptedHashHere with the\noutput of the mkpasswd command above:
Delete the default sops filler, type password_hash: and leave your cursor\nafter the : and type :r /tmp/password-hash.txt
password_hash: PasteEncryptedHashHere\nEnsure sops can decrypt it:
\nsops -d secrets/password-hash.yaml\nsops.nix and import it or add this directly to your\nconfiguration.nix:My sops.nix is located at ~/flake/hosts/hostname/sops.nix and the secrets\ndirectory is located at ~/flake/secrets so the path from sops.nix to\nsecrets/pasword-hash.yaml would be ../../secrets/password-hash.yaml
Another step you can take is to copy your key to a persistent location,\npreparing for impermanence:
\nsudo mkdir /persist/sops/age\nsudo cp ~/.config/sops/age/keys.txt /persist/sops/age/keys.txt\nThen you would change the age.keyFile = \"/persist/sops/age/keys.txt\" to match\nthis location below.
# ~/flake/hosts/magic/sops.nix # magic is my hostname\n# hosts/magic/ is also where my configuration.nix is\n{...}: {\n sops = {\n defaultSopsFile = ../../.sops.yaml; # Or the correct path to your .sops.yaml\n # Don't mix sshKeyPaths and keyFile\n age.sshKeyPaths = [];\n age.keyFile = \"/persist/sops/age/keys.txt\";\n\n secrets = {\n \"password_hash\" = {\n sopsFile = ../../secrets/password-hash.yaml; # <-- Points to your password hash file\n owner = \"root\";\n group = \"root\";\n mode = \"0400\";\n neededForUsers = true;\n };\n \"github_deploy_key_ed25519_nix-book\" = {\n sopsFile = ../../secrets/github-deploy-key.yaml;\n key = \"github_deploy_key_ed25519_nix-book\";\n owner = \"root\";\n group = \"root\";\n mode = \"0400\";\n };\n \"github_deploy_key_ed25519\" = {\n sopsFile = ../../secrets/github-deploy-key.yaml;\n key = \"github_deploy_key_ed25519\";\n owner = \"root\";\n group = \"root\";\n mode = \"0400\";\n };\n };\n };\n}\nImport sops.nix into your configuration.nix or equivalent:
# configuration.nix\nimports = [\n ./sops.nix # Assuming sops.nix is in the same directory as configuration.nix, adjust path as needed\n # ... other imports\n];\n\n\n❗ NOTE: You may see in the sops quickstart guide that if you’re using\nimpermanence, the key used for secret decryption (
\nsops.age.keyFile) must be\nin a persistent directory, loaded early enough during the boot process. If you\nare using the btrfs subvolume layout you don’t need to worry about this\nbecause your home will be on its own partition when only the root partition is\nwiped on reboot. AddingneededForUsers = true;tellssops-nixto decrypt\nand make that secret available earlier in the boot process specifically,\nbefore user and group accounts are created.
You typically use age.sshKeyPaths for system-level secrets with a\npersistent SSH host key
For user-level secrets, use age.keyFile pointing to your Age private key,\nstored in a safe persistent location.
For reproducibility, keep your key files in a persistent, predictable path and\ndocument 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\ncomplexity to use one or the other. Although most people may choose one, it’s\nnot bad to use both it just adds complexity.
And finally use the password-hash for your hashedPasswordFile for your user,\nmy user is jr so I added this:
# ... snip ...\n users.users = {\n # ${username} = {\n jr = {\n homeMode = \"755\";\n isNormalUser = true;\n # description = userVars.gitUsername;\n hashedPasswordFile = config.sops.secrets.password_hash.path;\n # ...snip...\nBy integrating SOPS with NixOS through sops-nix, you gain a modern, secure,\nand reproducible way to manage sensitive secrets. Unlike traditional approaches\nwhere secrets are often scattered in ad hoc locations, referenced by absolute\npaths, or managed outside version control, sops-nix keeps your secrets\nencrypted, declarative, and version-control friendly.
📌 How to Use This Guide
\nRead warnings: Advanced hardening can break compatibility or cause data\nloss! Pause and research before enabling anything not listed above unless you\nunderstand the consequences.
\nHardening NixOS:
\n🔷 Start Here:
\nAdditional security/hardening topics
\nThere is a lot covered in this guide which can get overwhelming when trying to\ndecide what is worth implementing. Here, I will list some common recommendations\nthat most users should follow to harden their stance.
\n\n\n“The major problem with current systems is their inability to provide\neffective isolation between various programs running on one machine. E.g. if\nthe user’s Web browser gets compromised (due to a bug exploited by a malicious\nweb site), the OS is usually unable to protect other user’s applications and\ndata from also being compromised.”–Qubes arch-spec
\n
You should always start by conducting a personal threat assesment to identify\npotential threats and vulnerabilities that you need to develop strategies to\ndefend against.
\nThreat modeling in computing involves evaluating the security risks to your\ncomputer or network. It helps uncover possible threats and weaknesses so you can\ncreate plans to safeguard your systems and data effectively. By examining\nvarious attack scenarios, you can anticipate potential cyber threats and better\nprotect your digital resources.
\nIt’s not possible to protect yourself against every attack(er), focus on the\nmost probable threats to your specific situation.
\nBefore diving into advanced or specialized hardening, apply these baseline\nsecurity measures suitable for all NixOS users. These settings help protect your\nsystem with minimal risk of breaking workflows or causing admin headaches.
\nThere is something to be said about the window manager you use. GNOME, KDE\nPlasma, and Sway secure privileged Wayland protocols like screencopy. This means\nthat on environments outside of GNOME, KDE, and Sway, applications can access\nscreen content of the entire desktop. This implicitly includes the content of\nother applications. It’s primarily for this reason that Silverblue, Kinoite, and\nSericea images are recommended. COSMIC has plans to fix this.\n–secureblue Images
\nSecureblue recommends disabling Xwayland and finding alternatives for those apps\nas well as disabling xdg-desktop-portal-wlr, this is because the wlroots\ndesktop portal reintroduces the screencopy vulnerability.
Use Disk Encryption (LUKS) to protect your data at rest.
\nKeep your system up to date (update regularly).
\nUse strong, unique passwords. To generate one from the command-line, there is\npkgs.diceware. Generate a password with: diceware -n 12 -w en_eff, add\nspaces between the words for higher entropy.
Avoid reusing passwords, use a password manager.
\nAvoid storing files directly in the root home folder (i.e., /home/user),\ncreate sub-folders instead.(i.e., Instead of creating ~/notes.txt, create\n~/my-notes/notes.txt or ~/Documents/notes.txt).
If you are able to implement a Mandatory Access Control framework, there are\nmore sub-folders that should be avoided such as ~/Downloads. Another\nreason to use non-default sub-dirs is to avoid typos deleting important\nfiles.
Home-Manager has an option xdg.userDirs.enable
# home.nix or equivalent\n{\n xdg.userDirs.enable = true;\n xdg.userDirs.createDirectories = true;\n # Optionally create non-default sub-dirs\n # xdg.userDirs.documents = \"/home/jr/my-documents\";\n # xdg.userDirs.download = \"/home/jr/my-downloads\";\n}\nThe XDG Base Directory Specification defines a consistent way for apps and\ndesktops to store and find files. It helps prevent “dotfile clutter” by\ndirecting application files into clear, organized locations.
\nOnly enable what you use, and actively disable what’s no longer in use.
\nEnable at least a basic firewall, a more complex firewall example that\nutilizes nftables is shared in the\nHardening Networking Chapter
\nAlthough the firewall is enabled by default on NixOS, let’s be explicit about\nit, add the following to your configuration.nix or equivalent:
# configuration.nix\n# this denies incoming connections but allows outgoing and established connections\nnetworking.firewall.enable = true;\nMany services provide an option to open the required firewall ports\nautomatically. For example:
\nservices.tor.openFirewall = true;\nThis prevents you from having to manually open ports
\nAudit and remove local user accounts that are no longer needed: Regularly\nreview and remove unused or outdated accounts to reduce your system’s attack\nsurface, improve compliance, and ensure only authorized users have access. The\nfollowing setting ensures that user (and group) management is fully declarative:
\n# configuration.nix\n# All users must be declared\nusers.mutableUsers = false;\nWith users.mutableUsers = false;, all non-declaratively managed (imperative)\nuser management including creation, modification, or password changes will fail\nor be reset on rebuild. User and group definitions become entirely controlled by\nyour system configuration for maximum reproducibility and security. If you need\nto add, remove, or modify users, you must do so in your configuration.nix and\nrebuild the system.
Don’t log in as root, it’s unnecessary.
Commands that require root permissions should be run individually using sudo\nin all cases. Avoid logging in as root & using sudo su.
Never run GUI applications as root. If there is a legitimate reason for doing\nthis, use lxsudo instead.
\n\nNOTE: There is mention of making\nuserborn the default for NixOS in the\nfuture. It can be more secure by prohibiting UID/GID re-use and giving\nwarnings about insecure password hashing schemes.
\n
I have personally had nothing but problems with userborn and find the docs\nextremely lacking, you need to read the source code to figure anything out which\nis ridiculous. I don’t personally use this but if you figure it out, more power\nto ya.
To enable userborn, just add the following to your configuration.nix or\nequivalent:
# users.nix\n{pkgs,...}:{\nservices.userborn = {\n enable = true;\n # Only needed if `/etc` is immutable\n # passwordFilesLocation = \"/var/lib/nixos/userborn\"\n};\n users.users = {\n \"newuser\" = {\n homeMode = \"755\";\n uid = 1000;\n isNormalUser = true;\n description = \"New user account\";\n extraGroups = [ \"networkmanager\" \"wheel\" \"libvirtd\" ];\n shell = pkgs.bash;\n ignoreShellProgramCheck = true;\n packages = with pkgs; [];\n };\n };\n }\nWith userborn, you configure your users as you normally would declaratively\nwith NixOS with users.users, change \"newuser\" to your desired username.
Explicitly setting uid = 1000; is a best practice for compatibility and\npredictability.
Only install, enable, and run what is needed: Disable or uninstall\nunnecessary software and services to minimize potential vulnerabilities. Take\nadvantage of NixOS’s easy package management and minimalism to keep your system\nlean and secure.
\nAvoid permanently installing temporary tools: Use tools like nix-shell,\ncomma, devShells and nix-direnv to test or run software temporarily. This\nprevents clutter and reduces potential risks from unused software lingering on\nthe system.
Update regularly: Keep your system and software up to date to receive the\nlatest security patches. Delaying updates leaves known vulnerabilities open to\nexploitation.
\nApply the Principle of Least Privilege: Never run tools or services as root\nunless absolutely necessary. Create dedicated users and groups with the minimum\nrequired permissions to limit potential damage if compromised.
\nUse strong passwords and passphrases: Aim for at least 14–16 characters by\ncombining several unrelated words, symbols, and numbers. For example:\nsunset-CoffeeHorse$guitar!. Strong passphrases are both memorable and secure.
Use a password manager and enable multi-factor authentication (MFA): Manage\nunique, strong passwords effectively with a trusted manager and protect accounts\nwith MFA wherever possible for a second layer of defense.
\nCheck logs regularly: Reviewing your system logs helps you spot unusual\nactivity, errors, or failed login attempts that could indicate a security\nproblem. NixOS uses journald by default, which makes this easy. For example,\nto see the logs for your current boot session:
journalctl -b\n# for the previous session\njournalctl -b -1\nAfter establishing some standard best practices and a hardened base, it’s time\nto dive deeper into system hardening, the process of adding layered safeguards\nthroughout your NixOS setup. This next section guides you through concrete steps\nand options for hardening critical areas of your system: from encryption and\nsecure boot to managing secrets, tightening kernel security, and leveraging\nplatform-specific tools.\nHardening NixOS
\n", "date_published": "2025-11-22T00:00:00+00:00", "author": { "name": "saylesss87@proton.me (saylesss88)" } }, { "id": "https://saylesss88.github.io/installation/enc/lanzaboote.html", "url": "https://saylesss88.github.io/installation/enc/lanzaboote.html", "title": "Lanzaboote", "content_html": "⚠️ Warning: This can easily brick your system ⚠️
\nWe will mainly follow the lanzaboote\nQuick Start Guide
\nFor Windows dual-booters and BitLocker users, you should export your BitLocker\nrecovery keys and confirm that they are correct. Refer to this\nMicrosoft support article
\n\n\n❗ NOTE: There are some serious limitations to this setup when used without\nencryption, I’d say it could stop the average person. But an experienced\nhacker could easily bypass this without encryption if they had access to your\ncomputer. For more protection look into TPM2 Hardware Requirements, and full\ndisk encryption.
\n
I found\nThis Article\nfairly enlightening as far as the state of Authenticated Boot and Disk\nEncryption on Linux.
\n\nLanzaboote only secures the boot chain. The userspace remains unverified (i.e.,\nthe nix store, etc.), to verify userspace you need to implement additional\nintegrity checks. It’s common to rely to disk encryption to prevent tampering\nwith and keep the Nix store safe but it’s not always desirable. (i.e.,\nunattended boot)
\nTo be able to setup Secure Boot on your device, NixOS needs to be installed in\nUEFI mode and systemd-boot must be used as a boot loader. This means if you wish\nto install lanzaboote on a new machine, you need to follow the install\ninstruction for systemd-boot and then switch to lanzaboote after the first boot.
\nCheck these prerequisits with bootctl status, this is an example output:
sudo bootctl status\nSystem:\n Firmware: UEFI 2.70 (Lenovo 0.4720)\n Secure Boot: disabled (disabled)\n TPM2 Support: yes\n Boot into FW: supported\n\nCurrent Boot Loader:\n Product: systemd-boot 251.7\n...\nThe firmware must be UEFI and the current bootloader needs to be\nsystemd-boot. If you check these boxes, you’re good to go.
To provide any security your system needs to defend against an attacker turning\nUEFI Secure Boot off or being able to sign binaries with the keys we are going\nto generate.
\nThe easiest way to achieve this is to:
\nEnable a BIOS password for your system, this will prevent someone from just\nshutting off secure boot.
\nUse full disk encryption.
\nFinding the UEFI System Partition (ESP)
\nThe UEFI boot process revolves around the ESP, the (U)EFI System Partition. This\npartition is conventionally mounted at /boot on NixOS.
Verify this with the command sudo bootctl status. Look for ESP:
Creating Your Keys
\nFirst you’ll need to install sbctl which is available in Nixpkgs:
# configuration.nix or equivalent\nenvironment.systemPackages = [ pkgs.sbctl ];\nCreate the keys:
\n$ sudo sbctl create-keys\n[sudo] password for julian:\nCreated Owner UUID 8ec4b2c3-dc7f-4362-b9a3-0cc17e5a34cd\nCreating secure boot keys...✓\nSecure boot keys created!\nIf you already have keys in /etc/secureboot migrate these to /var/lib/sbctl:
sbctl setup --migrate\nShown all in flake.nix for brevity. Can easily be split up into a boot.nix,\netc:
{\n description = \"A SecureBoot-enabled NixOS configurations\";\n\n inputs = {\n nixpkgs.url = \"github:NixOS/nixpkgs/nixos-unstable\";\n\n lanzaboote = {\n url = \"github:nix-community/lanzaboote/v0.4.2\";\n\n # Optional but recommended to limit the size of your system closure.\n inputs.nixpkgs.follows = \"nixpkgs\";\n };\n };\n\n outputs = { self, nixpkgs, lanzaboote, ...}: {\n nixosConfigurations = {\n yourHost = nixpkgs.lib.nixosSystem {\n system = \"x86_64-linux\";\n\n modules = [\n # This is not a complete NixOS configuration and you need to reference\n # your normal configuration here.\n\n lanzaboote.nixosModules.lanzaboote\n\n ({ pkgs, lib, ... }: {\n\n environment.systemPackages = [\n # For debugging and troubleshooting Secure Boot.\n pkgs.sbctl\n ];\n\n # Lanzaboote currently replaces the systemd-boot module.\n # This setting is usually set to true in configuration.nix\n # generated at installation time. So we force it to false\n # for now.\n boot.loader.systemd-boot.enable = lib.mkForce false;\n\n boot.lanzaboote = {\n enable = true;\n pkiBundle = \"/var/lib/sbctl\";\n };\n })\n ];\n };\n };\n };\n}\nBuild it
\nsudo nixos-rebuild switch --flake /path/to/flake\n$ sudo sbctl verify\nVerifying file database and EFI images in /boot...\n✓ /boot/EFI/BOOT/BOOTX64.EFI is signed\n✓ /boot/EFI/Linux/nixos-generation-355.efi is signed\n✓ /boot/EFI/Linux/nixos-generation-356.efi is signed\n✗ /boot/EFI/nixos/0n01vj3mq06pc31i2yhxndvhv4kwl2vp-linux-6.1.3-bzImage.efi is not signed\n✓ /boot/EFI/systemd/systemd-bootx64.efi is signed\nThis is where things can get tricky because UEFI/BIOS are widely different and\nuse different conventions.
\nYou can see your BIOS from the output of bootctl status:
sudo bootctl status\ndoas (jr@magic) password:\nSystem:\n Firmware: UEFI 2.70 (American Megatrends)\nMy UEFI is an American Megatrends, find yours and look up which key you have to\nhit to enter the BIOS on reboot, mine is the delete key. So I reboot and\nrepeatedly hit delete until it brings up the BIOS settings.
\nThe lanzaboote guide shows a few systems and how to enter setup mode for them.
\nFor a ThinkPad the steps are:
\nSelect the “Security” tab.
\nSelect the “Secure Boot” entry.
\nSet “Secure Boot” to enabled.
\nSelect “Reset to Setup Mode”.
\nFor my system, it would allow me to do the above steps but when I saved and\nexited I got a red screen then blue screen and it said No Valid Keys or\nsomething like that and eventually brought me to the MOK Manager where you can\nmanually register keys, this is NOT what you want to do.
\nEven after this mistake I was able to re-enable secure boot and get back into\nthe system.
\nAfter some tinkering, I found that I was able to enter “custom mode” without\nenabling secure boot, which in turn allowed me to select the “Reset to Setup\nMode”
\nIt asks if you are sure you want to erase all of the variables to enter setup\nmode? Hit “Yes”. Then it asks if you want to exit without saving, we want to\nsave our changes so hit “No” do not exit without saving.
\nAfter this you should see all No Keys entries.
\nFinally, Hit the setting to save and exit, some BIOS list an F4 or F9 keybind\nthat saves and exits.
\n\n\n❗: For my system, choosing “save and reboot” would not work for some reason,\nI had to choose “save and exit”.
\n
After hitting “save and exit”, the system boots into NixOS like normal but you\nare in setup mode if everything worked correctly.
\nOpen a terminal and type:
\nsudo sbctl enroll-keys --microsoft\nEnrolling keys to EFI variables...\nWith vendor keys from microsoft...✓\nEnrolled keys to the EFI variables!\n\n\n⚠️ If you used
\n--microsoftwhile enrolling the keys, you might want to check\nthat the Secure Boot Forbidden Signature Database (dbx) is not empty. A quick\nand dirty way is by checking the file size of\n/sys/firmware/efi/efivars/dbx-\\*. Keeping an up to date dbx reduces Secure\nBoot bypasses, see for example:\nhttps://uefi.org/sites/default/files/resources/dbx_release_info.pdf
I then Rebooted into BIOS and enabled secure boot, saved and exited. This loads\nNixOS as if you just rebooted.
\nAnd finally check the output of sbctl status:
sudo sbctl status\nSystem:\n Firmware: UEFI 2.70 (American Megatrends)\n Firmware Arch: x64\n Secure Boot: enabled (user)\n TPM2 Support: yes\n Measured UKI: yes\n Boot into FW: supported\nWe can see the Secure Boot: enabled (user)
As mentioned earlier, this provides some basic protection that may be good\nenough for your desktop in your bedroom but there are some serious limitations.\nI want to be clear that this may stop an average person but an advanced threat\nactor with resources could still fairly easily get in.
\nSecure Boot (with Lanzaboote or any other tool) on NixOS primarily protects the\nboot chain—the bootloader, kernel, and initrd—by ensuring only signed, trusted\nbinaries are executed at boot. This is a real and valuable security improvement,\nespecially for defending against “evil maid” attacks (where someone with\nphysical access tampers with your bootloader or kernel) and for preventing many\nforms of persistent malware.
\nHere are some of the caveats:
\nUserspace Remains Unverified
\nOnce the kernel and initrd have booted, NixOS (by default) does not\ncryptographically verify the integrity of the rest of userspace (the programs\nand libraries in the Nix store, your configs, etc.).
\nThis means an attacker who can modify userspace (e.g., by gaining root\naccess) can potentially install persistent malware, even if your boot chain\nis protected
\n.
\nKernel Lockdown Is Not Enabled
\nThe Linux kernel’s [lockdown mode]
\nis designed to prevent even root from tampering with the kernel at runtime\n(e.g., by loading unsigned modules, using kexec, or accessing /dev/mem).
\nNixOS does not enable kernel lockdown by default, and enabling it is\nnon-trivial, especially given how the Nix store works (modules and kernels\nare built dynamically and not always signed at install time).
\nWithout lockdown, a root user (or malware with root) can still compromise the\nkernel after boot.
\nStage 2 Verification Is Lacking
\nSome distributions (like Fedora Silverblue or systems using dm-verity)\ncryptographically verify the entire userspace at boot, making it immutable\nand much harder to tamper with. This is not the default on NixOS, though\nthere are experimental or appliance-focused solutions
\n.
\nDisk Encryption Complements Secure Boot
\nFull disk encryption (e.g., LUKS) is strongly recommended alongside Secure\nBoot. Encryption protects your data at rest and ensures that even if someone\nbypasses Secure Boot, they cannot read or modify your files without your\npassphrase
\n![\"server_rack\"](\"https://saylesss88.github.io/images/server_rack.cleaned.png\")
Nixpkgs, the package repository for NixOS, is a powerful resource for building\nand customizing software.
\nWorking with a local copy enhances development, debugging, and contribution\nworkflows.
\nThis post covers setting up a local Nixpkgs repository, searching for\ndependencies, and leveraging its advantages, incorporating tips from the Nix\ncommunity.
\nA local Nixpkgs repository offers significant advantages for Nix developers:
\nLocal searches for packages and dependencies are significantly quicker than\nquerying remote repositories or channels.
\nThis speedup is crucial for efficient debugging and rapid prototyping of Nix\nexpressions.
\nBy pinning your local repository to specific commits or branches (e.g.,\nnixos-unstable), you ensure build reproducibility.
This prevents unexpected issues arising from upstream changes in Nixpkgs.
\nYou can directly test and modify package derivations within your local copy.
\nThis allows for quick fixes to issues like missing dependencies without\nwaiting for upstream updates or releases.
\nDeveloping and testing new packages or patches locally is essential before\nsubmitting them as pull requests to Nixpkgs.
\nA local setup provides an isolated environment for experimentation.
\nWhen working with Nixpkgs locally, the choice between Flake and non-Flake\nsyntax has implications for performance and storage:
\nnix build .#<package>)Treats the current directory as a flake, requiring evaluation of\nflake.nix.
For local Nixpkgs, this evaluates the flake definition in the repository\nroot.
\nPerformance and Storage Overhead: Flakes copy the entire working\ndirectory (including Git history if present) to /nix/store for evaluation.\nThis can be slow and storage-intensive for large repositories like Nixpkgs.
nix-build -f . <package> or nix build -f . <package>)-f . specifies the Nix expression (e.g., default.nix or a specific file)\nin the current directory.
Efficiency: Evaluates the Nix expression directly without copying the\nentire worktree to /nix/store. This is significantly faster and more\nstorage-efficient for local development on large repositories.
It is common to place your local clone in the /src directory:
mkdir src && cd src\n\n\n❗ Warning, A shallow clone (
\n--depth 1) is not recommended for general\ndevelopment or contributing changes back to Nixpkgs via pull requests. It’s\nprimarily suitable for:\n
\n- Quick checks or builds: If you only need to verify a package’s current state\nor build a specific version without needing historical context.
\n- CI/CD environments: Where disk space and clone time are critical, and only\nthe latest commit is needed for automated tests or builds.
\n
With that said, to avoid downloading the entire history, perform a shallow\nclone:
\ngit clone [https://github.com/NixOS/nixpkgs](https://github.com/NixOS/nixpkgs) --depth 1\ncd nixpkgs\nWhile in the nixpkgs directory, you can check the version of a package:
nix-instantiate --eval -A openssl.version\n\"3.4.1\"\nOr to directly edit the file you can use nix edit:
nix edit nixpkgs#openssl\nIt uses the nix registry and openssl.meta.position to locate the file.
man nix3 registry\nThe above command will open the openssl/default.nix in your $EDITOR.
If you want to contribute to Nixpkgs, you need to set up a local version\nfollowing the\nContributing guide
\nYou’ll need to, this is directly from the Contributing.md:
Fork\nthe Nixpkgs repository
\nClone the forked repo\ninto a local nixpkgs directory.
git clone git@github.com:your-user/nixpkgs.git\ngit remote add upstream git@github.com:NixOS/nixpkgs.git\n# Check them out\ngit remove -v\nWhere it is: On the official NixOS servers.
\nRole: The absolute source of truth. Thousands of people are pushing to\nthis daily.
\nWhere it is: On your physical computer.
\nRole: Your working copy. This is the only one you can actually “rebase” or\n“commit” to directly.
\nWhere it is: On your GitHub fork (github.com/your-user/nixpkgs).
\nRole: A personal backup and a place to host your code so you can open Pull\nRequests.
\nIn the nixpkgs ecosystem, the “cleanest” way to work is to never add your\nown commits to your local master.
\nKeep your master as a “pure mirror” of upstream/master.
Whenever you want to fix a package or add something new, create a feature\nbranch:
\ngit checkout -b fix-my-package master\nThis way, syncing is as simple as a reset:
\n# Total reset of your local master to match the official one\ngit fetch upstream\ngit checkout master\ngit reset --hard upstream/master\ngit push origin master --force\nWhen you’re ready to push changes you push to origin/feature-branch, visit\nyour fork on github.com and submit the PR.
Use Git worktrees to manage different branches efficiently:
\ngit fetch --all --prune --depth=1\ngit worktree add -b nixos-unstable nixos-unstable # For just unstable\nExplanation of git worktree: Allows multiple working directories\nattached to the same .git directory, sharing history and objects but with\nseparate checked-out files.
git worktree add: Creates a new working directory for the specified branch\n(nixos-unstable in this case).
icat locally and encounter a missing\ndependency error:nix-build -A icat\n# ... (Error log showing \"fatal error: X11/Xlib.h: No such file or directory\")\nfatal error: X11/Xlib.h: No such file or directory indicates a\nmissing X11 dependency.search.nixos.orgrg (ripgrep)Familiarity with searching the Nixpkgs source code is crucial for finding\ndependencies.
\nNavigate to your local nixpkgs/ directory and use rg:
rg \"x11 =\" pkgs # Case-sensitive search\nOutput:
\npkgs/tools/X11/primus/default.nix\n21: primus = if useNvidia then primusLib_ else primusLib_.override { nvidia_x11 = null; };\n22: primus_i686 = if useNvidia then primusLib_i686_ else primusLib_i686_.override { nvidia_x11 = null; };\n\npkgs/applications/graphics/imv/default.nix\n38: x11 = [ libGLU xorg.libxcb xorg.libX11 ];\nRefining the search (case-insensitive):
\nrg -i \"libx11 =\" pkgs\nOutput:
\n# ... (Output showing \"xorg.libX11\")\nThe key result is xorg.libX11, which is likely the missing dependency.
nix-locatenix-locate (from the nix-index package) allows searching for derivations\non the command line.
\n\nNote: Install
\nnix-indexand runnix-indexto create the initial\nindex.
nix-locate libx11\n# ... (Output showing paths related to libx11)\nCombining online and local search tools (search.nixos.org, rg,\nnix-locate) provides a comprehensive approach to finding dependencies.
Speed: Faster searches and builds compared to remote operations.
\nControl: Full control over the Nixpkgs version.
\nUp-to-Date Information: Repository source often has the latest details.
\nRebasing over Merging: Never merge upstream changes into your local\nbranch. Always rebase your branch onto the upstream (e.g., master or\nnixos-unstable) to avoid accidental large-scale pings in pull requests (Tip\nfrom soulsssx3 on Reddit).
Tip from ElvishJErrico: Avoid using Nixpkgs directly as a flake for\nlocal development due to slow copying to /nix/store and performance issues\nwith garbage collection on large numbers of small files. Use\nnix build -f . <package> instead of nix build .#<package>.
Edge Cases for Flake Syntax: Flake syntax might be necessary in specific\nscenarios, such as NixOS installer tests where copying the Git history should\nbe avoided.
\nBase Changes on nixos-unstable: For better binary cache hits, base your\nchanges on the nixos-unstable branch instead of master. Consider the\nmerge-base for staging branches as well.
Consider jujutsu: Explore jj-vcs, a\nGit-compatible alternative that can offer a more intuitive workflow,\nespecially for large monorepos like Nixpkgs. While it has a learning curve, it\ncan significantly improve parallel work and branch management.
In the Nixpkgs Repository.
\nClick Fork, then Create a new Fork.
\nUncheck the box “Only fork the master branch”, for development we will need\nmore branches.
nixos-XX.YY release branches\navailable on your fork when you later try to create a PR against them, or\nwhen 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\nwill obviously be different.
git clone git@github.com:sayls8/nixpkgs.git\nFigure out the branch that should be used for this change by going through\nthis section
\nWhen in doubt use master, that’s where most changes should go. This can be\nchanged later by\nrebasing
Add Nixpkgs as your upstream:
\ncd nixpkgs\n\ngit remote add upstream https://github.com/NixOS/nixpkgs.git\n# Make sure you have the latest changes from upstream Nixpkgs\ngit fetch upstream\n# Show currently configured remote repository\ngit remote -v\norigin git@github.com:sayls8/nixpkgs.git (fetch)\norigin git@github.com:sayls8/nixpkgs.git (push)\nupstream https://github.com/NixOS/nixpkgs.git (fetch)\nupstream https://github.com/NixOS/nixpkgs.git (push)\nUnderstanding Your Remotes
\nThis output confirms that:
\norigin is your personal fork on GitHub (sayls8/nixpkgs.git). When you\ngit push origin ..., your changes go here.
upstream is the official Nixpkgs repository (NixOS/nixpkgs.git). When you\ngit 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\npush your contributions to your own fork.
\n# Shows a ton of remote branches\ngit branch -r | grep upstream\n# Narrow it down\ngit branch -r | grep upstream | grep nixos-\nNext Steps for Contributing
\nmaster is up to date with upstreamgit checkout master\ngit pull upstream master\ngit push origin master\ngit pull upstream master is equivalent to running git fetch upstream\nfollowed 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.
\nIf targeting another branch, replace master with nixos-24.11 for example.
git checkout master\ngit checkout -b my-feature-branch # name should represent the feature\nNew package: Add to\npkgs/by-name/<first-two-letters>/<package-name>/default.nix.
Example structure:
\n{ lib, stdenv, fetchFromGitHub }: stdenv.mkDerivation {\npname = \"xyz\"; version = \"1.2.3\"; src = fetchFromGitHub { ... }; ... }\nUpdate package: Edit version and sha256 in the package’s default.nix.\nUse nix-prefetch-url to update hashes:
nix-prefetch-url <source-url>\nFix a bug: Modify files in pkgs/, nixos/modules/, or elsewhere.
Test locally:
\nBuild:
\nnix-build -A <package-name>\nTest in a shell:
\nnix-shell -p <package-name>\nFor NixOS modules:
\nnixos-rebuild test\nFollow the Nixpkgs Contributing Guide.
\nCommit with a clear message, make sure to follow\ncommit conventions:
\nCommit Conventions
\nCreate a commit for each logical unit.
\nCheck for unnecessary whitespace with git diff --check before committing.
If you have commits pkg-name: oh, forgot to insert whitespace: squash\ncommits in this case. Use git rebase -i. See\nSquashing Commits\nfor additional information.
For consistency, there should not be a period at the end of the commit\nmessage’s summary line (the first line of the commit message).
\nWhen adding yourself as maintainer in the same pull request, make a separate\ncommit with the message maintainers: add <handle>. Add the commit before\nthose making changes to the package or module. See\nNixpkgs Maintainers\nfor details.
Format the commit messages in the following way:
\n(pkg-name): (from -> to | init at version | refactor | etc)\n\n(Motivation for change. Link to release notes. Additional information.)\na) For example, for the airshipper package:
git add pkgs/by-name/ai/airshipper/\ngit commit -m \"airshipper: init at 0.1.0\"\n\nAdds the airshipper tool for managing game assets.\nUpstream homepage: https://github.com/someuser/airshipper\"\nb) Updating airshipper to a new version
git add pkgs/by-name/ai/airshipper/\ngit commit -m \"airshipper: 0.1.0 -> 0.2.0\n\nUpdated airshipper to version 0.2.0. This release includes:\n- Improved asset fetching logic\n- Bug fixes for network errors\n\nRelease notes: https://github.com/someuser/airshipper/releases/tag/v0.2.0\"\nc) Fixing a bug in airshipper’s package definition
git add pkgs/by-name/ai/airshipper/\ngit commit -m \"airshipper: fix: build with latest glibc\n\nResolved build failures on unstable channel due to changes in glibc.\nPatched source to use updated API calls.\n\"\nExamples:
\nnginx: init at 2.0.1
firefox: 122.0 -> 123.0
vim: fix build with gcc13
Push:
\ngit push origin my-feature-branch\nWhen you push your feature branch, it will output a link that you can follow to\ncomplete the PR on GitHub.
\nIf 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\nGo to https://github.com/sayls8/nixpkgs. (your fork) Click the PR prompt for\nmy-feature-branch. Set the base branch to NixOS/nixpkgs:master (or\nnixos-24.11). Write a PR description: Purpose of the change. Related issues\n(e.g., Fixes #1234). Testing steps (e.g., nix-build -A <package-name>). Submit\nand respond to feedback.
For reviewer feedback or upstream changes:
\nEdit, commit, and push:
\ngit add . git commit -m \"<package-name>: address feedback\" git push origin my-feature-branch\nRebase if needed:
\ngit fetch upstream\ngit rebase upstream/master # or upstream/nixos-24.11\ngit push origin my-feature-branch --force\nAfter PR merge:
\nDelete branch:
\ngit push origin --delete my-feature-branch\nSync master:
\ngit checkout master\ngit pull upstream master\ngit push origin master\nAddressing the Many Branches
\nNo need to manage all branches: The nixos-branches are just metadata from\nupstream. You only check out the one you need (e.g., master or\nnixos-24.11).
Focus on relevant branches: The filter (grep nixos-) shows the key release\nbranches. Ignore -small branches and older releases unless specifically\nrequired. Confirm latest stable: If you’re targeting a stable branch,\nnixos-24.11 is likely the latest (or nixos-25.05 if it’s active). Verify\nvia NixOS status.
This chapter demonstrates the fundamental pattern for creating a package. Every\npackage recipe is a file that declares a function. This function takes the\npackages dependencies as argument.
\nIn this example we’ll make a simple package with coreutils and build it.\nDemonstrating the process of building and testing a local package.
This chapter will assume you have already have a cloned fork of Nixpkgs. I\nchoose to clone mine to the ~/src/ directory.
You can check out the nixpkgs/pkgs/README.md\nHere
The Nixpkgs Contributing Guide can be found\nHere
\ndefault.nixFor this example, we’ll create a package called testPackage and will place it\nin the nixpkgs/pkgs/misc directory.
cd ~/src/nixpkgs/pkgs/misc\nmkdir testPackage && cd testPackage\nhx default.nix\n# default.nix\n{\n runCommand,\n coreutils,\n}:\nrunCommand \"testPackage\" {\n nativeBuildInputs = [\n coreutils\n ];\n} ''\n\n echo 'This is a Test' > $out\n''\nNow we need to add our testPackage to all-packages.nix
cd pkgs/top-level\nhx all-packages.nix\nall-packages.nix is a centralized module that defines all available package\nexpressions.
We’ll add our package in the list alphabetically:
\n# all-packages.nix\n# `/msc` # editor search inside file\n# Scroll down to t's\n# snip ...\ntermusic = callPackage ../applications/autio/termusic { };\n\n# we add our package here\ntestPackage = callPackage ../misc/testPackage { };\n\ntfk8s = callPackage ../applications/misc/tfk8s { };\n# snip ...\n\n\n\n
callPackageis a core utility in Nixpkgs. It takes a Nix expression (like\nourdefault.nixfile, which defines a function) and automatically provides\nthe function with any arguments it declares, by looking them up within the\npkgsset (or the scope wherecallPackageis invoked). This means you only\nneed to list the dependencies your package needs in itsdefault.nixfunction\nsignature, andcallPackagewill “inject” the correct versions of those\npackages. This is what thecallPackageNix Pill demonstrates at a lower\nlevel.
pkgs/by-name/ and other locationsNixpkgs uses different conventions for package placement:
\nOlder categories (e.g., pkgs/misc/, pkgs/applications/): Packages\nwithin these directories typically use default.nix as their definition file\n(e.g., pkgs/misc/testPackage/default.nix). These packages are NOT\nautomatically included in the top-level pkgs set; they must be This\nchapter will assume you have already have a cloned fork of Nixpkgs. explicitly\nadded via a callPackage entry in pkgs/top-level/all-packages.nix. This is\nthe method demonstrated in this chapter for our testPackage.
The new pkgs/by-name/ convention: This is the preferred location for\nnew packages.
Packages here are placed in a directory structure like\npkgs/by-name/<first-two-letters>/<package-name>/.
Crucially, their main definition file is named package.nix (e.g.,\npkgs/by-name/te/testPackage/package.nix).
Packages placed within pkgs/by-name/ are automatically discovered and\nexposed by Nixpkgs’ top-level pkgs set. They do not require a manual\ncallPackage entry in all-packages.nix. This results in a more modular\nand scalable approach, reducing manual maintenance.
\n\n❗ : While this example uses
\npkgs/misc/to demonstrate explicit\ncallPackageusage, when contributing a new package to Nixpkgs, you should\nnearly always place it withinpkgs/by-name/and name its definition file\npackage.nix.
There are some\nLimitations\nto this approach.
\nPreviously, packages were manually added to all-packages.nix. While this is no\nlonger needed in most cases, understanding the old method provides useful\ncontext for troubleshooting legacy configurations or custom integrations.
Move to the root directory of Nixpkgs:
\ncd ~/src/nixpkgs\nTry building it:
\nnix-build -A testPackage\nthis derivation will be built:\nthis derivation will be built:\n /nix/store/yrbjsxmgzkl24n75sqjfxbpv5cs3b9hc-testPackage.drv\nbuilding '/nix/store/yrbjsxmgzkl24n75sqjfxbpv5cs3b9hc-testPackage.drv'...\n/nix/store/3012zlv30vn6ifihr1jxbg5z3ysw0hl3-testPackage\nrunCommand is a simple builder, it takes 3 arguments. The first is the package\nname the second is the derivation attributes, and the third is the script to\nrun.
cat ~/src/nixpkgs/result\n───────┬──────────────────────────────\n │ File: result\n───────┼──────────────────────────────\n 1 │ This is a Test\n───────┴──────────────────────────────\nnix-instantiate --eval -A testPackage.meta.position\n\"/home/jr/src/nixpkgs/pkgs/misc/testPackage/default.nix:6\"\nTools like nix search and the Nixpkgs website use the meta information for\ndocumentation and discoverability. It can also be useful for debugging and helps\nto provide better error messages. The above command shows that the\nmeta.position attribute points to the file and line where the package\ndefinition begins, which is very useful for debugging.
Typically a file will have a meta attribute that looks similar to the\nfollowing:
meta = with lib; {\n homepage = \"https://www.openssl.org/\";\n description = \"A cryptographic library that implements the SSL and TLS protocols\";\n license = licenses.openssl;\n platforms = platforms.all;\n} // extraMeta;\nFor example, the following shows how Nix is able to discover different parts of\nyour configuration:
\nLaunch the nix repl and load your local flake:
cd /src\nnix repl\nnix-repl> :lf nixpkgs\nnix-repl> outputs.legacyPackages.x86_64-linux.openssl.meta.position\n\"/nix/store/syvnmj3hhckkbncm94kfkbl76qsdqqj3-source/pkgs/development/libraries/openssl/default.nix:303\"\nnix-repl> builtins.unsafeGetAttrPos \"description\" outputs.legacyPackages.x86_64-linux.openssl.meta\n{\n column = 9;\n file = \"/nix/store/syvnmj3hhckkbncm94kfkbl76qsdqqj3-source/pkgs/development/libraries/openssl/default.nix\";\n line = 303;\n}\nLets create just the meta.description for demonstration purposes.
Since we don’t have a meta attribute this points to a default value that’s\nincorrect.
Let’s add the meta attribute and try it again:
# default.nix\n{\n runCommand,\n coreutils,\n}:\nrunCommand \"testPackage\" {\n nativeBuildInputs = [\n coreutils\n ];\n\n meta = {\n description = \"test package\";\n};\n} ''\n\n echo 'This is a Test' > $out\n''\nnix-instantiate --eval -A testPackage.meta.position\n\"/home/jr/src/nixpkgs/pkgs/misc/testPackage/default.nix:11\"\nNow it points us to the 11’th line, right where our meta.description is.
Let’s stage our package so nix recognises it:
\ncd ~/nixpkgs\ngit add pkgs/misc/testPackage/\nnix edit .#testPackage\nI 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
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\nbtrfs-progs. In the root directory of our local clone of Nixpkgs\n(i.e.~/src/nixpkgs) we can run the following command to locate btrfs-progs\nwithin Nixpkgs:
fd 'btrfs-progs' .\n./pkgs/by-name/bt/btrfs-progs/\nOpen the package.nix in the above directory and copy the src block within\nthe stdenv.mkDerivation block like so:
# package.nix\n version = \"6.14\";\n\n src = fetchurl {\n url = \"mirror://kernel/linux/kernel/people/kdave/btrfs-progs/btrfs-progs-v${version}.tar.xz\";\n hash = \"sha256-31q4BPyzbikcQq2DYfgBrR4QJBtDvTBP5Qzj355+PaE=\";\n };\nWhen we use the above src block in our overlay we’ll need to add\nsrc = self.fetchurl for our overlay to have access to fetchurl.
We will replace the version with our desired version number. To find another\nversion that actually exists we need to check their github repos\nbtrfs-progs Releases. I can see\nthat the previous version was v6.13, lets try that.
cd ~/src/nixpkgs\nhx overlay.nix\nWe will change the version to 6.13 for demonstration purposes. All that is\nreally required is changing the version and 1 character in the hash which\nwould cause a refetch and recalculation of the hash. We will use an empty string\nto follow convention:
# overlay.nix\nself: super: {\n btrfs-progs = super.btrfs-progs.overrideAttrs (old: rec {\n version = \"6.13\";\n\n # Notice the `self` added here\n src = self.fetchurl {\n url = \"mirror://kernel/linux/kernel/people/kdave/btrfs-progs/btrfs-progs-v${version}.tar.xz\";\n hash = \"\";\n };\n };\n });\n}\nTo build this with the file right from the root of the local Nixpkgs (i.e.\n~/src/nixpkgs) you could run the following. Running the command this way\navoids the impurity of looking it up in the ~/.config directory:
nix-build -A btrfs-progs --arg overlays '[ (import ./overlay.nix) ]'\nThe compiler will give you back the correct hash:
specified: sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=\ngot: sha256-ZbPyERellPgAE7QyYg7sxqfisMBeq5cTb/UGx01z7po=\nReplace the empty hash with the new hash value we just got from the compiler\nso the overlay.nix would look like this:
self: super: {\n btrfs-progs = super.btrfs-progs.overrideAttrs (old: rec {\n version = \"6.13\";\n\n src = self.fetchurl {\n url = \"mirror://kernel/linux/kernel/people/kdave/btrfs-progs/btrfs-progs-v${version}.tar.xz\";\n hash = \"sha256-ZbPyERellPgAE7QyYg7sxqfisMBeq5cTb/UGx01z7po=\";\n };\n });\n}\nTry building it again:
\nnix-build -A btrfs-progs --arg overlays '[ (import ./overlay.nix) ]'\nchecking for references to /build/ in /nix/store/szd6lizahidjniz85a0g1wsrfknirhwb-btrfs-progs-6.13...\ngzipping man pages under /nix/store/szd6lizahidjniz85a0g1wsrfknirhwb-btrfs-progs-6.13/share/man/\npatching script interpreter paths in /nix/store/szd6lizahidjniz85a0g1wsrfknirhwb-btrfs-progs-6.13\n/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\"\nstripping (with command strip and flags -S -p) in /nix/store/szd6lizahidjniz85a0g1wsrfknirhwb-btrfs-progs-6.13/lib /nix/store/szd6lizahidjniz85a0g1wsrfknirhwb-btrfs-progs-6.13/bin\n/nix/store/szd6lizahidjniz85a0g1wsrfknirhwb-btrfs-progs-6.13\nWe can inspect it with the repl:
\ncd ~/src/nixpkgs\nnix repl\nnix-repl> :a import ./. { overlays = [ (import ./overlay.nix) ]; }\nnix-repl> btrfs-progs\n«derivation /nix/store/6yxhj84cwcsnrd87rcxbd6w08l9ikc6p-btrfs-progs-6.13.drv»\nnix-repl> btrfs-progs.drvAttrs.buildInputs\n[\n «derivation /nix/store/yg4llzkcla5rppv8r1iikyamfxg3g4sg-acl-2.3.2.drv»\n «derivation /nix/store/vqczbcwjnid6bs4cv3skl7kyd6kkzcfx-attr-2.5.2.drv»\n «derivation /nix/store/xrvx0azszpdh2x0lnldakqx25vfxab19-e2fsprogs-1.47.2.drv»\n «derivation /nix/store/iil4b8adk615zhp6wmzjx16z1v2f8f4j-util-linux-minimal-2.41.drv»\n «derivation /nix/store/wwld8wp91m26wz69gp8vzh090sh5ygxd-lzo-2.10.drv»\n «derivation /nix/store/w4ncw24gdfkbx9779xpgjli5sagi506m-systemd-minimal-libs-257.5.drv»\n «derivation /nix/store/dmh4lvmq6n8hy56q93kplvnfnlwqzzv5-zlib-1.3.1.drv»\n «derivation /nix/store/h8iwhnr636dwb72qqcyzp111ajjxgzr2-zstd-1.5.7.drv»\n]\nnix-repl> btrfs-progs.drvAttrs.version\n\"6.13\"\nnix-repl> btrfs-progs.drvAttrs.src\n«derivation /nix/store/y5nkz1xczxha4xl93qq3adndyc46dcvf-btrfs-progs-v6.13.tar.xz.drv»\nUsing :a adds the attributes from the resulting set into scope and avoids\nbringing the entire nixpkgs set into scope.
To see whats available, you can for example type btrfs-progs.drvAttrs. then\nhit TAB.
Another way to do this is to move our overlay to the\n~/.config/nixpkgs/overlays directory and rename the file like the following,\nagian this adds an impurity because it relies on your ~/.config directory\nwhich is different from user to user:
mv overlay.nix ~/.config/nixpkgs/overlays/btrfs-progs.nix\ncd ~/src/nixpkgs\nnix-build -A btrfs-progs\nchecking for references to /build/ in /nix/store/szd6lizahidjniz85a0g1wsrfknirhwb-btrfs-progs-6.13...\ngzipping man pages under /nix/store/szd6lizahidjniz85a0g1wsrfknirhwb-btrfs-progs-6.13/share/man/\npatching script interpreter paths in /nix/store/szd6lizahidjniz85a0g1wsrfknirhwb-btrfs-progs-6.13\n/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\"\nstripping (with command strip and flags -S -p) in /nix/store/szd6lizahidjniz85a0g1wsrfknirhwb-btrfs-progs-6.13/lib /nix/store/szd6lizahidjniz85a0g1wsrfknirhwb-btrfs-progs-6.13/bin\n/nix/store/szd6lizahidjniz85a0g1wsrfknirhwb-btrfs-progs-6.13\nIn a flake, overlays are defined in the outputs.overlays attribute set of the\nflake.nix.
They are then applied to nixpkgs inputs using\ninputs.nixpkgs.follows = \"nixpkgs\"; (or similar) and the overlays attribute on\nthe input.
Example of flake usage:
\n# flake.nix\n{\n description = \"My NixOS flake with custom overlays\";\n\n inputs = {\n nixpkgs.url = \"github:NixOS/nixpkgs/nixos-unstable\";\n };\n\n outputs = { self, nixpkgs, ... }: {\n\n overlays.myCustomOverlay = final: prev: {\n btrfs-progs = prev.btrfs-progs.overrideAttrs (old: rec {\n version = \"6.13\";\n src = self.fetchurl {\n url = \"mirror://kernel/linux/kernel/people/kdave/btrfs-progs/btrfs-progs-v${version}.tar.xz\";\n hash = \"sha256-ZbPyERellPgAE7QyYg7sxqfisMBeq5cTb/UGx01z7po=\";\n };\n });\n };\n\n nixosConfigurations.my-system = nixpkgs.lib.nixosSystem {\n system = \"x86_64-linux\";\n modules = [\n # Apply the overlay\n { nixpkgs.overlays = [ self.overlays.myCustomOverlay ]; }\n ./configuration.nix\n ];\n };\n };\n}\nnix flake show\npath:/home/jr/btrfs-progs?lastModified=1749655369&narHash=sha256-ln6dLiqo7TxStQSXgcIwfbdt7STGw4ZHftZRfWpY/JQ%3D\n├───nixosConfigurations\n│ └───my-system: NixOS configuration\n└───overlays\n └───myCustomOverlay: Nixpkgs overlay\nThis chapter covers debugging NixOS modules, focusing on tracing module options\nand evaluating merges.
\n![\"404\"](\"https://saylesss88.github.io/images/coding4.png\")
This post is my notes following Nix Hour 40. If it seems a little chaotic,\ntry watching one. They are hard to follow if you’re not extremely familiar\nwith the concepts.
\nNix Code is particularly hard to debug because of (e.g. lazy evaluation,\ndeclarative nature, layered modules)
\nnix-instantiate.let\n lib = import <nixpkgs/lib>;\nin\nlib.evalModules {\n modules = [\n ({ lib, ... }: {\n options.foo = lib.mkOption {\n # type = lib.types.raw;\n type = lib.types.anything;\n # default = pkgs;\n };\n config.foo = {\n bar = 10;\n list = [1 2 3 ];\n baz = lib.mkDefault \"baz\";\n };\n })\n {\n foo.baz = \"bar\";\n }\n ];\n}\nIn the above code, adding lib to the function arguments isn’t required but\nif you were to move the module to another file it would fail without it\nbecause lib comes from outside of it. So it’s good practice to refer to\nlib in the modules themselves.
You should always assign a type to your options, if you don’t know which\ntype to use you could use raw. raw is a type that doesn’t do any\nprocessing. So if you were to assign the entire packages set to the option\ne.g. default = pkgs; it wouldn’t recurseinto all the packages and try to\nevaluate them. There is also anything, that is useful if you do want to\nrecurse into the values.
The following is an example of how you would run this inside vim/neovim, the\nrest of the examples will be from the command line:
\n:!nix-instantiate --eval -A config.foo --strict\nOutput:
\n{ bar = 10; baz = \"bar\"; list = [ 1 2 3 ]; }\nTo show the difference you could uncomment the raw type and comment the\nanything type and run the above command again you’ll see that you get an\nerror:
error: The option 'foo' is defined multiple times while it's expected to be\nunique\nTo execute this command on the command line:
\nnix-instantiate --eval --strict -A config.foo\nIt will show you the start of a trace. To get the full trace add:
\nnix-instantiate --eval --strict -A config.foo --show-trace\nIn the previous example, we looked at a simplified module. Now, let’s examine a\nmore realistic scenario involving a basic NixOS configuration file\n(configuration.nix).
This example will demonstrate how to use nix-instantiate to evaluate an entire\nsystem configuration and how --show-trace helps in diagnosing errors within\nthis context.
Consider the following configuration.nix file:
# configuration.nix\n{ lib, ... }: {\n boot.loader.grub.device = \"nodev\";\n fileSystems.\"/\".device = \"/devst\";\n system.stateVersion = \"24.11\";\n}\nnix-instantiate and point it to the\n<nixpkgs/nixos> entrypoint, providing our configuration.nix file as an\nargument. The -A system flag selects the top-level system attribute, which\nrepresents the instantiated system configuration.Run it in with:
\nnix-instantiate '<nixpkgs/nixos>' --arg configuration ./configuration.nix -A system\nOutput:
\n/nix/store/kfcwvvpdbsb3xcks1s76id16i1mc3l5k-nixos-system-nixos-25.05pre-git.drv\nOk, we can see that this successfully instantiates. Let’s introduce an error\nto trace:
\n{ lib, ... }: {\n boot.loader.grub.device = \"nodev\";\n fileSystems.\"/\".device = \"/devst\";\n system.stateVersion = builtins.genList \"24.11\" null;\n}\nOutput:
\n(stack trace truncated; use '--show-trace' to show the full, detailed trace)\nerror: expected an integer but found null: null\nRerun the command with --show-trace appended:
Or on the command line
\nnix-instantiate '<nixpkgs/nixos>' --arg configuration ./configuration.nix -A system --show-trace\nat /nix/store/ccfwxygjrarahgfv5865x2f828sjr5h0- source/lib/attrsets.nix:1529:14:)To show your own error message you could do something like this:
\n{lib, ...}: {\n boot.loader.grub.device = \"nodev\";\n fileSystems.\"/\".device = \"/devst\";\n system.stateVersion = builtins.addErrorContext \"AAAAAAAAAAAAAAAAA\" (builtins.genList \"24.11\" null);\n}\nRun it:
\nnix-instantiate '<nixpkgs/nixos>' --arg configuration ./configuration.nix -A system --show-trace`\nOutput:
\n … while evaluating the attribute 'value'\n at /nix/store/ccfwxygjrarahgfv5865x2f828sjr5h0-source/lib/modules.nix:770:21:\n 769| inherit (module) file;\n 770| inherit value;\n | ^\n 771| }) module.config\n\n … AAAAAAAAAAAAAAAAA\n\n … while calling the 'genList' builtin\n at /home/jr/tests/configuration.nix:4:71:\n 3| fileSystems.\"/\".device = \"/devst\";\n 4| system.stateVersion = builtins.addErrorContext \"AAAAAAAAAAAAAAAAA\"\n (builtins.genList \"24.11\" null);\n | ^\n 5| }\n\n … while evaluating the second argument passed to builtins.genList\n\n error: expected an integer but found null: null\nLet’s consider another example, this time demonstrating the definition of\nconfiguration options using lib.mkOption within a module structure.
# default.nix\nlet\n lib = import <nixpkgs/lib>;\nin\nlib.evalModules {\n modules = [\n ({ lib, ... }: {\n options.ints = lib.mkOption {\n type = lib.types.attrsOf lib.types.int;\n };\n options.strings = lib.mkOption {\n type = lib.types.string;\n # type = lib.types.attrsOf lib.types.string;\n default = \"foo\";\n };\n })\n ];\n}\nInstantiate this with:
\nnix-instantiate --eval --strict -A config.strings\nOutput:
\nevaluation warning: The type `types.string` is deprecated.\nSee https://github.com/NixOS/nixpkgs/pull/66346 for better alternative types.\n\"foo\"\nlib.attrsOfBelow is an interesting way to provide nixpkgs run it on the command line:
\nexport NIX_PATH=nixpkgs=channel:nixpkgs-unstable\necho $NIX_PATH\nOutput:
\nnixpkgs=channel:nixpkgs-unstable\nThe next two commands are to check that after using the above way to provide\nnixpkgs-unstable that they both point to the same store path, the following\ncommand will fetch nixpkgs from the channel above:
nix-instantiate --find-file nixpkgs\nOutput 1️⃣
\n/nix/store/ydrgwsibghsyx884qz97zbs1xs93yk11-source\nnix-instantiate --eval channel:nixpkgs-unstable -A path\nOutput: 2️⃣
\n/nix/store/ydrgwsibghsyx884qz97zbs1xs93yk11-source\nIn our previous example, we encountered a deprecation warning for\nlib.types.string. This next example delves deeper into why that type was\ndeprecated and demonstrates the consequences of its behavior, along with the\nrecommended fix.
# default.nix\nlet\n lib = import <nixpkgs/lib>;\nin\n lib.evalModules {\n modules = [\n ({lib, ...}: {\n options.ints = lib.mkOption {\n type = lib.types.attrsOf lib.types.int;\n };\n options.strings = lib.mkOption {\n # type = lib.types.string;\n type = lib.types.attrsOf lib.types.string;\n default = {\n x = \"foo\";\n };\n };\n config = {\n strings = lib.mkOptionDefault {\n x = \"bar\";\n };\n };\n })\n ];\n }\nEvaluate it with:
\nnix-instantiate --eval --strict -A config.strings\ntypes.string depricated because it silently concatenates strings
The above command has two options with the same priority level and evaluates\nto { x = \"foobar\"; }
Output:
\nevaluation warning: The type `types.string` is deprecated. See https://github.\ncom/NixOS/nixpkgs/pull/66346 for better alternative types.\n{ x = \"foobar\"; }\ntypes.str was the replacement for the depricated types.string:# default.nix\nlet\n lib = import <nixpkgs/lib>;\nin\n lib.evalModules {\n modules = [\n ({lib, ...}: {\n options.ints = lib.mkOption {\n type = lib.types.attrsOf lib.types.int;\n };\n options.strings = lib.mkOption {\n # type = lib.types.string;\n type = lib.types.attrsOf lib.types.str;\n # Sets the value with a lower priority: lib.mkOptionDefault\n default = {\n x = \"foo\";\n };\n };\n config = {\n strings = lib.mkOptionDefault {\n x = \"bar\";\n };\n };\n })\n ];\n }\nOutput:
\nerror:\n… while evaluating the attribute 'x'\n\n… while evaluating the attribute 'value'\n at /nix/store/ydrgwsibghsyx884qz97zbs1xs93yk11-source/lib/modules.nix:1148:41:\n 1147|\n 1148| optionalValue = if isDefined then { value = mergedValue; } else { };\n | ^\n 1149| };\n\n… while calling the 'foldl'' builtin\n at /nix/store/ydrgwsibghsyx884qz97zbs1xs93yk11-source/lib/options.nix:508:8:\n 507| else\n 508| (foldl' (\n | ^\n 509| first: def:\n\n(stack trace truncated; use '--show-trace' to show the full, detailed trace)\n\nerror: The option `strings.x' has conflicting definition values:\n- In `<unknown-file>': \"foo\"\n- In `<unknown-file>': \"bar\"\nUse `lib.mkForce value` or `lib.mkDefault value` to change the priority on any of these definitions.\n\nshell returned 1\nSo types in the module system aren’t just types in the conventional sense but\nthey also specify the emerging behavior of these values.
\nIf we switch the type in the above example to types.lines you get this\nreturned, { x = \"foo\\nbar\"; }
mkOptionDefault isn’t typically something you should generally use, instead\noptions have a default setting
If you want to make sure that you set a default but if the user specifies it,\nit shouldn’t get overridden. You should not set it in the following:
\noptions.strings = lib.mkOption {\n type = lib.types.attrsOf lib.types.lines;\n default = {\n x = \"foo\";\n };\n}\nBecause the above uses mkOptionDefault but instead in under the config\nattribute like the following:
# ...snip...\noptions.strings = lib.mkOption {\n type = lib.types.attrsOf lib.types.lines;\n # default = {\n # x = \"foo\";\n # };\n};\nconfig = {\n strings = {\n x = lib.mkDefault \"foo\";\n };\n};\n# ...snip...\nlet\n lib = import <nixpkgs/lib>;\nin\n lib.evalModules {\n modules = [\n ({lib, ...}: {\n options.ints = lib.mkOption {\n type = lib.types.attrsOf lib.types.int;\n };\n options.strings = lib.mkOption {\n # type = lib.types.string;\n type = lib.types.attrsOf lib.types.str;\n # Sets the value with a lower priority: lib.mkOptionDefault\n #default = {\n # x = \"foo\";\n #};\n };\n config.strings = {\n x = \"foo\";\n };\n })\n {\n config.strings = {\n y = \"bar\";\n };\n }\n ];\n }\nOutput:
\nx and y{ x = \"foo\"; y = \"bar\"; }\nlet\n lib = import <nixpkgs/lib>;\nin\n lib.evalModules {\n modules = [\n ({lib, ...}: {\n options.ints = lib.mkOption {\n type = lib.types.attrsOf lib.types.int;\n };\n options.strings = lib.mkOption {\n # type = lib.types.string;\n type = lib.types.attrsOf lib.types.str;\n # Sets the value with a lower priority: lib.mkOptionDefault\n #default = {\n # x = \"foo\";\n #};\n };\n config.strings = {\n x = lib.mkDefault \"foo\";\n };\n })\n {\n config.strings = {\n x = \"x\";\n y = \"bar\";\n };\n }\n ];\n }\nx = lib.mkDefault foo\nAnd this is typically what you want to do for defaults and modules in things\nlike nested configuration.Output:
\n{ x = \"x\"; y = \"bar\"; }\ninfinite recursion\nwhen shadowing a name. The simplest example for this is:\n\n\nlet a = 1; in rec { a = a; }\n
\n\n💡TIP: Avoid
\nrec. Uselet ... inExample:\nlet\n a = 1;\nin {\n a = a;\n b = a + 2;\n}\n
We’ll separate the logic for this example, this will be the default.nix this\nis where having lib defined in your inline modules is helpful because you can\njust delete the section and paste it into your modules.nix:
# default.nix\nlet\n lib = import <nixpkgs/lib>;\nin\n lib.evalModules {\n modules = [\n ./module.nix\n ];\n }\nAnd in the module.nix:
# module.nix\n{ lib, pkgs, ...}: {\n options.etc = lib.mkOption {\n type = lib.types.attrsOf lib.types.path;\n default = { };\n description = ''\n Specifies which paths are is /etc/\n '';\n };\n\n config._module.args.pkgs = import <nixpkgs> {\n config = {};\n overlays = [];\n };\n config.etc.foo = pkgs.writeText \"foo\" ''\n foo configuration\n '';\n}\nnix-instantiate --eval --strict -A config.etc\n--strict evaluates the etc, then it goes into the\nattrsOf, and the pathnix repl\nnix-repl> :l <nixpkgs>\nnix-repl> hello.out.out.out\nIn this example:
\n:l <nixpkgs> loads the Nixpkgs library into the repl environment, making its\ndefinitions available.
hello refers to the hello package definition within Nixpkgs. Packages in\nNixpkgs are defined as derivations.
.out is a common attribute name for the main output of a derivation (e.g.,\nthe installed package). Some packages, especially those with complex build\nprocesses or multiple outputs, might have nested output attributes. In the\ncase of hello, accessing .out.out.out ultimately leads us to the\nderivation itself.
The key takeaway here is that when you evaluate a package in the nix repl,\nyou’re often interacting with its derivation or one of its output paths in the\nNix store. The «derivation ...» indicates that hello.out.out.out evaluates\nto a derivation – the blueprint for building the hello package. This is in\ncontrast to --eval --strict, which tries to fully evaluate values, potentially\nleading to infinite recursion if it encounters a derivation that refers back to\nitself indirectly during attribute evaluation.
Output:
\n«derivation /nix/store/b1vcpm321dwbwx6wj4n13l35f4y2wrfv-hello-2.12.1.drv»\nSo we want to change the command from --eval --strict which is only based on\nevaluation to at least nix-instantiate which is based on derivations:
nix-instantiate -A config.etc\nOutput:
\nwarning: you did not specify '--add-root'; the result might be removed by the garbage collector\n/nix/store/abyfp1rxk73p0n5kfilv7pawxwvc7hsg-foo.drv\n# module.nix\n{\n lib,\n pkgs,\n ...\n}: {\n options.etc = lib.mkOption {\n type = lib.types.attrsOf (lib.types.attrsOf lib.types.path);\n default = {};\n description = ''\n Specifies which paths are in /etc/\n '';\n };\n\n config._module.args.pkgs = import <nixpkgs> {\n config = {};\n overlays = [];\n };\n config.etc.foo.bar = pkgs.writeText \"foo\" ''\n foo configuration\n '';\n}\nTry to evaluate the above command with nix-instantiate -A config.etc and Nix\ndoesn’t even try to build it. With nested attrsOf
nix repl -f default.nix\nnix-repl> config.etc\n{\n foo = { ... };\n}\nnix-repl> config.etc.foo\n{\n bar = «derivation /nix/store/abyfp1rxk73p0n5kfilv7pawxwvc7hsg-foo.drv»;\n}\nconfig.foo is an attribute set and config.etc.foo is also an attribute\nset but it’s not a derivation by itself. So nix-instantiate does this one\nlevel of recursion here and it would have built foo value if it were a\nderivation.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\nfocus on a common task in system configuration: managing files within the\n/etc/ directory. We’ll define a module that allows us to specify the content\nof arbitrary files in /etc/ and then use a special Nix function to combine\nthese individual file definitions into a single, manageable entity.
We’ll introduce a new option, options.etc, which will allow us to define the\ncontent of files within /etc/. Then, we’ll use pkgs.linkFarm to create a\nderivation that represents the entire /etc/ directory as a collection of\nsymbolic links pointing to the individual file contents we’ve defined. This\ndemonstrates how modules can abstract away the details of creating complex\nsystem configurations, providing a declarative and reproducible way to manage\neven fundamental aspects of the operating system.
Let’s show how we can use Nix modules to declaratively manage the /etc/\ndirectory
# default.nix\nlet\n lib = import <nixpkgs/lib>;\nin\n lib.evalModules {\n modules = [\n ./module.nix\n ];\n }\n\n# module.nix\n{\n lib,\n pkgs,\n config,\n ...\n}: {\n options.etc = lib.mkOption {\n type = lib.types.attrsOf (lib.types.attrsOf lib.types.path);\n default = {};\n description = ''\n Specifies which paths are in /etc/\n '';\n };\n options.etcCombined = lib.mkOption {\n type = lib.types.package;\n default =\n pkgs.linkFarm \"etc\"\n (lib.mapAttrsToList (name: value: {\n name = name;\n path = value;\n }) config.etc);\n };\n\n config._module.args.pkgs = import <nixpkgs> {\n config = {};\n overlays = [];\n };\n config.etc.foo = pkgs.writeText \"foo\" ''\n foo configuration\n '';\n config.etc.bar = pkgs.writeText \"bar\" ''\n bar configuration\n '';\n}\n\nRun it with:
\nnix-instantiate -A config.etcCombined\nOutput:
\n/nix/store/3da61nmfk546qn2zpxsm57mq6vz6fjx8-etc.drv\nnix-build -A config.etcCombined\nOutput:
\nthese 3 derivations will be built:\n/nix/store/41yfxq4af1vrs0rrgfk5gc36kmjc7270-bar.drv\n/nix/store/abyfp1rxk73p0n5kfilv7pawxwvc7hsg-foo.drv\n/nix/store/3da61nmfk546qn2zpxsm57mq6vz6fjx8-etc.drv\nbuilding '/nix/store/41yfxq4af1vrs0rrgfk5gc36kmjc7270-bar.drv'...\nbuilding '/nix/store/abyfp1rxk73p0n5kfilv7pawxwvc7hsg-foo.drv'...\nbuilding '/nix/store/3da61nmfk546qn2zpxsm57mq6vz6fjx8-etc.drv'...\n/nix/store/ca3wyk5m3qhy8n1nbn0181m29qvp1klp-etc\nnix-build -A config.etcCombined && ls result/ -laa\nOutput:
\n/nix/store/ca3wyk5m3qhy8n1nbn0181m29qvp1klp-etc\ndr-xr-xr-x - root 31 Dec 1969 .\ndrwxrwxr-t - root 16 May 15:13 ..\nlrwxrwxrwx - root 31 Dec 1969 bar -> /nix/store/1fsjyc2hmilab1qw6jfkf6cb767kz858-bar\nlrwxrwxrwx - root 31 Dec 1969 foo -> /nix/store/wai5dycp0zx1lxg0rhpdxnydhiadpk05-foo\nWe can see that foo and bar link to different derivations
When trying to figure out which default to use for etcCombined infinisil\nwent to the Nixpkgs Reference Manual. Make sure to go to the correct version.
25.05pre-git (i.e. unstable)
\nOnce at the website press Ctrl+f and type symlinkjoin and hit enter.
Or in your local copy of Nixpkgs you could go to\nnixpkgs/pkgs/build-support/ trivial-builders/default.nix. Then use your\neditors search feature, with nvim and helix you press /symlinkjoin or\n/linkFarm hit enter then press n to cycle to the next match. It will bring\nyou to comments and up to date information.
# linkFarm \"myexample\" [ { name = \"hello-test\"; path = pkgs.hello; }\n# { name = \"foobar\"; path = pkgs.stack; } ]\npassthru.tests outside of Nixpkgs and then\nrun tests available to your package set?mkdir passthru-tests && cd passthru-tests\nCreate a default.nix with the following:
# default.nix\nlet\n pkgs = import <nixpkgs> {};\n\n package = pkgs.runCommand \"foo\" {\n passthru.tests.simple = pkgs.runCommand \"foo-test\" {} ''\n if [[ \"$(cat ${package})\" != \"foo\" ]]; then\n echo \"Result is not foo\"\n exit 1\n fi\n touch $out\n '';\n } ''\n echo foo > $out\n '';\nin\npackage\nSee if it will build:
\nnix-build\nTry running the test:
\nnix-build -A passthru.tests\nthis derivation will be built:\n/nix/store/pqpqq9x1wnsabzbsb52z4g4y4zy6p7yx-foo-test.drv\nbuilding '/nix/store/pqpqq9x1wnsabzbsb52z4g4y4zy6p7yx-foo-test.drv'...\n/nix/store/7bbw2ban0mgkh4d59yz3cnai4aavwvb6-foo-test\npassthru.tests is the convention for defining tests associated with a\nderivation. The attributes in passthru are preserved and accessible after\nthe derivation is built.let\n pkgs = import <nixpkgs> {};\n\n package =\n pkgs.runCommand \"foo\" {\n passthru.tests.simple = pkgs.runCommand \"foo-test\" {} ''\n if [[ \"$(cat ${package})\" != \"foo\" ]]; then\n echo \"Result is not foo\"\n exit 1\n fi\n touch $out\n '';\n\n passthru.tests.version = pkgs.testers.testVersion {\n package = package;\n version = \"1.2\";\n };\n\n # pkgs.writeShellApplication\n script = ''\n #!${pkgs.runtimeShell}\n echo \"1.2\"\n '';\n passAsFiles = [ \"script\" ];\n\n } ''\n cp \"$scriptPath\" \"$out\"\n '';\nin\n package\nTry to build it:
\nnix-build -A passthru.tests\ntesters.testVersion checks if an executable outputs a specific version\nstring.
nix-build -A passthru.tests specifically targets the derivations defined\nwithin the tests attribute of the main derivation.
these 3 derivations will be built:\n /nix/store/lyz86bd78p7f3yjy1qky6annmggymcwd-foo.drv\n /nix/store/s4iawjy5zpv89dbkc3zz7z3ngz4jq2cv-foo-test.drv\n /nix/store/z3gi4pb8jn2h9rvk4dhba85fiphp5g4z-foo-test-version.drv\nbuilding '/nix/store/lyz86bd78p7f3yjy1qky6annmggymcwd-foo.drv'...\ncp: cannot stat '': No such file or directory\nerror: builder for '/nix/store/lyz86bd78p7f3yjy1qky6annmggymcwd-foo.drv'\n failed with exit code 1;\n last 1 log lines:\n > cp: cannot stat '': No such file or directory\n For full logs, run:\n nix log /nix/store/lyz86bd78p7f3yjy1qky6annmggymcwd-foo.drv\nerror: 1 dependencies of derivation '/nix/store/z3gi4pb8jn2h9rvk4dhba85fiphp5g4z\n-foo-test-version.drv' failed to build\nerror: build of '/nix/store/s4iawjy5zpv89dbkc3zz7z3ngz4jq2cv-foo-test.drv',\n '/nix/store/z3gi4pb8jn2h9rvk4dhba85fiphp5g4z-foo-test-version.drv' failed\nRun nix-build with no arguments:
nix-build\nnix derivation show /nix/store/lyz86bd78p7f3yjy1qky6annmggymcwd-foo.drv | jq '.[].env'\nOutput:
\n{\n \"__structuredAttrs\": \"\",\n \"buildCommand\": \"cp \\\"$scriptPath\\\" \\\"$out\\\"\\n\",\n \"buildInputs\": \"\",\n \"builder\": \"/nix/store/xg75pc4yyfd5n2fimhb98ps910q5lm5n-bash-5.2p37/bin/bash\",\n \"cmakeFlags\": \"\",\n \"configureFlags\": \"\",\n \"depsBuildBuild\": \"\",\n \"depsBuildBuildPropagated\": \"\",\n \"depsBuildTarget\": \"\",\n \"depsBuildTargetPropagated\": \"\",\n \"depsHostHost\": \"\",\n \"depsHostHostPropagated\": \"\",\n \"depsTargetTarget\": \"\",\n \"depsTargetTargetPropagated\": \"\",\n \"doCheck\": \"\",\n \"doInstallCheck\": \"\",\n \"enableParallelBuilding\": \"1\",\n \"enableParallelChecking\": \"1\",\n \"enableParallelInstalling\": \"1\",\n \"mesonFlags\": \"\",\n \"name\": \"foo\",\n \"nativeBuildInputs\": \"\",\n \"out\": \"/nix/store/9mcrnddb6lf1md14v4lj6s089i99l5k7-foo\",\n \"outputs\": \"out\",\n \"passAsFile\": \"buildCommand\",\n \"passAsFiles\": \"script\",\n \"patches\": \"\",\n \"propagatedBuildInputs\": \"\",\n \"propagatedNativeBuildInputs\": \"\",\n \"script\": \"#!/nix/store/xg75pc4yyfd5n2fimhb98ps910q5lm5n-bash-5.2p37/bin/bash\\necho \\\"1.2\\\"\\n\",\n \"stdenv\": \"/nix/store/lgydi1gl5wqcw6k4gyjbaxx7b40zxrsp-stdenv-linux\",\n \"strictDeps\": \"\",\n \"system\": \"x86_64-linux\"\n}\nnix derivation show /nix/store/lyz86bd78p7f3yjy1qky6annmggymcwd-foo.drv | jq\n '.[].env.buildCommand'\nOutput:
\n\"cp \\\"$scriptPath\\\" \\\"$out\\\"\\n\"\nnix derivation show /nix/store/lyz86bd78p7f3yjy1qky6annmggymcwd-foo.drv | jq\n '.[].env.buildCommand' -r\nOutput:
\ncp \"$scriptPath\" \"$out\"\npassAsFile not passAsFiles but that\nchange wasn’t enough to fix it. passAsFiles expects a list of files, not a\nsingle file path. Running nix-build -A passthru.tests failed saying\n> foo --version returned a non-zero exit code.let\n pkgs = import <nixpkgs> {};\n\n package =\n pkgs.runCommand \"foo\" {\n #passthru.tests.simple = pkgs.runCommand \"foo-test\" {} ''\n # if [[ \"$(cat ${package})\" != \"foo\" ]]; then\n # echo \"Result is not foo\"\n # exit 1\n # fi\n # touch $out\n #'';\n\n passthru.tests.version = pkgs.testers.testVersion {\n package = package;\n version = \"1.2\";\n };\n\n # pkgs.writeShellApplication\n script = ''\n #!${pkgs.runtimeShell}\n echo \"1.2\"\n '';\n passAsFile = [\"script\"];\n } ''\n mkdir -p \"$out/bin\"\n cp \"$scriptPath\" \"$out/bin/foo\"\n chmod +x \"$out/bin/foo\"\n '';\nin\n package\nBuild it:
\nnix-build -A passthru.tests\nOutput:
\nthese 2 derivations will be built:\n /nix/store/lqrlcd64dmpzkggcfzlnsnwjd339czd3-foo.drv\n /nix/store/c3kw4xbdlrig08jrdm5wis1dmv2gnqsd-foo-test-version.drv\nbuilding '/nix/store/lqrlcd64dmpzkggcfzlnsnwjd339czd3-foo.drv'...\nbuilding '/nix/store/c3kw4xbdlrig08jrdm5wis1dmv2gnqsd-foo-test-version.drv'...\n1.2\n/nix/store/zsbk5zawak68ailvkwi2gad2bqbqmdz9-foo-test-version\nnix-instantiate is Your Friend: Use nix-instantiate to evaluate your\nNixOS modules and pinpoint errors.
Unlock Details with --show-trace: When errors occur, always append\n--show-trace to get a comprehensive stack trace, revealing the origin of the\nproblem. Remember that in newer Nix versions, the most relevant parts of the\ntrace are often at the bottom.
Understand Option Types: Nix option types (raw, anything,\nstring/str, lines, attrsOf) are not just about data types; they also\ndictate how values are merged and processed within the module system.
Be Mindful of mkOptionDefault: While useful in specific scenarios,\nmkOptionDefault sets a lower priority default. For standard defaults that\ncan be overridden by user configuration, define them directly within the\nconfig attribute using lib.mkDefault.
Use builtins.addErrorContext: Enhance your custom error messages by\nproviding specific context relevant to your module’s logic using\nbuiltins.addErrorContext.
Derivations vs. Evaluation: Be aware of the difference between evaluating\nexpressions (--eval --strict) and instantiating derivations\n(nix-instantiate). Strict evaluation can trigger infinite recursion if it\nencounters unevaluated derivations with cyclic dependencies during attribute\naccess.
Explore with nix repl: The nix repl allows you to interactively\nexplore Nix expressions and the outputs of derivations, providing insights\ninto the structure and values within Nixpkgs.
This chapter has equipped you with essential techniques for debugging and\ntracing NixOS modules. We’ve explored how to use nix-instantiate and\n--show-trace to pinpoint errors, how to interpret Nix’s often-verbose error\nmessages, and how to leverage the nix repl for interactive exploration.\nUnderstanding option types and the nuances of mkOptionDefault is crucial for\nwriting robust and predictable modules. We’ve also touched upon the distinction\nbetween evaluation and instantiation, and how that impacts debugging.
While these tools and techniques are invaluable for understanding and\ntroubleshooting your own Nix configurations, they also become essential when you\nwant to contribute to or modify the vast collection of packages and modules\nwithin Nixpkgs itself. Nixpkgs is where the majority of Nix packages and\nNixOS modules reside, and learning how to navigate and contribute to it opens up\na whole new level of control and customization within the Nix ecosystem.
\nIn the next chapter,\nWorking with Nixpkgs Locally,\nwe’ll shift our focus to exploring and modifying Nixpkgs. We’ll cover how to\nclone Nixpkgs, how to make changes to package definitions, and how to test those\nchanges locally before contributing them back upstream. This chapter will\nempower you to not just use existing Nix packages, but also to customize and\nextend them to fit your specific needs.
\n", "date_published": "2025-11-22T00:00:00+00:00", "author": { "name": "saylesss87@proton.me (saylesss88)" } }, { "id": "https://saylesss88.github.io/NixOS_Modules_Explained_3.html", "url": "https://saylesss88.github.io/NixOS_Modules_Explained_3.html", "title": "Nix Module System Explained", "content_html": "![\"buildings\"](\"https://saylesss88.github.io/images/buildings1.png\")
TL;DR: In this chapter, we will break down the Nix module system used by\nboth NixOS and Home-Manager. We will discuss using home-manager as a module and\nthe flexibility that modules give us. We will touch on options and break down\nthe vim module from the Nixpkgs collection. Finally we will display how to\ntest modules with the repl.
Your configuration.nix is a module. For the Nixpkgs collection most modules\nare in nixos/modules.
The suggested way of using home-manager according to their manual is as a\nNixOS module.\nBoth home-manager and NixOS use the same module system.
{\n imports = [\n # Paths to other modules.\n # Compose this module out of smaller ones.\n ];\n\n options = {\n # Option declarations.\n # Declare what settings a user of this module can set.\n # Usually this includes a global \"enable\" option which defaults to false.\n };\n\n config = {\n # Option definitions.\n # Define what other settings, services and resources should be active.\n # Usually these depend on whether a user of this module chose to \"enable\" it\n # using the \"option\" above.\n # Options for modules imported in \"imports\" can be set here.\n };\n}\nimports, options, and config are the top-level attributes of a Nix module.\nThey are the primary, reserved keys that the Nix module system recognizes and\nprocesses to combine different configurations into a single, cohesive system or\nuser environment. config is the same config you receive as a module argument\n(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\nthis blueprint. So, when a module receives the config argument, it’s getting\nthe complete picture of everything you’ve asked NixOS to set up so far.
This allows the module to:
\nSee what other parts of your system are doing.
\nMake smart decisions based on those settings.
\nAdd its own pieces to the overall plan, building on what’s already there.
\nMost modules are functions that take an attribute set and return an attribute\nset.
\nTo turn the above module into a function accepting an attribute set just add the\nfunction arguments to the top, click the eye to see the whole module:
\n{ config, pkgs, ... }:\n~ {\n~ imports = [\n~ # Paths to other modules.\n~ # Compose this module out of smaller ones.\n~ ];\n~\n~ options = {\n~ # Option declarations.\n~ # Declare what settings a user of this module can set.\n~ # Usually this includes a global \"enable\" option which defaults to false.\n~ };\n~\n~ config = {\n~ # Option definitions.\n~ # Define what other settings, services and resources should be active.\n~ # Usually these depend on whether a user of this module chose to \"enable\" it\n~ # using the \"option\" above.\n~ # Options for modules imported in \"imports\" can be set here.\n~ };\n~ }\nIt may require the attribute set to contain:
\nconfig: The configuration of the entire system.
options: All option declarations refined with all definition and declaration\nreferences.
pkgs: The attribute set extracted from the Nix package collection and\nenhanced with the nixpkgs.config option.
modulesPath: The location of the module directory of NixOS.
Many people start of using a single configuration.nix and eventually their\nsingle file configuration gets too large to search through and maintain\nconveniently.
This is where modules come in allowing you to break up your configuration\ninto logical parts. Your boot.nix will contain settings and options related to\nthe actual boot process. You’re services.nix will only have services and so\non…
configuration.nix or equivalent or if you’re using flakes relative to your\nflake.nix or equivalent.\nimports mechanism takes paths to other modules as its argument and\ncombines them to be included in the evaluation of the system configuration.\n\n\n{ ... }:\n{\n imports = [\n # Paths to other modules\n\n # They can be relative paths\n ./otherModule.nix\n\n # Or absolute\n /path/to/otherModule.nix\n\n # Or to a directory\n ../modules/home/shells/nushell\n ];\n}\n
\n\n❗: The imports mechanism includes and evaluates the Nix expression found\nat the given path as a module. If that path is a directory, it will\nautomatically look for and evaluate a
\ndefault.nixfile within that directory\nas a module. It is common to have thatdefault.nixbe a function that only\nimports and combines all the modules in said directory. Like the above\nexample, in the nushell directory would be adefault.nixthat is\nautomatically imported and evaluated.
Crucial Distinction: imports vs. import:
Beginners often confuse the modules attribute imports = [./module.nix] here\nwith the Nix builtins function import module.nix. The first expects a path to\na file containing a NixOS module (having the same specific structure we’re\ndescribing here), while the second loads whatever Nix expression is in that file\n(no expected structure). –NixOS Wiki.
Considering configuration.nix is a module, it can be imported like any other\nmodule and this is exactly what you do when getting started with flakes.
# flake.nix\n{\n description = \"NixOS configuration\";\n\n inputs = {\n nixpkgs.url = \"github:nixos/nixpkgs/nixos-unstable\";\n home-manager.url = \"github:nix-community/home-manager\";\n home-manager.inputs.nixpkgs.follows = \"nixpkgs\";\n };\n\n outputs = inputs@{ nixpkgs, home-manager, ... }: {\n nixosConfigurations = {\n hostname = nixpkgs.lib.nixosSystem {\n system = \"x86_64-linux\";\n modules = [\n ./configuration.nix\n home-manager.nixosModules.home-manager\n {\n home-manager.useGlobalPkgs = true;\n home-manager.useUserPackages = true;\n home-manager.users.jdoe = ./home.nix;\n\n # Optionally, use home-manager.extraSpecialArgs to pass\n # arguments to home.nix\n }\n ];\n };\n };\n };\n}\nmodules = [...] in flake.nix: This is effectively the initial imports list\nfor your entire NixOS system or Home Manager user configuration. It tells the\nNix module system: “Start by collecting and merging the configurations defined\nin these specific modules.”
The above example is what you get from running:\nnix flake new /etc/nixos -t github:nix-community/home-manager#nixos
If you notice the home-manager.nixosModules.home-manager, that is what imports\nhome-manager as a module.
You could also make the actual home-manager module and import it like this:
\n# home-manager.nix\n{ inputs, outputs, ... }: {\n imports = [\n # Import home-manager's NixOS module\n inputs.home-manager.nixosModules.home-manager\n ];\n\n home-manager = {\n extraSpecialArgs = { inherit inputs outputs; };\n users = {\n # Import your home-manager configuration\n your-username = import ../home-manager/home.nix;\n };\n };\n}\nThis “module” isn’t much different from the one included in the flake.nix\nabove, it is just shown here to show the flexibility of modules. They can be as\nbig and complex or as small and simple as you want. You can break up every\nsingle program or component of your configuration into individual modules or\nhave modules that bundle similar programs the choice is yours.
Then in your configuration.nix or equivalent you would add home-manager.nix\nto your imports list and you would have home-manager as a NixOS module.
An attribute set is a collection of name-value pairs called attributes:
\nAttribute sets are written enclosed in curly braces {}. Attribute names and\nattribute values are separated by an equal sign =. Each value can be an\narbitrary expression, terminated by a semicolon ;.
\n\nExample:nix.dev reference\nThis defines an attribute set with attributes named:
\n\n
\n- \n
xwith the value123, an integer- \n
textwith the value\"Hello\", a string- \n
ywhere the value is the result of applying the functionfto the\nattribute set{bla = 456; }\n{\n x = 123;\n text = \"Hello\";\n y = f { bla = 456; };\n}\n\n{ a = \"Foo\"; b = \"Bar\"}.a\n~ \"Foo\"\n
Attributes can appear in any order. An attribute name may only occur once in\neach attribute set.
\n\n\n❗ Remember
\n{}is a valid attribute set in Nix.
The following is a function with an attribute set argument, remember that\nanytime you see a : in Nix code it means this is a function. To the left is\nthe function arguments and to the right is the function body:
{ a, b }: a + b\nThe simplest possible NixOS Module:
\n{ ... }:\n{\n}\nNixOS produces a full system configuration by combining smaller, more isolated\nand reusable components: Modules. If you want to understand Nix and NixOS\nmake sure you grasp modules!
\nA NixOS module defines configuration options and behaviors for system\ncomponents, allowing users to extend, customize, and compose configurations\ndeclaratively.
\nA module is a file containing a Nix expression with a specific structure. It\ndeclares options for other modules to define (give a value). Modules were\nintroduced to allow extending NixOS without modifying its source code.
\nTo define any values, the module system first has to know which ones are\nallowed. This is done by declaring options that specify which attributes can be\nset and used elsewhere.
\nIf you want to write your own modules, I recommend setting up\nnixd or\nnil with your editor of choice. This will\nallow your editor to warn you about missing arguments and dependencies as well\nas syntax errors.
\nOptions are declared under the top-level options attribute with\nlib.mkOption.
mkOption\nCreates an Option attribute set. It accepts an attribute set with certain keys\nsuch as, default, package, and example.
# options.nix\n{ lib, ... }:\n{\n options = {\n name = lib.mkOption { type = lib.types.str; };\n };\n}\n\n\n\n
libprovides helper functions fromnixpkgs.liband the ellipsis (...) is\nfor arbitrary arguments which means that this function is prepared to accept\nany additional arguments that the caller might provide, even if those\narguments are not explicitly named or used within the module’s body. They make\nthe modules more flexible, without the...each module would have to\nexplicitly list every possible argument it might receive, which would be\ncumbersome and error-prone. So{lib, ... }:means that “I need thelib\nargument” and I acknowledge that the module system might pass other\narguments automatically (likeconfig,pkgs, etc.) and I’m fine with them\nbeing there, even if I don’t use them directly in this specific module file.
Options are set or defined under the top-level config attribute:
# config.nix\n{ ... }:\n{\n config = {\n name = \"Slick Jones\";\n };\n}\nIn this option declaration, we created an option name of type string and\nset that same option to a string.
Option Definitions can be in a separate file than Option Declarations
\nModules are evaluated with\nlib.evalModules\nlib.evalModules evaluates a set of modules, typically once per application\n(e.g. once for NixOS and once for Home-Manager).
The following is nixpkgs/nixos/modules/programs/vim.nix, a module that is\nincluded in the Nixpkgs collection:
{\n config,\n lib,\n pkgs,\n ...\n}:\n\nlet\n cfg = config.programs.vim;\nin\n{\n options.programs.vim = {\n enable = lib.mkEnableOption \"Vi IMproved, an advanced text\";\n\n defaultEditor = lib.mkEnableOption \"vim as the default editor\";\n\n package = lib.mkPackageOption pkgs \"vim\" { example = \"vim-full\"; };\n };\n\n # TODO: convert it into assert after 24.11 release\n config = lib.mkIf (cfg.enable || cfg.defaultEditor) {\n warnings = lib.mkIf (cfg.defaultEditor && !cfg.enable) [\n \"programs.vim.defaultEditor will only work if programs.vim.enable is\n enabled, which will be enforced after the 24.11 release\"\n ];\n environment = {\n systemPackages = [ cfg.package ];\n variables.EDITOR = lib.mkIf cfg.defaultEditor (lib.mkOverride 900 \"vim\");\n pathsToLink = [ \"/share/vim-plugins\" ];\n };\n };\n}\nIt provides options to enable Vim, set it as the default editor, and specify the\nVim package to use.
\n{\n config,\n lib,\n pkgs,\n ...\n}\nInputs: The module takes the above inputs and ... (catch-all for other\nargs)
config: Allows the module to read option values (e.g.\nconfig.programs.vim.enable). It provides access to the evaluated\nconfiguration.
lib: The Nixpkgs library, giving us helper functions like mkEnableOption ,\nmkIf, and mkOverride.
pkgs: The Nixpkgs package set, used to access packages like pkgs.vim
...: Allows the module to accept additional arguments, making it flexible\nfor extension in the future.
\n\nKey Takeaways: A NixOS module is typically a function that can include\n
\nconfig,lib, andpkgs, but it doesn’t require them. The...argument\nensures flexibility, allowing a module to accept extra inputs without breaking\nfuture compatibility. Usinglibsimplifies handling options (mkEnableOption,\nmkIf, mkOverride) and helps follow best practices. Modules define options,\nwhich users can set in their configuration, andconfig, which applies\nchanges based on those options.
let\n cfg = config.programs.vim;\nin\nThis is a local alias. Instead of typing config.programs.vim over and over,\nthe module uses cfg.
options.programs.vim = {\n enable = lib.mkEnableOption \"Vi IMproved, an advanced text\";\n defaultEditor = lib.mkEnableOption \"vim as the default editor\";\n package = lib.mkPackageOption pkgs \"vim\" { example = \"vim-full\"; };\n};\nThis defines three user-configurable options:
\nenable: 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.
\n\n\n
mkPackageOptionis a helper that defines a package-typed option with a\ndefault (pkgs.vim) and provides docs + example. Usinglib.mkEnableOption\nmakes it clear exactly where this function is coming from. Same with\nlib.mkIfand as you can see they can be further down the configuration,\nfurther from where you definedwith lib;making it less clear where they\ncome from. Explicitness is your friend when it comes to reproducability and\nclarity.
config = lib.mkIf (cfg.enable || cfg.defaultEditor) {\nprograms.vim.enable or\ndefaultEditor is set.warnings = lib.mkIf (cfg.defaultEditor && !cfg.enable) [\n \"programs.vim.defaultEditor will only work if programs.vim.enable is enabled,\n which will be enforced after the 24.11 release\"\n];\nGives you a soft warning if you try to set defaultEditor = true without also\nenabling Vim.
environment = {\n systemPackages = [ cfg.package ];\n variables.EDITOR = lib.mkIf cfg.defaultEditor (lib.mkOverride 900 \"vim\");\n pathsToLink = [ \"/share/vim-plugins\" ];\n};\nIt adds Vim to your systemPackages, sets $EDITOR if defaultEditor is true,\nand makes /share/vim-plugins available in the environment.
The following is a bat home-manager module that I wrote:
\n# bat.nix\n{\n pkgs,\n config,\n lib,\n ...\n}: let\n cfg = config.custom.batModule;\nin {\n options.custom.batModule.enable = lib.mkOption {\n type = lib.types.bool;\n default = false;\n description = \"Enable bat module\";\n };\n\n config = lib.mkIf cfg.enable {\n programs.bat = {\n enable = true;\n themes = {\n dracula = {\n src = pkgs.fetchFromGitHub {\n owner = \"dracula\";\n repo = \"sublime\"; # Bat uses sublime syntax for its themes\n rev = \"26c57ec282abcaa76e57e055f38432bd827ac34e\";\n sha256 = \"019hfl4zbn4vm4154hh3bwk6hm7bdxbr1hdww83nabxwjn99ndhv\";\n };\n file = \"Dracula.tmTheme\";\n };\n };\n extraPackages = with pkgs.bat-extras; [\n batdiff\n batman\n prettybat\n batgrep\n ];\n };\n };\n}\nNow I could add this to my home.nix to enable it:
# home.nix\ncustom = {\n batModule.enable = true;\n}\nIf I set this option to true the bat configuration is dropped in place. If it’s\nnot set to true, it won’t put the bat configuration in the system. Same as with\noptions defined in modules within the Nixpkgs repository.
\nIf I had set the default to true, it would automatically enable the module\nwithout requiring an explicit custom.batModule.enable = true; call in my\nhome.nix.
NixOS achieves its full system configuration by combining the configurations\ndefined in various modules. This composition is primarily handled through the\nimports mechanism.
imports: This is a standard option within a NixOS or Home Manager\nconfiguration (often found in your configuration.nix or home.nix). It takes a\nlist of paths to other Nix modules. When you include a module in the imports\nlist, the options and configurations defined in that module become part of your\noverall system configuration.
You declaratively state the desired state of your system by setting options\nacross various modules. The NixOS build system then evaluates and merges these\noption settings. The culmination of this process, which includes building the\nentire system closure, is represented by the derivation built by\nconfig.system.build.toplevel.
Traditionally, NixOS configurations often implicitly rely on the version of\nNixpkgs available when nixos-rebuild is run. However, for more robust and\nreproducible setups, especially in collaborative environments or when rolling\nback to specific configurations, explicitly locking these dependencies to\nspecific versions becomes crucial.
In the following example, we’ll explore how to use a tool called npins to\nmanage and lock the dependencies of a NixOS configuration, ensuring a more\npredictable and reproducible system. This will involve setting up a project\nstructure and using npins to pin the specific version of Nixpkgs our\nconfiguration relies on.
This is the file structure:
\n❯ tree\n.\n├── configuration.nix\n├── default.nix\n├── desktop.nix\n└── npins\n ├── default.nix\n └── sources.json\nThis uses npins for dependency locking. Install it and run this in the project
directory:
\nnpins init\nCreate a default.nix with the following:
# default.nix\n{ system ? builtins.currentSystem, sources ? import ./npins, }:\nlet\n pkgs = import sources.nixpkgs {\n config = { };\n overlays = [ ];\n };\n inherit (pkgs) lib;\nin lib.makeScope pkgs.newScope (self: {\n\n shell = pkgs.mkShell { packages = [ pkgs.npins self.myPackage ]; };\n\n # inherit lib;\n\n nixosSystem = import (sources.nixpkgs + \"/nixos\") {\n configuration = ./configuration.nix;\n };\n\n moduleEvale = lib.evalModules {\n modules = [\n # ...\n ];\n };\n})\nA configuration.nix with the following:
# configuration.nix\n{\n boot.loader.grub.device = \"nodev\";\n fileSystems.\"/\".device = \"/devst\";\n system.stateVersion = \"25.05\";\n\n # declaring options means to declare a new option\n # defining options means to define a value of an option\n imports = [\n # ./main.nix\n ./desktop.nix # Files\n # ./minimal.nix\n ];\n\n # mine.desktop.enable = true;\n}\nAnd a desktop.nix with the following:
# desktop.nix\n{ pkgs, lib, config, ... }:\n\n{\n imports = [];\n\n # Define an option to enable or disable desktop configuration\n options.mine.desktop.enable = lib.mkEnableOption \"desktop settings\";\n\n # Configuration that applies when the option is enabled\n config = lib.mkIf config.mine.desktop.enable {\n environment.systemPackages = [ pkgs.git ];\n };\n}\nmkEnableOption defaults to false. Now in your configuration.nix you can\nuncomment mine.desktop.enable = true; to enable the desktop config and\nvice-versa.
You can test that this works by running:
\nnix-instantiate -A nixosSystem.system\nnix-instantiate performs only the evaluation phase of Nix expressions. During\nthis phase, Nix interprets the Nix code, resolves all dependencies, and\nconstructs derivations but does not execute any build actions. Useful for\ntesting.
To check if this worked and git is installed in systemPackages you can load it\ninto nix repl but first you’ll want lib to be available so uncomment this in\nyour default.nix:
# default.nix\ninherit lib;\nRerun nix-instantiate -A nixosSystem.system
Then load the repl and check that git is in systemPackages:
nix repl -f .\nnix-repl> builtins.filter (pkg: lib.hasPrefix \"git\" pkg.name) nixosSystem.config.environment.systemPackages\nThis shows the path to the derivation
\nCheck that mine.desktop.enable is true
\nnix-repl> nixosSystem.config.mine.desktop.enable\ntrue\nAs demonstrated with npins, explicitly managing the dependencies of your NixOS\nmodules is a powerful technique for ensuring the long-term stability and\nreproducibility of your system configurations. By pinning specific versions of\nNixpkgs and other resources, you gain greater control over your environment and\nreduce the risk of unexpected changes due to upstream updates.
\nYou’ll see the following all throughout Nix code and is convenient although it\ndoesn’t follow best practices. One reason is static analysis can’t reason about\nthe code (e.g. Because it implicitly brings all attributes into scope, tools\ncan’t verify which ones are actually being used), because it would have to\nactually evaluate the files to see which names are in scope:
\n# utils.nix\n{ pkgs, ... }: {\n environment.systemPackages = with pkgs; [\n rustup\n evcxr\n nix-prefetch-git\n ];\n}\nAnother reason the above expression is considered an “anti-pattern” is when more\nthen one with is used, it’s no longer clear where the names are coming from.
Scoping rules for with are not intuitive, see\nissue –nix.dev This can make\ndebugging harder, as searching for variable origins becomes ambiguous (i.e. open\nto more than one interpretation).
The following follows best practices:
\n{pkgs, ... }: {\n environment.systemPackages = builtins.attrValues {\n inherit (pkgs)\n rustup\n evcxr\n nix-prefetch-git;\n };\n}\n{\n inherit (pkgs) rustup evcxr nix-prefetch-git;\n}\nis equivalent to:
\n{\n rustup = pkgs.rustup;\n evcxr = pkgs.evcxr;\n nix-prefetch-git = pkgs.nix-prefetch-git;\n}\nApplying builtins.attrValues produces:
[ pkgs.evcxr pkgs.nix-prefetch-git pkgs.rustup ]\nAs you can see only the values are included in the list, not the keys. This is\nmore explicit and declarative but can be more complicated, especially for a\nbeginner.
\nbuiltins.attrValues returns the values of all attributes in the given set,\nsorted by attribute name. The above expression turns into something like the\nfollowing avoiding bringing every attribute name from nixpkgs into scope.
A more straightforward example:
\nattrValues {c = 3; a = 1; b = 2;}\n=> [1 2 3]\nThis approach avoids unintended name clashes or confusion when debugging.
\nUpon looking into this a bit further, most people use the following format to\navoid the “anti-pattern” from using with pkgs;:
# utils.nix\n{ pkgs, ... }: {\n environment.systemPackages = [\n pkgs.rustup\n pkgs.evcxr\n pkgs.nix-prefetch-git\n ];\n}\nWhile the performance differences might be negligible on modern computers,\nadopting this best practice from the start is highly recommended. The above\napproach is more explicit, it’s clear exactly where each package is coming from.
\nIf maintaining strict scope control matters, use builtins.attrValues.
If readability and simplicity are more your priority, explicitly referencing\npkgs.<packageName> might be better. Now you can choose for yourself.
As we have seen throughout this chapter, modules are the building blocks of your\nNixOS system and are themselves often functions. There are a few different ways\nto use these modules to build your system. In the next chapter,\nNix Flakes Explained\nwe will learn about Nix Flakes as a more modern and comprehensive entrypoint for\nmanaging your entire system and its dependencies.
\nTo further deepen your understanding of NixOS Modules and the broader ecosystem\nof tools and best practices surrounding them, the following resources offer\nvaluable insights and information.
\nNixHour Writing NixOS modules\n– This example is from this video\ninfinisilModules
\n\n![\"trees3\"](\"https://saylesss88.github.io/images/trees3.cleaned.png\")
If you’re completely new, take a look at\nthis to get flakes on your\nsystem.
\nFor the Nix Flake man page type man nix3 flake and for a specific feature,\ntype something like man nix3 flake-lock.
Flakes replace stateful channels (which cause much confusion among novices) and\nintroduce a more intuitive and consistent CLI, making them a perfect opportunity\nto start using Nix. – Alexander Bantyev\nPractical Nix Flakes
\nThe “state” being remembered and updated by channels is the specific revision of\nthe Nixpkgs repository that your local Nix installation considers “current” for\na given channel. When this state changes on your machine, your builds diverge\nfrom others whose machines have a different, independently updated channel\nstate.
\nChannels are also constantly updated on the remote servers. So, “nixos-unstable”\ntoday refers to a different set of packages and versions than “nixos-unstable”\ndid yesterday or will tomorrow.
\nFlakes solve this by making the exact revision of nixpkgs (and other\ndependencies) an explicit input within your flake.nix file, pinned in the\nflake.lock. This means the state is explicitly defined in the configuration\nitself, not implicitly managed by a global system setting.
Evaluation time is notoriously slow on NixOS, the problem was that in the past\nNix evaluation wasn’t hermetic preventing effective evaluation caching. A .nix\nfile can import other Nix files or by looking them up in the Nix search path\n($NIX_PATH). This causes a cached result to be inconsistent unless every file\nis perfectly kept track of. Flakes solve this problem by ensuring fully hermetic\nevaluation.
“Hermetic” means that the output of an evaluation (the derivation itself)\ndepends only on the explicit inputs provided, not on anything external like\nenvironment variables or pulling in files only on your system. This is the\nproblem that Nix solves and the problem that flakes are built around.
\nNix flakes are independent components in the Nix ecosystem. They define\ntheir own dependencies (inputs) and what they produce (outputs), which can\ninclude packages, deployment configurations, or Nix functions for\nother flakes to use.
\nFlakes provide a standardized framework for building and managing software,\nmaking all project inputs explicit for greater reproducibility and\nself-containment.
\nAt its core, a flake is a source tree (like a Git repository) that contains a\nflake.nix file in its root directory. This file provides a standardized way to\naccess Nix artifacts such as packages and modules.
Flakes provide a standard way to write Nix expressions (and therefore packages)\nwhose dependencies are version-pinned in a lock file, improving reproducibility\nof Nix installations. – NixOS Wiki
\nThink of flake.nix as the central entry point of a flake. It not only defines\nwhat the flake produces but also declares its dependencies.
flake.nix: The Heart of a Flake
The flake.nix file is mandatory for any flake. It must contain an attribute\nset with at least one required attribute: outputs. It can also optionally\ninclude description and inputs.
Basic Structure:
\n{\n description = \"Package description\";\n inputs = { /* Dependencies go here */ };\n outputs = { /* What the flake produces */ };\n nixConfig = { /* Advanced configuration options */ };\n}\nI typically see nixConfig used for extra-substituters for cachix. This is a\ngeneral-purpose way to define Nix configuration options that apply when this\nflake is evaluated or built. It ties into your /etc/nix/nix.conf or\n~/.config/nix/nix.conf.
For example, create a directory and add a flake.nix with the following\ncontents, yes this is a complete flake.nix demonstrating outputs being the\nonly required attribute:
# flake.nix\n{\n outputs = _: { multiply = 2 * 2; };\n}\nNow evaluate it with:
\nnix eval .#multiply\n4\nIn the outputs = _: { ... }; line, the _ (underscore) is a placeholder\nargument. It represents the inputs that the outputs function could receive (like\ninputs, self, pkgs, etc.), but in this specific case, we’re not using any\nof them to define the multiply attribute. It’s a common convention in Nix to use\n_ 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\nflake.nix file in the directory where you’re running the command.
The # is used to select a specific attribute from the outputs of the\nflake. 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\noutput.
flake.lock auto-generated lock file
All flake inputs are pinned to specific revisions in a lockfile called\nflake.lock This file stores the revision info as JSON.
The flake.lock file ensures that Nix flakes have purely deterministic outputs.\nA flake.nix file without an accompanying flake.lock should be considered\nincomplete and a kind of proto-flake. Any Nix CLI command that is run against\nthe flake—like nix build, nix develop, or even nix flake show—generates a\nflake.lock for you.
Here’s an example section of a flake.lock file that pins Nixpkgs to a specific\nrevision:
$ cat flake.lock\n{\n \"nodes\": {\n \"nixpkgs\": {\n \"info\": {\n \"lastModified\": 1587398327,\n \"narHash\": \"sha256-mEKkeLgUrzAsdEaJ/1wdvYn0YZBAKEG3AN21koD2AgU=\"\n },\n \"locked\": {\n \"owner\": \"NixOS\",\n \"repo\": \"nixpkgs\",\n \"rev\": \"5272327b81ed355bbed5659b8d303cf2979b6953\",\n \"type\": \"github\"\n },\n \"original\": {\n \"owner\": \"NixOS\",\n \"ref\": \"nixos-20.03\",\n \"repo\": \"nixpkgs\",\n \"type\": \"github\"\n }\n },\n \"root\": {\n \"inputs\": {\n \"nixpkgs\": \"nixpkgs\"\n }\n }\n },\n \"root\": \"root\",\n \"version\": 5\n}\nAny future build of this flake will use the version of nixpkgs recorded in the\nlock file. If you add new inputs, they will be automatically added when you run\na 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:
\nnix flake lock --update-input nixpkgs\nnix build\nThe above command allows you to update individual inputs, and nix flake update\nwill update the whole lock file.
lib.genAttrs: A function, given the name of the attribute, returns the\nattribute’s value
Example:
\nnix repl\nnix-repl> :l <nixpkgs>\nnix-repl> lib.genAttrs [ \"boom\" \"bash\" ] (name: \"sonic\" + name)\nOutput:
\n{\n bash = \"sonicbash\";\n boom = \"sonicboom\";\n}\nYou will often see the following:
\nA common use for this with flakes is to have a list of different systems:
\n systems = [\n \"x86_64-linux\"\n \"aarch64-linux\"\n \"x86_64-darwin\"\n \"aarch64-darwin\"\n ];\nAnd use it to generate an attribute set for each listed system:
\neachSystem = lib.genAttrs systems;\nThe above command creates an attribute set by mapping over a list of system\nstrings. If you notice, you provide it a list (i.e. [ 1 2 3 ]) and the function\nreturns a set (i.e. { ... })
Why genAttrs is useful:
It lets you define attributes (like packages, checks, devShells) per\nsupported system in a DRY(don’t repeat yourself), structured way.
lib.mapAttrs: A function, given an attribute’s name and value, returns a new\nnameValuePair.
Example:
\nnix-repl> builtins.mapAttrs (name: value: name + \"-\" + value) { x = \"foo\"; y = \"bar\"; }\nOutput:
\n{\n x = \"x-foo\";\n y = \"y-bar\";\n}\npkgs.mkShell: is a specialized stdenv.mkDerivation that removes some\nrepetition when using it with nix-shell (or nix develop)
Example:
\n{ pkgs ? import <nixpkgs> {} }:\npkgs.mkShell {\n packages = [ pkgs.gnumake ];\n\n inputsFrom = [ pkgs.hello pkgs.gnutar ];\n\n shellHook = ''\n export DEBUG=1\n '';\n}\nIn a new directory create a flake.nix
# flake.nix\n{\n outputs = {\n self,\n nixpkgs,\n }: let\n pkgs = nixpkgs.legacyPackages.x86_64-linux;\n in {\n\n packages.x86_64-linux.default = pkgs.kakoune; # You could define a meta-package here\n\n devShells.x86_64-linux.default = pkgs.mkShell {\n packages = [\n pkgs.kakoune\n pkgs.git\n pkgs.ripgrep\n pkgs.fzf\n ];\n };\n };\n}\nmkShell 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\njust re-exports kakoune from nixpkgs. You could build your own apps here.
A development shell (devShells.x86_64-linux.default): This provides a\nconvenient environment where you have specific tools available without\ninstalling them globally on your system.
To use this flake you have a few options:
\nnix run will launch kakoune
nix develop will activate the development environment providing all of the\npkgs listed under mkShell.
Or more explicitly nix develop .#devShells.x86_64-linux.default, does the\nsame thing as the command above.
Flake references (flakerefs) are a way to specify the location of a flake.\nThey have two different formats:
\n\n\nAttribute set representation:
\n\n{\n type = \"github\";\n owner = \"NixOS\";\n repo = \"nixpkgs\";\n}\nor URL-like syntax:
\n\ngithub:NixOS/nixpkgs\nThese are used on the command line as a more convenient alternative to the\nattribute set representation. For instance, in the command
\n\nnix build github:NixOS/nixpkgs#hello\n\n
github:NixOS/nixpkgsis a flake reference (whilehellois an output\nattribute). They are also allowed in theinputsattribute of a flake, e.g.\ninputs.nixpkgs.url = \"github:NixOS/nixpkgs\";\nis equivalent to
\n\n\ninputs.nixpkgs = {\n type = \"github\";\n owner = \"NixOS\";\n repo = \"nixpkgs\";\n};\n
\n\n\n
nix flakeprovides subcommands for creating, modifying and querying Nix\nFlakes. Flakes are the unit for packaging Nix code in a reproducible and\ndiscoverable way. They can have dependencies on other flakes, making it\npossible to have multi-repository Nix projects.
— From\nnix.dev Reference Manual
\nThe main thing to note here is that nix flake is used to manage Nix flakes\nand that Flake commands are whitespace separated rather than hyphen -\nseparated.
Flakes do provide some advantages when it comes to discoverability of outputs.
\nFor Example, two helpful commands to inspect a flake are:
\nnix flake show\ncommand: Show the outputs provided by a flake.
\nnix flake check\ncommand: check whether the flake evaluates and run its tests.
\nAny Nix CLI command that is run against a flake – like nix build,\nnix develop, nix flake show – generate a flake.lock file for you.
flake.lock file ensures that all flake inputs are pinned to specific\nrevisions and that Flakes have purely deterministic outputs.Example:
\nnix shell nixpkgs#ponysay --command ponysay \"Flakes Rock!\"\nThis works because of the [flake registry] that maps symbolic identifiers like\nnixpkgs to actual locations such as https://github.com/NixOS/nixpkgs. So the\nfollowing are equivalent:
nix shell nixpkgs#ponysay --command ponysay Flakes Rock!\nnix shell github:NixOS/nixpkgs#ponysay --command ponysay Flakes Rock!\nTo override the nixpkgs registry with your own local copy you could:
nix registry add nixpkgs ~/src/local-nixpkgs\nAttribute sets are fundamental in Nix. They are simply collections of\nname-value pairs wrapped in curly braces {}.
let\n my_attrset = { foo = \"bar\"; };\nin\nmy_attrset.foo\n~ \"bar\"\nTop-Level Attributes of a Flake:
\nFlakes have specific top-level attributes that can be accessed directly\n(without dot notation). The most common ones are inputs, outputs, and\nnixConfig.
flake.nixinputs: Declaring Dependencies
The inputs attribute set specifies the other flakes that your current flake\ndepends on.
Each key in the inputs set is a name you choose for the dependency, and the\nvalue 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\nattribute (e.g., inputs.helix.packages).
See\nNix Flake inputs\nfor a flake inputs deep dive.
\nExample: This declares dependencies on the nixpkgs and import-cargo\nflakes:
inputs = {\n import-cargo.url = \"github:edolstra/import-cargo\";\n nixpkgs.url = \"nixpkgs\";\n};\nWhen Nix evaluates your flake, it fetches and evaluates each input. These\nevaluated inputs are then passed as an attribute set to the outputs function,\nwith the keys matching the names you gave them in the inputs set.
\nThe special input self is a reference to the outputs and the source tree of\nthe current flake itself.
outputs: Defining What Your Flake Provides
The outputs attribute defines what your flake makes available. This can\ninclude packages, NixOS modules, development environments (devShells) and\nother Nix derivations.
Flakes can output arbitrary Nix values. However, certain outputs have specific\nmeanings for Nix commands and must adhere to particular types (often\nderivations, as described in the\noutput schema).
\nYou can inspect the outputs of a flake using the command:
\nnix flake show\n\n\nThis command takes a flake URI and displays its outputs in a tree structure,\nshowing the attribute paths and their corresponding types.
\n
Understanding the outputs Function
Beginners often mistakenly think that self and nixpkgs within\noutputs = { self, nixpkgs, ... }: { ... } are the outputs themselves. Instead,\nthey are the input arguments (often called output arguments) to the outputs\nfunction.
The outputs function in flake.nix always takes a single argument, which is an\nattribute set. The syntax { self, nixpkgs, ... } is Nix’s way of destructuring\nthis single input attribute set to extract the values associated with the keys\nself and nixpkgs.
Flakes output your whole system configuration, packages, as well as Nix\nfunctions for use elsewhere.
\nFor example, the nixpkgs repository has its own flake.nix file that\noutputs many helper functions via the lib attribute.
For a deep dive into flake outputs, see\nNix Flake Outputs
\n\n\nThe
\nlibconvention The convention of usinglibto output functions is\nobserved not just by Nixpkgs but by many other Nix projects. You’re free,\nhowever, to output functions via whichever attribute you prefer. –\nZero to Nix Flakes
Some flake outputs are required to be system specific (i.e. “x86_64-linux” for\n(64-bit AMD/Intel Linux) including packages, development environments, and NixOS\nconfigurations)
\nVariadic Attributes (…) and @-patterns
\nThe ... syntax in the input arguments of the outputs function indicates\nvariadic attributes, meaning the input attribute set can contain more attributes\nthan just those explicitly listed (like lib and nixpkgs).
Example:
\nmul = { a, b, ... }: a * b;\nmul { a = 3; b = 4; c = 2; } # 'c' is an extra attribute\nHowever, you cannot directly access these extra attributes within the function\nbody unless you use the @-pattern:
\nmul = s@{ a, b, ... }: a b s.c; # 's' now refers to the entire input set\nmul { a = 3; b = 4; c = 2; } # Output: 24\n~ 24\nWhen used in the outputs function argument list (e.g.,\noutputs = { pkgs, ... } @ inputs), the @-pattern binds the entire input\nattribute set to a name (in this case, inputs) while also allowing you to\ndestructure specific attributes like pkgs.
What outputs = { pkgs, ... } @ inputs: { ... }; does:
Destructuring: It tries to extract the value associated with the key\npkgs from the input attribute set and binds it to the variable pkgs. The\n... allows for other keys in the input attribute set to be ignored during\nthis direct destructuring.
Binding the Entire Set: It binds the entire input attribute set to the\nvariable inputs.
\nflake.nix:{\ninputs.nixpkgs.url = \"github:NixOS/nixpkgs/nixos-unstable\";\ninputs.home-manager.url = \"github:nix-community/home-manager\";\n\noutputs = { self, nixpkgs, ... } @ attrs: { # A `packages` output for the x86_64-linux platform\npackages.x86_64-linux.hello = nixpkgs.legacyPackages.x86_64-linux.hello;\n\n # A `nixosConfigurations` output (for a NixOS system named \"fnord\")\n nixosConfigurations.fnord = nixpkgs.lib.nixosSystem {\n system = \"x86_64-linux\";\n specialArgs = attrs;\n modules = [ ./configuration.nix ];\n };\n\n};\n}\nPlatform Specificity in Outputs
\nFlakes ensure that their outputs are consistent across different evaluation\nenvironments. Therefore, any package-related output must explicitly specify the\ntarget platform (a combination of architecture and OS, x86_64-linux).
legacyPackages Explained
\nlegacyPackages is a way for flakes to interact with the traditional, less\nstructured package organization of nixpkgs. Instead of packages being directly\nat the top level (e.g., pkgs.hello), legacyPackages provides a\nplatform-aware way to access them within the flake’s structured output format\n(e.g., nixpkgs.legacyPackages.x86_64-linux.hello). It acts as a bridge between\nthe flake’s expected output structure and nixpkgs’s historical organization.
The Sole Argument of outputs
\nIt’s crucial to remember that the outputs function accepts only one argument,\nwhich is an attribute set. The { self, nixpkgs, ... } syntax is simply\ndestructuring that single input attribute set.
Outputs of the Flake (Return Value)
\nThe outputs of the flake refer to the attribute set that is returned by the\noutputs function. This attribute set can contain various named outputs like\npackages, nixosConfigurations, devShells, etc.
Imports: Including Other Nix Expressions
\nThe import function in Nix is used to evaluate the Nix expression found at a\nspecified path (usually a file or directory) and return its value.
Basic Usage: import ./path/to/file.nix
Passing Arguments During Import
\nimport <nixpkgs> {} is calling two functions, not one.
import <nixpkgs>: The first function callimport is a built-in Nix function. Its job is to load and evaluate a Nix\nexpression from a specified path.
<nixpkgs> is a flake reference. When you use import <nixpkgs>, Nix\nevaluates the default.nix file (or sometimes lib/default.nix) found at\nthat location.
The default.nix in nixpkgs evaluates to a function. This function is\ndesigned to be configurable, allowing you to pass arguments like system,\nconfig, etc. to customize how nixpkgs behaves and what packages it\nprovides.
So, import <nixpkgs> doesn’t give you the nixpkgs package set directly; it\ngives 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\nthat function and passing the attribute set as its single argument.
\nSo, the {} after import <nixpkgs> is not part of the import function\niteself. It’s the argument being passed to the function that import <nixpkgs>\njust returned.
You can also pass an attribute set as an argument to the Nix expression being\nimported:
\nlet\nmyHelpers = import ./lib/my-helpers.nix { pkgs = nixpkgs; };\nin\n# ... use myHelpers\nIn this case, the Nix expression in ./lib/my-helpers.nix is likely a function\nthat expects an argument (often named pkgs by convention):
# ./lib/my-helpers.nix\n\n{ pkgs }:\nlet\nmyPackage = pkgs.stdenv.mkDerivation {\nname = \"my-package\"; # ...\n};\nin\nmyPackage\nBy passing { pkgs = nixpkgs; } during the import, you are providing the\nnixpkgs value from your current flake.nix scope to the pkgs parameter expected\nby 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\nlooks for a file named default.nix within that directory. If found, Nix\nevaluates the expressions within default.nix as if you had specified its path\ndirectly in the import statement.
For some examples of more advanced outputs like devShells and checks, check\nout this blog post that I wrote:\nNix Flakes Tips and Tricks
In this chapter, we’ve explored Nix Flakes as a powerful and modern approach to\nmanaging Nix projects, from development environments to entire system\nconfigurations. We’ve seen how they provide structure, dependency management,\nand reproducibility through well-defined inputs and outputs. Flakes offer a\ncohesive way to organize your Nix code and share it with others.
\nAs we’ve worked with the flake.nix file, you’ve likely noticed its structure – a\ntop-level attribute set defining various outputs like devShells, packages,\nnixosConfigurations, and more. These top-level attributes are not arbitrary;\nthey follow certain conventions and play specific roles within the Flake\necosystem.
\nIn the next chapter,\nUnderstanding Top-Level Attributes\nwe will delve deeper into the meaning and purpose of these common top-level\nattributes. We’ll explore how they are structured, what kind of expressions they\ntypically contain, and how they contribute to the overall functionality and\norganization of your Nix Flakes. Understanding these attributes is key to\neffectively leveraging the full potential of Nix Flakes.
\n![\"FlakeHub\"](\"https://saylesss88.github.io/images/nixosnix.png\")
![\"coding2\"](\"https://saylesss88.github.io/images/coding2.png\")
In Nix, the concept of a package can refer to two things:
\nA collection of files and data that constitute a piece of software or an\nartifact.
\nA Nix expression that describes how to create such a collection. This\nexpression acts as a blueprint before the package exists in a tangible form.
\nThe process begins with writing a package definition using the Nix language.\nThis definition contains the necessary instructions and metadata about the\nsoftware you intend to “package.”
\nPackage Definition:
\nThis is essentially a function written in the Nix language.
\nNix language shares similarities with JSON but includes the crucial\naddition of functions.
\nIt acts as the blueprint for creating a package.
\nDerivation:
\nWhen the package definition is evaluated by Nix, it results in a\nderivation.
\nA derivation is a concrete and detailed build plan.
\nIt outlines the exact steps Nix needs to take: fetching source code,\nbuilding dependencies, compiling code, and ultimately producing the\ndesired output (the package).
\nRealization (Building the Package):
\nYou don’t get a pre-built “package” directly from the definition or the\nderivation.
\nThe package comes into being when Nix executes the derivation. This\nprocess is often referred to as “realizing” the derivation.
\nAnalogy: Think of a package definition as an architectural blueprint, the\nderivation as the detailed construction plan, and the realized package as the\nfinished building.
\nThe most basic derivation structure in Nix looks like this:
\n{ stdenv }:\n\nstdenv.mkDerivation { }\nThis is a function that expects an attribute set containing stdenv as its\nargument.
It then calls stdenv.mkDerivation (a function provided by stdenv) to\nproduce a derivation.
Currently, this derivation doesn’t specify any build steps or outputs.
\nFurther Reading:
\nHere’s a package definition for the classic “hello” program:
\n# hello.nix\n{\n stdenv,\n fetchzip,\n}:\n\nstdenv.mkDerivation {\n pname = \"hello\";\n version = \"2.12.1\";\n\n src = fetchzip {\n 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)\";\n sha256 = \"\";\n };\n}\nThis is a Nix function that takes stdenv and fetchzip as arguments.
\nIt uses stdenv.mkDerivation to define the build process for the “hello”\npackage.
pname: The package name.
version: The package version.
src: Specifies how to fetch the source code using fetchzip.
Handling Dependencies: Importing Nixpkgs
\nIf you try to build hello.nix directly with nix-build hello.nix, it will\nfail because stdenv and fetchzip are part of Nixpkgs, which isn’t included\nin this isolated file.
To make this package definition work, you need to pass the correct arguments\n(stdenv, fetchzip) to the function.
The recommended approach is to create a default.nix file in the same\ndirectory:
# default.nix\n\nlet\n nixpkgs = fetchTarball \"[https://github.com/NixOS/nixpkgs/tarball/nixos-24.05](https://github.com/NixOS/nixpkgs/tarball/nixos-24.05)\";\n pkgs = import nixpkgs { config = {}; overlays = []; };\nin\n{\n hello = pkgs.callPackage ./hello.nix { };\n}\nThis default.nix imports Nixpkgs.
It then uses pkgs.callPackage to call the function in hello.nix, passing\nthe necessary dependencies from Nixpkgs.
You can now build the “hello” package using: nix-build -A hello. The -A\nflag tells Nix to build the attribute named hello from the top-level\nexpression in default.nix.
Realizing the Derivation and Handling sha256
\nEvaluation vs. Realization: While “evaluate” refers to Nix processing an\nexpression, “realize” often specifically means building a derivation and\nproducing its output in the Nix store.
\nWhen you first run nix-build -A hello, it will likely fail due to a missing\nsha256 hash for the source file. Nix needs this hash for security and\nreproducibility. The error message will provide the correct sha256 value.
Example Error:
\n nix-build -A hello\n error: hash mismatch in fixed-output derivation '/nix/store/pd2kiyfa0c06giparlhd1k31bvllypbb-source.drv':\n specified: sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=\n got: sha256-1kJjhtlsAkpNB7f6tZEs+dbKd8z7KoNHyDHEJ0tmhnc=\n error: 1 dependencies of derivation '/nix/store/b4mjwlv73nmiqgkdabsdjc4zq9gnma1l-hello-2.12.1.drv' failed to build\nsha256 = \"\"; in hello.nix with the provided correct\nvalue: sha256 = \"1kJjhtlsAkpNB7f6tZEs+dbKd8z7KoNHyDHEJ0tmhnc=\";.Building and Running the Result
\nAfter updating the sha256, you can successfully build the package:
nix-build -A hello\nThe output will be a result symlink pointing to the built package in the Nix\nstore. You can then run the “hello” program:
\n./result/bin/hello\nHello, world!\nExample: The swaytools Package Definition
\nLet’s examine a more complex, real-world package definition from Nixpkgs:\nnixpkgs/pkgs/tools/wayland/swaytools/default.nix.
# default.nix\n{\n lib,\n setuptools,\n buildPythonApplication,\n fetchFromGitHub,\n slurp,\n}:\n\nbuildPythonApplication rec {\n pname = \"swaytools\";\n version = \"0.1.2\";\n\n format = \"pyproject\";\n\n src = fetchFromGitHub {\n owner = \"tmccombs\";\n repo = \"swaytools\";\n rev = version;\n sha256 = \"sha256-UoWK53B1DNmKwNLFwJW1ZEm9dwMOvQeO03+RoMl6M0Q=\";\n };\n\n nativeBuildInputs = [ setuptools ];\n\n propagatedBuildInputs = [ slurp ];\n\n meta = with lib; {\n homepage = \"https://github.com/tmccombs/swaytools\";\n description = \"Collection of simple tools for sway (and i3)\";\n license = licenses.gpl3Only;\n maintainers = with maintainers; [ atila ];\n platforms = platforms.linux;\n };\n}\n1 Function Structure:
\n{ lib, setuptools, buildPythonApplication, fetchFromGitHub, slurp }buildPythonApplication, a specialized helper for Python packages\n(similar to stdenv.mkDerivation but pre-configured for Python). The rec\nkeyword allows attributes within the derivation to refer to each other.pname and version define the package’s name and version.
The meta attribute provides standard package information like the homepage,\ndescription, license, maintainers, and supported platforms.
src attribute uses fetchFromGitHub to download the source code from\nthe specified repository and revision, along with its sha256 hash for\nverification.nativeBuildInputs: Lists tools required during the build process (e.g.,\nsetuptools for Python).
propagatedBuildInputs: Lists dependencies needed at runtime (e.g., slurp).
format = \"pyproject\"; indicates that the package uses a pyproject.toml\nfile for its Python build configuration.Integration within Nixpkgs
\nLocation: The swaytools definition resides in\npkgs/tools/wayland/swaytools/default.nix.
Top-Level Inclusion: It’s made available as a top-level package in\npkgs/top-level/all-packages.nix like this:
# all-packages.nix\nswaytools = python3Packages.callPackage ../tools/wayland/swaytools { };\npython3Packages.callPackage is used here because swaytools is a Python\npackage, and it ensures the necessary Python-related dependencies are correctly\npassed to the swaytools definition.In this chapter, we’ve journeyed through the fundamental concept of package\ndefinitions in Nix. We’ve seen how these Nix expressions act as blueprints,\nleading to the creation of derivations – the detailed plans for building\nsoftware. Finally, we touched upon the realization process where Nix executes\nthese derivations to produce tangible packages in the Nix store. Examining the\nsimple “hello” package and the more complex “swaytools” definition provided\npractical insights into the structure and key attributes involved in defining\nsoftware within the Nix ecosystem.
\nThe crucial step in this process, the transformation from a package definition\nto a concrete build plan, is embodied by the derivation. This detailed\nspecification outlines every step Nix needs to take to fetch sources, build\ndependencies, compile code, and produce the final package output. Understanding\nthe anatomy and lifecycle of a derivation is key to unlocking the full power and\nflexibility of Nix.
\nIn the next chapter,\nIntroduction to Nix Derivations,\nwe will delve deeper into the structure and components of these derivations. We\nwill explore the attributes that define a build process, how dependencies are\nmanaged within a derivation, and how Nix ensures the reproducibility and\nisolation of your software builds through this fundamental concept.
\n📚 Welcome to nix-book!
\n![\"Deploy](\"https://github.com/saylesss88/nix-book/actions/workflows/deploy-book.yml/badge.svg?branch=main\"){kind=icon}
🚀 If you find this guide helpful, please consider leaving a star ⭐ or\nsupporting the project by buying me a coffee ☕. Your support helps keep this\ncontent updated and freely available.
\nFollow nix-book with your preferred feed format for automatic notifications of\nnew content:
\nWelcome to my personal journey and guide through the Nix ecosystem! This “book”\naims to be a practical and understandable resource for anyone looking to dive\ninto Nix, NixOS, and Home Manager. Whether you’re just getting started or\nlooking to deepen your understanding, I hope you find this resource helpful!
\nI am a technologist with a wide range of interests that I’m passionate about,\nNixOS being one of them. I am also a privacy advocate trying to spread the word.
\n✨ What You’ll Find Here
\nThis book covers a range of topics to help you harness the power of Nix:
\nGetting Started with the Nix Ecosystem: Covers the Nix Language, Package\nManager, and a minimal Btrfs-Subvol install with Disko and Flakes, including\nBtrfs Impermanence.
\nHardening NixOS: A deep dive into security and hardening practices with NixOS
\nHardening Networking: Configure dnscrypt-proxy, firewalls, and more.
\nGnupg and gpg-agent on NixOS
\nWhonix KVM on NixOS
\nNixOS as a Guest VM with Secureblue as the Host
\nVersion Control with Git
\nVersion Control with JJ
\nUnderstanding Nix Functions: Explores practical Nix functions and their role\nwith NixOS Modules.
\nNixOS Modules Explained: A dedicated deep dive into NixOS’s modular\nconfiguration system.
\nNix Flakes Explained: Comprehensive coverage of Flake Inputs, Outputs,\nExamples, and extending Flakes with Custom Packages using Overlays.
\nUnderstanding Top-Level Attributes
\nPackage Definitions Explained
\nIntro to Nix Derivations: Including how builders and Autotools work.
\nComparing Flakes and Traditional Nix
\nDebugging and Tracing NixOS Modules
\nWorking with Nixpkgs Locally
\nFork, Clone, Contribute to Nixpkgs
\nNix Pull Requests
\nIntro to Nushell on NixOS
\nMy goal is to share my learnings and provide clear examples to make your Nix\nexperience smoother and more enjoyable.
\n📖 How to Read the Book
\nYou can read the book directly here on GitHub by navigating through the folders,\nor for a more comfortable reading experience, check out the dedicated website. I\ntried to write it in a way where you could jump to the chapter you’re interested\nin and still be able to follow along:
\nBrowse the book chapters here on\nGitHub.
\n🙏 Contributions & Feedback
\nThis book is a living document, and I welcome your input! If you find any\nerrors, have suggestions for improvements, or want to contribute a new section,\nplease feel free to:
\nReach out to me on Reddit u/saylesss88
Open an Issue: For bug reports, typos, or content suggestions.
\nSubmit a Pull Request: If you have code changes or want to add content\ndirectly.
\nYour feedback is invaluable and helps make this resource better for everyone!
\n⚖️ License
\nThis “Nix Book” is open-source and licensed under the Apache License 2.0.
\nThis means you are free to use, modify, and distribute this work, provided you\nadhere to the terms of the license. You can find the full text of the license in\nthe LICENSE file within this repository:
\nTo see a WIP book on privacy, checkout\nprivacy-book
\nView the\nApache License 2.0
\n" }, { "id": "https://saylesss88.github.io/Getting_Started_with_Nix_1.html", "url": "https://saylesss88.github.io/Getting_Started_with_Nix_1.html", "title": "Chapter1", "content_html": "![\"trees\"](\"https://saylesss88.github.io/images/trees1.cleaned.png\")
Welcome to nix-book, an introductory book about Nix. This book leans more\ntowards using Flakes but will contrast traditional Nix where beneficial.\nOriginally, this content started as a blog. I’m refining its flow to make it\nmore cohesive.
\nIn this chapter, I will touch on the different parts of the Nix ecosystem, give\na quick example of each and explain how they fit together.
\nThe code blocks have an option to hide code, where I find it reasonable I will\nhide the outputs of the expressions. Click the eye in the right corner of the\ncode block next to the copy clipboard.
\nExample hover over top-right corner of code block and click the eye to see\nhidden text:
\n![\"Buy](\"https://img.shields.io/badge/Buy%20Me%20a%20Coffee-%23FFDD00?style=for-the-badge&logo=buy-me-a-coffee&logoColor=black\"){kind=icon}
{\n attrset = { a = 2; b = 4; };\n~ hidden_set = { a = hidden; b = set; };\n}\n\n\n❗ If you’re new to Nix, think of it as a recipe book for software: you\ndescribe what you want (declarative), and Nix ensures it’s built the same way\nevery time (reproducible).
\n
The main reason to learn Nix is that it allows you to write declarative scripts\nfor reproducible software builds. Rather than mutate the global state and\ninstall packages to a global location such as /usr/bin Nix stores packages in\nthe Nix store, usually the directory /nix/store, where each package has its\nown unique subdirectory. This paradigm gives you some powerful features, such\nas:
Allowing multiple versions or variants of the same package at the same time.\nThis prevents “DLL hell” from different applications having dependencies on\ndifferent versions of the same package.
\nAtomic upgrades: Upgrading or uninstalling an application cannot break other\napplications and either succeed completely or fail completely preventing\npartial upgrades breaking your system. The nix store is immutable preventing\npackage management operations from overwriting other packages. They wouldn’t\noverwrite each other anyways because the hashing scheme ensures that new\nversions or repeat packages end up at different paths.
\nNix is designed to provide hermetic builds that aren’t affected by the\nenvironment, this helps you make sure that when packaging software that the\ndependencies are complete because they must be explicitly declared as inputs.\nWith other package managers it is more difficult to be sure that an\nenvironment variable or something in your $PATH isn’t affecting your build.
Let’s dive into the key characteristics of Nix:
\n| 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 |
\n\n❗ Important: In Nix, everything is an expression, there are no statements.
\n❗ Important: Values in Nix are immutable.
\n
The Nix Language is the foundation of the ecosystem and is used to write\nNix Expressions.
\nExample:
\n{ hello = \"world\"; }\n\"foo\" + \"bar\"\nWhile the Nix language provides the foundation for writing expressions, it is\nonly part of the ecosystem. These expressions become powerful when used within\nthe Nix Package Manager, which evaluates and realizes them into tangible\nsoftware builds and system configurations. This is where Nixpkgs and NixOS come\ninto play.
\nAt the heart of the Nix ecosystem is Nix Package Manager. This powerful\nengine is responsible for orchestrating the entire process: taking Nix\nexpressions (like package definitions and configuration modules),\nevaluating them into precise derivations, executing their build steps (the\nrealization phase), and meticulously managing the immutable Nix store.
\nA cornerstone of the Nix ecosystem is Nixpkgs. This vast collection\ncomprises tens of thousands of Nix expressions that describe how to build a wide\narray of software packages from source. Nixpkgs is more than just a package\nrepository—it also contains NixOS Modules, declarative configurations that\ndefine system behavior, ensuring a structured and reproducible environment.\nThese modules enable users to declaratively describe a Linux system, with each\nmodule contributing to the desired state of the overall system by leveraging\npackage definitions and derivations. This is how NixOS emerges: it is quite\nsimply the natural consequence of applying the Nix philosophy to building an\nentire Linux operating system.
\nWe will further expand our understanding of modules in\nChapter 3
\nThe following is an example of a NixOS module that is part of the nixpkgs\ncollection:
# nixpkgs/nixos/modules/programs/zmap.nix\n{\n pkgs,\n config,\n lib,\n ...\n}:\n\nlet\n cfg = config.programs.zmap;\nin\n{\n options.programs.zmap = {\n enable = lib.mkEnableOption \"ZMap, a network scanner designed for Internet-wide network surveys\";\n };\n\n config = lib.mkIf cfg.enable {\n environment.systemPackages = [ pkgs.zmap ];\n\n environment.etc.\"zmap/blacklist.conf\".source = \"${pkgs.zmap}/etc/zmap/blacklist.conf\";\n environment.etc.\"zmap/zmap.conf\".source = \"${pkgs.zmap}/etc/zmap.conf\";\n };\n}\nprograms.zmap.nix, demonstrates how NixOS configurations work.\nIt defines an enable option for the ZMap network scanner. If enabled by the\nuser in their system configuration, the module ensures the zmap package is\ninstalled and its default configuration files are placed in /etc, allowing\nZMap to be managed declaratively as part of the operating system.\nWhen nixpkgs is imported (e.g., in a NixOS configuration), the\nconfiguration options and settings defined by its modules (like\nprograms.zmap.nix) become available for use, typically accessed via dot\nnotation (e.g., config.programs.zmap.enable). This ability to make such a\nhuge set of modules and packages readily available without a significant\nperformance penalty is due to Nix’s lazy evaluation; only the\nexpressions required for a particular build or configuration are actually\nevaluated.
Most of the time you’ll simply search\nto see if the package is already included in nixpkgs and follow the\ninstructions there to get it on your system. It is good practice to first\nsearch for the options to see what\nconfigurable settings are available, and then proceed to search for the\npackage itself if you know it exists or if you need its specific package\ndefinition. When you look up the options for Zmap, programs.zmap.enable is\nall that is listed in this example.
Home Manager uses the same underlying Nix module system as NixOS, and when\nyou do something like home.packages = with pkgs; you are referring to the\nsame package derivations from nixpkgs as you would with\nenvironment.systemPackages. However, Home Manager’s own configuration\nmodules (e.g., for programs.zsh or git) are distinct and reside in the\nHome Manager repository, designed for user-specific configurations.
One of the main differentiating aspects of Nix, as opposed to traditional\npackage managers, is this concept that package builds are treated as pure\nfunctions. This functional paradigm ensures consistency and reproducibility,\nwhich are core tenets of the Nix philosophy.
\n![\"Nix](\"https://saylesss88.github.io/images/nix_isnot_nixos.png\")
Fig. X: Conceptual diagram illustrating the distinction between Nix and\nNixOS. Source: xeiaso, from the blog post “Making NixOS modules for fun and\n(hopefully) profit”, https://xeiaso.net/talks/asg-2023-nixos/.
\nNix expressions permeate the ecosystem—everything in Nix is an expression,\nincluding the next key components: package definitions and derivations.
\nPackage Definitions are specialized expressions that tell Nix how to build\nsoftware.
\nExample package definition:
\n# hello.nix\n {pkgs ? import <nixpkgs> {}}:\n pkgs.stdenv.mkDerivation {\n pname = \"hello\";\n version = \"2.12.1\";\n\n src = pkgs.fetchurl {\n url = \"https://ftp.gnu.org/gnu/hello/hello-2.12.1.tar.gz\";\n sha256 = \"086vqwk2wl8zfs47sq2xpjc9k066ilmb8z6dn0q6ymwjzlm196cd\";\n };\n\n nativeBuildInputs = [pkgs.autoconf pkgs.automake pkgs.gcc];\n\n configurePhase = ''\n ./configure --prefix=$out\n '';\n\n buildPhase = ''\n make\n '';\n\n installPhase = ''\n make install\n '';\n }\nNow when you run something like:
\nnix-instantiate hello.nix\nwarning: you did not specify '--add-root'; the result might be removed by the garbage collector\n/nix/store/p2hbg16a9kpqgx2nzcsq39wmnyxyq4jy-hello-2.12.1.drv\n.drv file (the derivation),\na precise JSON-like blueprint describing how the package will be built. It\ndoes not contain the built software itself.When you run:
\nnix-build hello.nix\n#...snip...\nshrinking RPATHs of ELF executables and libraries in /nix/store/53hqyw72dijq3wb5kc0ln04g681gk6cp-hello-2.12.1\nshrinking /nix/store/53hqyw72dijq3wb5kc0ln04g681gk6cp-hello-2.12.1/bin/hello\nchecking for references to /build/ in /nix/store/53hqyw72dijq3wb5kc0ln04g681gk6cp-hello-2.12.1...\ngzipping man pages under /nix/store/53hqyw72dijq3wb5kc0ln04g681gk6cp-hello-2.12.1/share/man/\npatching script interpreter paths in /nix/store/53hqyw72dijq3wb5kc0ln04g681gk6cp-hello-2.12.1\nstripping (with command strip and flags -S -p) in /nix/store/53hqyw72dijq3wb5kc0ln04g681gk6cp-hello-2.12.1/bin\n/nix/store/53hqyw72dijq3wb5kc0ln04g681gk6cp-hello-2.12.1\nNix realizes the derivation by actually executing the build steps, fetching\nsources, compiling (if needed), and producing the final result (typically\nstored in e.g. /nix/store/53hqyw72dijq3wb5kc0ln04g681gk6cp-hello-2.12.1)
nix-build also creates a symlink named result in your current directory,\npointing to the final build output in the Nix store.
./result/bin/hello\nHello, world!\nresult/bin/hello points to the executable inside the output of the\nderivation.The derivation describes how the package is built, but does not\ninclude the final binaries.
To say that another way, the derivation is not the executable. The executable is\none of the derivations outputs. When Nix “realizes” a derivation, it executes\nthose build instructions, and the result is the actual built software, which\ngets placed into its own unique path in the Nix store.
A single derivation can produce multiple outputs. The executable is typically\npart 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\nbuilding the hello derivation and running the following on the store path:
nix show-derivation /nix/store/9na8mwp5zaprikqaqw78v6cdn1rxac7i-hello-2.12.1\n{\n \"/nix/store/871398c9cbskmzy6bvfnynr8yrlh7nk0-hello-2.12.1.drv\": {\n \"args\": [\n \"-e\",\n \"/nix/store/v6x3cs394jgqfbi0a42pam708flxaphh-default-builder.sh\"\n ],\n \"builder\": \"/nix/store/1jzhbwq5rjjaqa75z88ws2b424vh7m53-bash-5.2p32/bin/bash\",\n \"env\": {\n \"__structuredAttrs\": \"\",\n \"buildInputs\": \"\",\n \"builder\": \"/nix/store/1jzhbwq5rjjaqa75z88ws2b424vh7m53-bash-5.2p32/bin/bash\",\n \"cmakeFlags\": \"\",\n \"configureFlags\": \"\",\n \"depsBuildBuild\": \"\",\n \"depsBuildBuildPropagated\": \"\",\n \"depsBuildTarget\": \"\",\n \"depsBuildTargetPropagated\": \"\",\n \"depsHostHost\": \"\",\n \"depsHostHostPropagated\": \"\",\n \"depsTargetTarget\": \"\",\n \"depsTargetTargetPropagated\": \"\",\n \"doCheck\": \"\",\n \"doInstallCheck\": \"\",\n \"mesonFlags\": \"\",\n \"name\": \"hello-2.12.1\",\n \"nativeBuildInputs\": \"\",\n \"out\": \"/nix/store/9na8mwp5zaprikqaqw78v6cdn1rxac7i-hello-2.12.1\",\n \"outputs\": \"out\",\n \"patches\": \"\",\n \"pname\": \"hello\",\n \"propagatedBuildInputs\": \"\",\n \"propagatedNativeBuildInputs\": \"\",\n \"src\": \"/nix/store/pa10z4ngm0g83kx9mssrqzz30s84vq7k-hello-2.12.1.tar.gz\",\n \"stdenv\": \"/nix/store/80wijs24wjp619zmrasrh805bax02xjm-stdenv-linux\",\n \"strictDeps\": \"\",\n \"system\": \"x86_64-linux\",\n \"version\": \"2.12.1\"\n },\n# ... snip ...\nIn this introductory chapter, we’ve laid the groundwork for understanding the\npowerful Nix ecosystem. We explored how the Nix Language forms the declarative\nbedrock, enabling us to define desired system states and software builds as\nexpressions. You saw how the Nix Package Manager orchestrates this process,\ntransforming those expressions into precise derivations during the evaluation\nphase, and then faithfully “realizing” them into reproducible, isolated\nartifacts within the immutable /nix/store.
We also introduced the vast Nixpkgs collection, which provides tens of thousands\nof package definitions and forms the foundation for NixOS — a fully declarative\noperating system built on these principles—and even user-level configurations\nlike those managed by Home Manager. This unique functional approach, with its\nemphasis on immutability and lazy evaluation, is what enables Nix’s promises of\nconsistency, atomic upgrades, and truly hermetic builds, fundamentally changing\nhow we think about software and system management.
\nThe Nix Language
\nNow that you have a foundational understanding of the Nix ecosystem and its core\noperational cycle, we are ready to delve deeper into the building blocks of Nix\nexpressions. In the next chapter,\nUnderstanding Nix Functions,\nwe will peel back the layers and explore the intricacies of function arguments,\nadvanced patterns, scope, and how functions play a crucial role in building more\nsophisticated Nix expressions and derivations.
\nHere are some resources that are helpful for getting started:
\nNix Core Ecosystem, Nix, NixOS,\nNix Lang, Nixpkgs are all distinctly different; related things which can be\nconfusing for beginners this article explains them.
\nnixpkgs: Vast package repository
\nNix Reference Manual Data Types\nThe main Data Types you’ll come across in the Nix ecosystem
\nnix.dev: Has become the top respected source of\ninformation in my opinion. There is a lot of great stuff in here, and they\nactively update the information.
\n`````nix repl\n(let a = \"2\"; in # Let expressions are a way to create variables\na + a + builtins.toString \"4\")\n`````\n