this document describes how to achieve a specific gentoo system installation and configuration. the rationale of each specific choice is out of scope here. this isn't a guide. further, there isn't even consistency between sections. and it's currently in progress. you have been warned.
aspects of this gentoo linux system:
ACCEPT_KEYWORDS="~amd64") branch.further notes about gentoo configuration here.
this document was written and updated in 2025+2026 alongside the installation of gentoo on my thinkpad t420, thinkpad x9 15", thinkpad z16 gen 1.
this isn't meant to be a general purpose guide. it doesn't explain kernel configuration, or portage configuration beyond what's required to install.
if you're installing gentoo yourself, you should primarily be using the official handbook.
i'm using arch install media because i'm used to it and genfstab is already present.
$ dd if=./archlinux-2026.05.01-x86_64.iso of=/dev/sdz bs=1M && sync
the "(cached)" option in the boot menu. this loads the installation media into ram for faster access and removal of the installation media drive during install.
connect to wifi. set root password (for install media) and enable sshd to connect from another system if you'd rather perform the installation remotely from a complete system.
gentoo install media:
$ nmtui
$ passwd
$ /etc/init.d/sshd start
$ ip addr | grep inet | grep wlp3s0
inet 10.19.91.222/24 brd 10.19.91.255 scope global dynamic noprefixroute wlp3s0
arch install media:
$ iwctl
[iwd]# device list
[iwd]# station wlan0 scan
[iwd]# station wlan0 get-networks
[iwd]# station wlan0 connect $SSID
[iwd]# quit
$ passwd
$ ip addr | grep inet | grep wlp3s0
inet 10.19.91.222/24 brd 10.19.91.255 scope global dynamic noprefixroute wlp3s0
from the machine you want to connect from:
$ ssh root@10.19.91.222
swap /dev/sdz with the name of the disk you're installing on.
shred the partition data:
$ lsblk
$ shred -n 1 -s 16k /dev/sdz
create the partition table:
$ cfdisk /dev/sdz
one example:
$ fdisk -l /dev/sdz
Disk /dev/sda: 465.76 GiB, 500107862016 bytes, 976773168 sectors
Disk model: Samsung SSD 860
Units: sectors of 1 * 512 = 512 bytes
Sector size (logical/physical): 512 bytes / 512 bytes
I/O size (minimum/optimal): 512 bytes / 512 bytes
Disklabel type: gpt
Disk identifier: 06352CF3-DA32-4E93-89C4-2057B4675B5B
Device Start End Sectors Size Type
/dev/sdz1 2048 2099199 2097152 1G EFI System
/dev/sdz2 2099200 976773119 974673920 464.8G Linux filesystem
a separate example:
$ fdisk -l /dev/nvme0n1
Disk /dev/nvme0n1: 931.51 GiB, 1000204886016 bytes, 1953525168 sectors
Disk model: KINGSTON SNV2S1000G
Units: sectors of 1 * 512 = 512 bytes
Sector size (logical/physical): 512 bytes / 512 bytes
I/O size (minimum/optimal): 512 bytes / 512 bytes
Disklabel type: gpt
Disk identifier: AA99F539-A01E-454F-A18D-1F0D3DF373CC
Device Start End Sectors Size Type
/dev/nvme0n1p1 2048 2099199 2097152 1G EFI System
/dev/nvme0n1p2 2099200 1953523711 1951424512 930.5G Linux filesystem
/dev/sdz2)$ cryptsetup benchmark
$ cryptsetup luksFormat /dev/sdz2
$ cryptsetup luksOpen /dev/sdz2 cryptroot
$ mkfs.btrfs /dev/mapper/cryptroot
$ mkdir -p /mnt/gentoo
$ mount -o noatime /dev/mapper/cryptroot /mnt/gentoo
noatime is specified because it's a permanent option i want,
and we'll later be generating our systems /etc/fstab file using the mounted configuration.
keep in mind:
however you mount the disks now under /mnt/gentoo will be how we tell the system to mount the disks on each boot.
/dev/sdz1)$ mkfs.vfat -F 32 /dev/sdz1
$ mkdir -p /mnt/gentoo/boot
$ mount /dev/sdz1 /mnt/gentoo/boot
$ cd /mnt/gentoo
time should be correct before https attempted:
$ date
$ chronyd -q
use links to download the stage3 tarball:
$ pacman -Sy links
$ links https://www.gentoo.org/downloads/mirrors/
from the handbook:
On the mirror list, select a mirror close by. Usually HTTP mirrors suffice, but other protocols are available as well. Move to the releases/amd64/autobuilds/ directory. There all available stage files are displayed (they might be stored within subdirectories named after the individual sub-architectures). Select one and press d to download.
or, for example:
$ pacman -Sy curl
$ curl -O https://mirror.csclub.uwaterloo.ca/gentoo-distfiles/releases/amd64/autobuilds/current-stage3-amd64-desktop-systemd/stage3-amd64-desktop-systemd-20260510T170106Z.tar.xz
verify and validate (TODO)
then
$ tar xpvf stage3-*.tar.xz --xattrs-include='*.*' --numeric-owner -C /mnt/gentoo
these are important decisions!
$ cat /mnt/gentoo/etc/portage/make.conf
COMMON_FLAGS="-march=native -O2 -pipe"
CFLAGS="${COMMON_FLAGS}"
CXXFLAGS="${COMMON_FLAGS}"
FCFLAGS="${COMMON_FLAGS}"
FFLAGS="${COMMON_FLAGS}"
RUSTFLAGS="${RUSTFLAGS} -C target-cpu=native"
LC_MESSAGES=C.UTF-8
ACCEPT_KEYWORDS="~amd64"
ACCEPT_LICENSE="-* @FREE @BINARY-REDISTRIBUTABLE "
MAKEOPTS="-j4 -l11"
EMERGE_DEFAULT_OPTS="--jobs 4"
highly recommend reading the handbook section for this, as it varies heavy from system to system.
generate your fstab file:
$ genfstab -U /mnt/gentoo/ >> /mnt/gentoo/etc/fstab
copy dns info in for the chroot
$ cp --dereference /etc/resolv.conf /mnt/gentoo/etc/
chroot:
$ arch-chroot /mnt/gentoo
install gentoo ebuild repo snapshot:
$ emerge-webrsync
install packages we'll use to complete the installation:
$ emerge --ask --verbose --oneshot \
app-portage/mirrorselect app-editors/vim app-portage/cpuid2cpuflags
select nearby mirrors:
$ mirrorselect -i -o >> /etc/portage/make.conf
select profile:
$ eselect profile list | grep plasma | grep systemd
[8] default/linux/amd64/23.0/desktop/plasma/systemd (stable)
$ eselect profile set 8
$ echo "*/* $(cpuid2cpuflags)" > /etc/portage/package.use/cpu-flags
$ echo '*/* VIDEO_CARDS: intel' > /etc/portage/package.use/video-cards
you'll need this to build gentoo-kernel:
$ echo 'sys-kernel/installkernel grub dracut' >> /etc/portage/package.use/installkernel
otherwise, when trying to emerge:
# required by sys-kernel/gentoo-kernel-7.0.6::gentoo[-generic-uki,initramfs]
# required by virtual/dist-kernel-7.0.6::gentoo
>=sys-kernel/installkernel-68 dracut
$ emerge --ask --verbose --oneshot \
sys-kernel/gentoo-kernel sys-kernel/installkernel \
sys-kernel/linux-firmware sys-firmware/sof-firmware \
sys-kernel/dracut sys-boot/grub sys-fs/cryptsetup sys-fs/btrfs-progs
at the time of writing the full disk encryption from scratch gentoo wiki page appears insufficient for dracut on systemd configurations. but i'm unsure, so the differences are documented here. in any case it should be referenced in case anything changed.
in this section we will be dealing with the uuid of the luks encrypted partition to be opened, and the uuid of the decrypted volume to be mounted. there are non-uuid id ways of doing this, but i don't trust the non-uuid labels to remain the same.
$ lsblk -o name,uuid
NAME UUID
nvme0n1
├─nvme0n1p1 173C-1599
└─nvme0n1p2 007ba2bd-499d-4d0d-b8ba-4307fd2d450d
└─cryptroot d5f12268-b87a-4d3a-a82a-711e526e40b1
/dev/nvme0n1p2 is the luks encrypted partition to be opened:
$ blkid -s UUID -o value /dev/nvme0n1p2
007ba2bd-499d-4d0d-b8ba-4307fd2d450d
/dev/mapper/cryptroot is the decrypted volume to be mounted.
$ blkid -s UUID -o value /dev/mapper/cryptroot
d5f12268-b87a-4d3a-a82a-711e526e40b1
rebuild systemd with cryptsetup:
$ echo 'sys-apps/systemd cryptsetup' >> /etc/portage/package.use/systemd
$ emerge --ask --newuse sys-apps/systemd
$ mkdir -p /etc/dracut.conf.d
$ vim /etc/dracut.conf.d/luks.conf
$ cat /etc/dracut.conf.d/luks.conf
add_dracutmodules+=" systemd-cryptsetup "
hostonly="yes"
The hostonly="yes" makes dracut only include hardware/modules needed for your system, keeping the initramfs smaller.
the gentoo wiki has this instead, probably for non-systemd systems?:
$ cat /etc/dracut.conf.d/luks.conf
add_dracutmodules+=" crypt dm rootfs-block "
kernel_cmdline+=" rd.luks.uuid=007ba2bd-499d-4d0d-b8ba-4307fd2d450d root=UUID=d5f12268-b87a-4d3a-a82a-711e526e40b1 "
generate a new initramfs image:
$ dracut --force --hostonly
if it exits without error, should be good.
$ grep GRUB_CMDLINE_LINUX /etc/default/grub
GRUB_CMDLINE_LINUX="rd.luks.uuid=007ba2bd-499d-4d0d-b8ba-4307fd2d450d root=UUID=d5f12268-b87a-4d3a-a82a-711e526e40b1"
$ grub-install --efi-directory=/boot
$ grub-mkconfig -o /boot/grub/grub.cfg
you probably want to: create a user, set a timezone, configure ntpd, sshd etc. since this can all be done after system installation, i've separated it into a gentoo configuration page.
at this point you could reboot your newly installed system, but you'd have no means to login, and possible no means to connect to the network...
create a root password:
$ passwd
install network manager, or whatnot:
$ emerge --ask net-misc/networkmanager
give the computer a hostname:
$ echo 'beast' >> /etc/hostname
$ exit # the chroot
$ umount /mnt/gentoo/boot
$ umount /mnt/gentoo
$ shutdown -h now
remove the install media, boot into your new gentoo system!