Skip to content

Installation

Jump to bottom
Justin Schaaf edited this page Apr 12, 2025 · 5 revisions

New NixOS Install

Follow the steps below when installing NixOS for the first time to initialize the system with this repo's config.

These instructions are adapted from the NixOS Manual.

Note

Most commands here must be run as root. You can elevate your session with sudo -i or sudo su -

  1. Obtain the installer and enter a live boot environment according to the NixOS manual.

    • You can get away with using the minimal image. If you're more comfortable with a graphical environment, feel free to go for the GNOME or Plasma versions.

  2. Format the internal drive. If the config you're installing supports zero-touch (currently only Lasagna/TV), you can skip this.

    I prefer my systems to have a 512 MB FAT32 boot partition (if using UEFI), a Linux Swap partition equal to or 4GB greater than the computer's RAM size, and the rest of the disk being a Btrfs root partition.

    [!WARNING] This will destroy ALL data on the drive. If you have an existing OS to dual boot or data on the drive you would like to keep, please format the drive according to your needs.

    Encrypted storage

    This setup requires you to enter a password to decrypt the disk upon booting the system. While I want the encryption key stored on the system's TPM chip, I don't want to sign NixOS's Linux Kernel package myself.

    Refer to the instructions here. Note that your swap partition will not be encrypted with this method.

    Unencrypted storage

    [!NOTE] These instructions assume your main drive is /dev/sda. You can also safely ignore parted's informational message about needing to update /etc/fstab.

    1. Create the disk's partition table. This decides how the drive will be laid out. Be sure to replace [TABLE] with the choice for your system:

      • For UEFI systems, create a gpt table.
      • For BIOS systems, create a msdos (MBR) table.
      parted /dev/sda -- mklabel [TABLE]

    2. Add the root partition. This will fill the disk except for 512 MB at the start of the drive and your swap size at the end (using 16GB as an example).

      [!TIP] For BIOS systems, repolace 512MB with 1MB as you will not need a boot partition.

      parted /dev/sda -- mkpart root btrfs 512MB -16GB

    3. Add the swap partition. I recommend matching your system's RAM and adding an extra 4GB, stopping at 16GB of swap space max.

      parted /dev/sda -- mkpart swap linux-swap -16GB 100%

    4. For UEFI systems, add the boot partition.

      parted /dev/sda -- mkpart ESP fat32 1MB 512MB
      parted /dev/sda -- set 3 esp on

    5. Format each of the partitions. This actually initializes the file systems on each partition we allocated above. For BIOS systems, skip the mkfs.fat command.

      mkfs.btrfs -L nixos /dev/sda1
      mkswap -L swap /dev/sda2
      mkfs.fat -F 32 -n boot /dev/sda3

    6. Mount the root file system at /mnt. This should be /dev/sda1.

      mount /dev/sda1 /mnt

    7. For UEFI systems, mount the boot partition at /mnt/boot.

      mkdir -p /mnt/boot
      mount -o umask=077 /dev/sda3 /mnt/boot

    8. Activate the swap partition.

      swapon /dev/sda2

  1. Do the install. Replace [SYSTEM] with the hostname of the config you would like to install, choosing from the list here.

    • If you had to manually format the disk, remove the -z option at the end.
    • If you want a local copy of the config at /etc/nixos, add -l /mnt/etc/nixos/ to the command.
    nix --experimental-features "nix-command flakes" run github:justinhschaaf/nixos-config#jsinstall -- -z [SYSTEM]

  2. Reboot the system and sign into the account for the installed configuration, likely sysadmin or justinhs. Be sure to change the password with passwd.

    shutdown now -r

Existing NixOS System

  1. Install the new config. Replace [SYSTEM] with the hostname of the config you would like to install, choosing from the list here.

    • If you want a local copy of the config at /etc/nixos, add -l /etc/nixos/ to the command. Backup your current /etc/nixos config before doing so, as the install script will override your config. 
    sudo nix --experimental-features "nix-command flakes" run github:justinhschaaf/nixos-config#jsinstall -- -r [SYSTEM]

  2. Reboot the system.

    shutdown now -r

Troubleshooting

Hardware config

Use the command below to generate a hardware config for your system:

nix-shell -p nixos-install-tools --run 'sudo nixos-generate-config --show-hardware-config'

If running from the live boot environment, after mounting your disks:

sudo nixos-generate-config --root /mnt --show-hardware-config

Change root

If you can't sign into the system, you can enter the system from the installer and run the passwd command to update your password.

  1. Obtain the installer and enter a live boot environment
  2. Mount your system's partitions as described in step 2 of a new install.
  3. Run nixos-enter.

Consult the wiki for more details on this process.

Incorrect permissions on /mnt

If you used a different method to partition the system's disk, you may encounter an error message like the one below:

path /mnt should have permissions 755, but had permissions 700. Consider running 'chmod o+rx /mnt'.

DO NOT RUN CHMOD. This error message means the partition you're installing NixOS to is not flagged as root. It also causes a bunch of nasty permissions issues after install to the point where most applications won't run whatsoever (including Hyprland). Try one of the following:

  • If using parted, make sure you set the brtfs partition as type root.
  • If using a graphical disk partition tool such as GParted or GNOME Disks, I'm honestly not certain how to flag the partition properly. I'd recommend using the workaround below.
  • Install NixOS using the graphical (Calamares) installer. Either let the installer partition the disk as it wants, or if manually partitioning the disk, edit the flags on your main partition and select root (the installer won't let you proceed without it).

Terminal just crashes/GNOME resets when installing

If your terminal emulator or all open applications close when in the live boot environment, your system likely ran out of memory while running the installer. The disk partition likely completed successfully, so try resuming nixos-install manually.

nixos-install --flake github:justinhschaaf/nixos-config#[SYSTEM] --no-root-passwd

If you're installing from a local config, use path:/mnt/etc/nixos/#[SYSTEM] for the flake argument instead (assuming your final config will be at /etc/nixos).

Clone this wiki locally