Guix Installation

Last Updated: October 24, 2025 • Tags: Guix

A guide for installing Guix with my configs, BTRFS and LUKS2 with argon2id.

Preliminaries

Note: If the hardware requires nonguix in any way use a nonguix installation media.

Prepare a USB thumb drive using dd bs=4M if=_ of=_ conv=fsync oflag=direct
Boot the Guix installation media
Switch to a Shell with Ctrl+Alt+F3
Set the keyboard layout using loadkeys neo
Set a root password using passwd root
Start an SSH daemon using herd start ssh-daemon
Connect from an existing system and proceed from there

Partition the Disk

Note: This still uses gptfdisk, however, recent version of util-linux’s fdisk also support GPT partitions.

The setup will use two GPT partitions:

An unencrypted EFI system partition, which gets mounted to /boot
- It would also be possible to create a separate partition for /boot
- Using an unencrypted boot requires a custom bootloader configuration
An encrypted LUKS partition for the root with BTRFS subvolumes

No swap space will be created. The partitions are created using gdisk

$ gdisk /dev/nvme1n1
GPT fdisk (gdisk) version 1.0.9

Partition table scan:
  MBR: protective
  BSD: not present
  APM: not present
  GPT: present

Command (? for help): n
Partition number (1-128, default 1): 1
First sector (34-976773134, default = 2048) or {+-}size{KMGTP}:
Last sector (2048-976773134, default = 976773119) or {+-}size{KMGTP}: +2GB
Warning! Unable to generate a proper UUID! Creating an improper one as a last
resort! Windows 7 may crash if you save this partition table!
Current type is 8300 (Linux filesystem)
Hex code or GUID (L to show codes, Enter = 8300): ef00
Changed type of partition to 'EFI system partition'

Command (? for help): n
Partition number (2-128, default 2):
First sector (34-976773134, default = 4196352) or {+-}size{KMGTP}:
Last sector (4196352-976773134, default = 976773119) or {+-}size{KMGTP}:
Hex code or GUID (L to show codes, Enter = 8300): 8309
Changed type of partition to 'Linux LUKS'

The result should roughly looks as follows:

Number  Start (sector)    End (sector)  Size       Code  Name
   1            2048         4196351   2.0 GiB     EF00  EFI system partition
   2         4196352       976773119   463.8 GiB   8309  Linux LUKS

If that’s the case, writhe the partition table and quit the partitioning tool.

Creating Filesystems

The EFI system partition must be formated using FAT32:

# mkfs.fat -F 32 /dev/nvme1n1p1

Afterwards, we can create the encrypted LUKS2 container

# cryptsetup luksFormat --type luks2 /dev/nvme1n1p2

Before we can create our root file system, we need to open the container again:

# cryptsetup open --type luks2 /dev/nvme1n1p2 root

Now we can create our BTRFS root file system:

# mkfs.btrfs /dev/mapper/root

Mounting the Filesystems

The file system need to be mounted at a mountpoint, where are going to use /mnt for that.

# mount /dev/mapper/root /mnt
# mkdir /mnt/boot
# mount /dev/nvme1n1p1 /mnt/boot

Before creating any additional files at the mountpoints, it’s worthwhile to consider BTRFS subvolumes.

Creating Subvolumes

Subvolumes are great because they allow additional mount options (such as noexec to be passed). Normally I create the following subvolumes:

# btrfs subvolume create /mnt/home
# btrfs subvolume create /mnt/etc
# btrfs subvolume create /mnt/var
# btrfs subvolume create /mnt/var/log
# btrfs subvolume create /mnt/var/tmp

Installing Guix

First, we need to obtain a Guix configuration. I keep my configuration in a separate repository which I clone and adjust at this point:

# guix package -i git vim
# GUIX_PROFILE="/root/.guix-profile" && . "$GUIX_PROFILE/etc/profile"
# git clone https://git.8pit.net/guix-config.git /root/guix-config
# cd /root/guix-config
# vim etc/config.scm

Regarding the configuration pay attention to the following details:

The target of the bootloader-configuration must refer to the mounted EFI system partition by path (i.e., /boot).
For the EFI system partition, also update the UUID in the file-systems section for mounting it after boot.
The source of the mapped-devices configuration should refer to the LUKS2 partition by UUID (see the blkid output).

We now need to ensure that all packages we add from now on also end up on /mnt for that run:

# herd start cow-store /mnt

Afterwards, we can finally install Guix to /mnt using:

# guix time-machine -C /root/guix-config/channels.scm -- system init /root/guix-config/etc/config.scm /mnt

Recommendation: If you are installing over SSH, consider running this in a tmux session.

Rebooting

If system init completed successfully unmount and reboot:

# umount /mnt/boot /mnt
# sync
# reboot