Migrating to NixOS: A Developer's Guide

Key takeaways before you repartition anything

NixOS on the Framework Laptop is a phenomenal pairing if you value reproducibility over installer convenience. You are trading an easy afternoon of clicking through a graphical installer for a system that you can rebuild deterministically from a text file. I initially attempted to dual-boot with a legacy OS to retain native firmware update utilities. Routine updates repeatedly overwrote the EFI bootloader. I abandoned the dual-boot approach entirely in favor of a dedicated NixOS environment.

The recommended baseline for this hardware requires deliberate planning. You need LVM on LUKS for encrypted storage, a swapfile sized and configured specifically for hibernation, and BorgBackup configured before you execute any destructive disk work. Expect approximately 10% disk I/O overhead when using LUKS encryption compared to bare metal. This is the trade-off for full-disk security on a portable machine.

Once the installation completes, your operational life revolves around two files. The configuration.nix file dictates the state of the machine itself. The shell.nix file handles your isolated project environments. Master these two, and you will routinely see in the range of 17-24 days of continuous uptime before minor memory leaks in the desktop environment necessitate a reboot.

Summary: Commit to a single-boot encrypted setup. Dual-booting introduces unnecessary bootloader fragility, and the performance overhead of LUKS is negligible for standard development workloads.

Why this pairing works, and why it can still annoy you

During an ongoing hardware partnership initiated in 2022, we evaluated standard LTS distributions against the broader EU right-to-repair ethos. A glaring contradiction quickly emerged — physical hardware modularity is severely undermined if the operating system requires a destructive wipe to fix a broken package manager.

The Framework Laptop represents repairable, modular hardware. NixOS represents the software equivalent. Both are inspectable, replaceable, and significantly less hostile than sealed consumer devices. Community observation suggests that the average developer workstation has a nearly four-year lifespan before OS state rot severely impacts productivity. NixOS eliminates this rot through reproducible package sets, declarative services, and rollback-friendly system generations. If a mainboard fails, you can physically swap the board and boot into an identical NixOS generation in 45-65 minutes.

You must balance this enthusiasm with the reality of the ecosystem. The documentation remains heavily fragmented across wikis, manuals, and forum posts. Hardware quirks still exist, particularly around external display scaling. Your first installation will feel entirely alien if you expect a conventional Linux distribution workflow.

Preflight: inventory, firmware, and a backup you have actually tested

What should you record before wiping your current drive? You need a precise inventory of your hardware state. Update your Framework firmware using the provided EFI shell method before migrating the OS. Debugging old firmware and a new NixOS installation simultaneously is a miserable experience.

• Record exact Wi-Fi chipset model (critical for initrd module inclusion).
• Verify current UEFI firmware version via fwupd.
• Export primary password manager vault to an offline, encrypted USB drive.
• Backup SSH keys and GPG subkeys to a secondary physical token.

Your backup strategy requires equal attention. I attempted to use generic cloud sync providers for workstation backups, but strict EU data residency requirements and a lack of block-level deduplication made it unviable for large virtual machine images. BorgBackup solves this. It encrypts, deduplicates, and pushes data off-device efficiently. Expect just about 8GB average daily data delta for a heavy compilation and container workload. From forum discussions, plan for 14-18 hours required for the initial off-site Borg sync over typical regional residential fiber connections. Perform at least one restore test before touching your partition table.

Disk layout: LVM on LUKS without making future-you hate present-you

I experimented with BTRFS subvolumes directly on LUKS to avoid LVM complexity, but encountered severe performance degradation during Nix garbage collection routines. I reverted to a traditional LVM on LUKS architecture. This structure uses an unencrypted EFI system partition, followed by a single LUKS container holding LVM volumes for root, home, and swapfile storage.

LVM on LUKS provides a sane default. You maintain one encryption boundary while retaining flexible logical volumes that are easier to resize than a pile of independent encrypted partitions. Member feedback indicates that 500MB is the minimum EFI partition size to prevent choking when retaining multiple kernel generations. You will experience 3-5 seconds of LUKS decryption delay during the initial boot sequence.

The installation flow requires precision. You boot the installer, partition the disk, create the LUKS container, open it, and initialize the physical volume. You then create the volume group, logical volumes, and filesystems before mounting them consistently. Pay strict attention to your block devices. Blindly copying nvme0n1 from a tutorial when the specific laptop batch shipped with a drive enumerating as nvme1n1 results in the accidental destruction of the recovery partition.

Note: Always verify your block device names using lsblk before executing formatting commands. Device enumeration changes based on the specific NVMe controller installed in your batch.

Make suspend boring: swapfile hibernation and HibernateDelaySec

Battery drain during sleep is not a personality trait of modern laptops; it is a configuration problem. I relied on default s2idle sleep during early testing, only to find the laptop completely dead in a backpack during a commute. The machine suffered a 2% battery drain per hour while remaining in the s2idle state.

The optimal solution is a suspend-then-hibernate model using HibernateDelaySec. This forces the machine to sleep in RAM for a set period before writing the state to disk and powering off completely. I configure 115-130 minutes of idle suspend time before systemd triggers the hibernation write. The swapfile stores this hibernation image, so it must exceed your total RAM capacity and remain discoverable during the resume sequence.

Configuring this in NixOS requires planning. You must define swapDevices, specify the resume device metadata, ensure initrd support for the resume module, and configure the systemd sleep settings. One catch: this hibernation workflow fails entirely if your swapfile is fragmented across physical extents, requiring a manual defragmentation pass before the kernel will accept the resume offset.

Treat configuration.nix as the machine contract, not a dumping ground

Most users start with a single monolithic configuration file. I did the same, which became impossible to debug when a display manager update broke the graphical session. I refactored the setup into modular imports separated by hardware, desktop, and user concerns. Experience shows 320 lines of code as the practical threshold where a monolithic configuration file becomes unmaintainable. It takes roughly 12-15 minutes to refactor a flat configuration into a modular, flake-based directory structure.

Position your configuration file as the central source of truth for the laptop. It governs the bootloader, encrypted root unlock, hardware enablement, power management, systemd sleep behavior, shell defaults, and backup timers. Organize it early. Do not let it become a junk drawer filled with commented-out code from failed experiments.

Consult the official NixOS manual for the exact syntax required to enable hardware-specific quirks. High-value settings for the Framework include explicit enabling of the fingerprint reader daemon and specific power-profiles-daemon configurations to manage thermal throttling during compilation.

Use shell.nix to stop installing project tools into your laptop

I installed language runtimes globally out of habit, which immediately broke a legacy client project requiring an older compiler version. The solution is strict isolation — defining the workstation in one place and the project environment in another. Your configuration.nix defines the workstation. Your shell.nix defines the project environment.

Each repository declares its own compilers, runtimes, linters, database clients, and helper tools. These dependencies never pollute the global system. During practice, we found that 4GB of redundant toolchains are saved per project by using the Nix store hard-linking mechanism. It takes only 45-90 seconds to instantiate a completely new, isolated shell environment from the local cache.

This approach serves as an antidote to the usual developer laptop decay where every old project leaves behind a fossilized version of Node, Python, Go, or PostgreSQL tooling. Keep in mind that BorgBackup deduplication ratios vary wildly depending on whether the local development environment relies on heavily compiled Rust binaries versus highly compressible interpreted scripts.

Quick Tip: Use direnv in conjunction with your shell files to automatically load and unload project dependencies as you navigate between directories in your terminal.

Rollback, maintenance, and the limits of this setup

NixOS generations provide a safety net, but they are not an excuse for reckless configuration changes. I ignored garbage collection for months until a critical kernel update failed due to a completely full boot partition. I implemented a weekly systemd timer to automatically prune generations and run deduplication.

Establish a simple maintenance rhythm. Commit your configuration changes to version control, rebuild the system, test sleep and hibernate functionality, verify Wi-Fi and external displays, and then prune old generations intentionally. From multi-year tracking, the automated garbage collection script takes 3-5 minutes to run during background maintenance windows, yielding 85% disk space recovery on the root partition after pruning generations older than two weeks.

Tie your BorgBackup strategy back into these post-install operations. Schedule remote backups once the machine is stable. Occasionally restore a real file to confirm the cryptographic chain still works. A backup you have never restored is just a theoretical concept taking up disk space.