Handbook: Installing

About the installation

You will build a NixOS system by hand and add SnapOS packs to it. At the end the whole computer is described by two files in /etc/snapos:

The installer builds the full SnapOS for you. Here you decide everything: a desktop or none, which programs, which packs. You will need the internet during the whole installation.

The minimal USB

Download the minimal image for your computer on the Downloads page and flash it with balenaEtcher. Start the computer from the USB stick (often F12, F9 or Esc while it turns on). You land in a terminal, logged in as nixos; commands that change the system need sudo.

The minimal USB is the NixOS minimal ISO with Snappy, the snapos commands and this handbook's address.

Configuring the network

A network cable works by itself. For Wi-Fi:

nmtui

Choose Activate a connection, pick your network and type its password. Then check:

ping -c 2 nixos.org

Preparing the disks

UEFI or BIOS?

Computers from the last ten years start with UEFI; older ones with BIOS. Check:

ls /sys/firmware/efi

If the folder exists, it is UEFI. This handbook shows UEFI; the BIOS differences are in a note at each step.

Finding the disk

lsblk

Your disk is the disk of the right size: sda, vda or nvme0n1. Below it is /dev/sda.

Partitions

sudo parted -s /dev/sda -- mklabel gpt \
  mkpart ESP fat32 1MiB 512MiB set 1 esp on \
  mkpart root ext4 512MiB 100%

Swap (optional)

Instead of a swap partition you can use compressed memory: zramSwap.enable = true; in configuration.nix.

Formatting and mounting

sudo mkfs.fat -F 32 -n boot /dev/sda1
sudo mkfs.ext4 -L nixos /dev/sda2
sudo mount /dev/sda2 /mnt
sudo mkdir -p /mnt/boot
sudo mount -o umask=077 /dev/sda1 /mnt/boot

The labels (boot, nixos) name the partitions, so you recognize them later in lsblk -f. On NVMe the partitions are /dev/nvme0n1p1 and /dev/nvme0n1p2.

The hardware file

sudo snapos-generate-config --root /mnt

This writes /mnt/etc/snapos/hardware-configuration.nix (your disks and the drivers your computer needs) and a first configuration.nix, which you replace in the next steps. You will not need to edit the hardware file.

Writing flake.nix

sudo nano /mnt/etc/snapos/flake.nix

# /etc/snapos/flake.nix: where your system comes from.
# nixpkgs gives every program; snapos gives the SnapOS packs.
{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-26.05";
    snapos.url = "https://github.com/snapos-distro/snapos-updates/releases/latest/download/snapos-source.tar.gz";
    snapos.inputs.nixpkgs.follows = "nixpkgs";
  };

  outputs = { nixpkgs, snapos, ... }: {
    # "mypc" is the name you use with snapos-install and snapos-rebuild
    nixosConfigurations.mypc = nixpkgs.lib.nixosSystem {
      system = "x86_64-linux";            # "aarch64-linux" on an ARM64 computer
      modules = [ snapos.nixosModules.packs ./configuration.nix ];
    };
  };
}

nixpkgs is the collection with every program, at the NixOS 26.05 line. snapos brings the packs from the newest release in snapos-updates, the same place every SnapOS updates from, and follows makes them use the same nixpkgs as you. mypc is the name of your system: you use it when installing and rebuilding. Save with Ctrl+O, close with Ctrl+X.

Writing configuration.nix

Replace the generated file with your own. The whole file is at the end of this chapter; the next sections explain each part.

sudo nano /mnt/etc/snapos/configuration.nix

The boot loader

boot.loader.systemd-boot.enable = true;
boot.loader.efi.canTouchEfiVariables = true;

Name, network, users and language

networking.hostName = "mypc";
networking.networkmanager.enable = true;
time.timeZone = "America/Sao_Paulo";
i18n.defaultLocale = "pt_BR.UTF-8";
console.keyMap = "br-abnt2";
users.users.ana = {
  isNormalUser = true;
  extraGroups = [ "wheel" "networkmanager" ];   # wheel: may use sudo
};

Choosing a desktop

Any desktop NixOS has works. A few examples (pick one, or none for a terminal-only system):

Set the keyboard of the desktop too: services.xserver.xkb.layout = "br";

Programs

Programs are names from nixpkgs (search them on search.nixos.org):

# snapos:packages:begin
environment.systemPackages = with pkgs; [
  firefox
  git
  nano
];
# snapos:packages:end

The two comment lines let snapos add and snapos remove edit the list for you later.

Adding the SnapOS packs

One line per pack (all of them are described in The SnapOS packs):

snapos.packs.theme.enable = true;      # the red look and Snappy
snapos.packs.commands.enable = true;   # snapos find, add, rollback...
snapos.packs.snapguard.enable = true;  # the antivirus
snapos.packs.debian.enable = true;     # .deb programs
snapos.packs.updater.enable = true;    # updates of the packs

The whole file

# /etc/snapos/configuration.nix: your whole system, written by you.
{ config, pkgs, ... }:

{
  imports = [ ./hardware-configuration.nix ];

  # Starting the computer (UEFI)
  boot.loader.systemd-boot.enable = true;
  boot.loader.efi.canTouchEfiVariables = true;

  # Name, network, time and language
  networking.hostName = "mypc";
  networking.networkmanager.enable = true;
  time.timeZone = "America/Sao_Paulo";
  i18n.defaultLocale = "pt_BR.UTF-8";
  console.keyMap = "br-abnt2";

  # You
  users.users.ana = {
    isNormalUser = true;
    extraGroups = [ "wheel" "networkmanager" ];
  };

  # A desktop: Xfce here (or none at all: delete these four lines)
  services.xserver.enable = true;
  services.xserver.desktopManager.xfce.enable = true;
  services.xserver.displayManager.lightdm.enable = true;
  services.xserver.xkb.layout = "br";

  # Programs (snapos add and snapos remove edit this list for you)
  # snapos:packages:begin
  environment.systemPackages = with pkgs; [
    firefox
    git
    nano
  ];
  # snapos:packages:end

  # The SnapOS packs you want
  snapos.packs.theme.enable = true;      # the red look and Snappy
  snapos.packs.commands.enable = true;   # snapos find, add, rollback...
  snapos.packs.snapguard.enable = true;  # the antivirus
  snapos.packs.debian.enable = true;     # .deb programs
  snapos.packs.updater.enable = true;    # updates of the packs

  nix.settings.experimental-features = [ "nix-command" "flakes" ];
  system.stateVersion = "26.05";
}

Installing

sudo snapos-install --flake /mnt/etc/snapos#mypc

NixOS downloads and builds everything the files describe; this takes a while. At the end it asks a password for root. Then give your user a password:

sudo snapos-enter --root /mnt -c 'passwd ana'

Finishing

reboot

Remove the USB stick. Your system starts, and its description lives in /etc/snapos. Next: working with your system.