Opinionated Gentoo Install Guide

Date: 2026-02-20

An opinionated gentoo installation guide derived from the official handbook. Uses a BTRFS filesystem.

Installation

This installation guide is created in such a way that it must be followed section by section. Sections that come later may depend on previous sections to function properly.

Sections labelled (OPTIONAL) can be skipped.

Start by booting into the minimal gentoo installer.

Make sure you choose the UEFI option in the boot menu. You can check if you are booted with UEFI by verifying that /sys/firmware/efi exists.

Partitioning

fdisk /dev/sdX
g
n
⏎
⏎
+2G
n
⏎
⏎
⏎
t
1
1
t
2
23
w

Apply Filesystem

mkfs.vfat -F 32 /dev/sdX1
mkfs.btrfs /dev/sdX2

Mount Root Partition

Mounting must be done in the order specified.

mkdir -p /mnt/gentoo
mount /dev/sdX2 /mnt/gentoo

Create BTRFS Subvolumes

cd /mnt/gentoo
btrfs subvolume create @
btrfs subvolume create @home
btrfs subvolume create @swap

cd ~
umount /mnt/gentoo
mount -o subvol=@ /dev/sdX2 /mnt/gentoo/

mkdir /mnt/gentoo/home
mount -o subvol=@home /dev/sdX2 /mnt/gentoo/home

mkdir /mnt/gentoo/swap
mount -o subvol=@swap /dev/sdX2 /mnt/gentoo/swap

Mount Boot Partition

mkdir -p /mnt/gentoo/efi
mount /dev/sdX1 /mnt/gentoo/efi

Download Stage 3 Tarball

cd /mnt/gentoo
date <- ENSURE THE DATE/TIME IS CORRECT
links https://www.gentoo.org/downloads/mirrors/
/downloads
⏎
/stage 3 openrc
⏎
⏎
⏎
q
⏎

Install Stage 3 Tarball

tar xpvf stage3-*.tar.xz --xattrs-include='*.*' --numeric-owner -C /mnt/gentoo

Configure /etc/portage/make.conf

vim /mnt/gentoo/etc/portage/make.conf

Most required USE flags are already set by the selected profile, they aren't initially required unless neccesary. You can check with emerge --info | grep \^USE .

/mnt/gentoo/etc/portage/make.conf

COMMON_FLAGS="-O2 -pipe -march=native"
RUSTFLAGS="${RUSTFLAGS} -C target-cpu=native"

CFLAGS="${COMMON_FLAGS}"
CXXFLAGS="${COMMON_FLAGS}"
FCFLAGS="${COMMON_FLAGS}"
FFLAGS="${COMMON_FLAGS}"

MAKEOPTS="-jX"

USE="X elogind
-wifi -bluetooth -branding -doc -nls -test"

LC_MESSAGES=C.UTF-8

USE="-bluetooth -wifi" are good choices for a virtual machine.

The lto and pgo use flags can increase performance marginally but take insane amounts of time to compile. Only practical if doing overnight compilations.

Copy DNS Info

cp --dereference /etc/resolv.conf /mnt/gentoo/etc/

Chroot

Ignore the 'no such device' error!

arch-chroot /mnt/gentoo

Configuring Portage

emerge-webrsync

Select Profile

This list can change, ensure you are selecting the stable non-systemd minimal profile. Check the current list with eselect profile list | head -n 15 .

eselect profile set 1

Install Vim

emerge app-editors/vim
eselect editor set X <- Set to Vim, use 'eselect editor list' to find the index.

Update @world Set

This can take a while (10+ minutes), not ideal for a quick install but I'm unsure how it affects packages like firmware that are emerged later on in the guide. It is best to do it. Updating @world also allows me to continue using Vim.

emerge --verbose --update --deep --changed-use @world

Timezone

Switch to tty2 and run arch-chroot /mnt/gentoo.

cd
ln -sf ../usr/share/zoneinfo/Europe/London /etc/localtime

Configure Locacle

vim /etc/locale.gen

-- /etc/locale.gen --
en_GB.UTF-8 <- UNCOMMENT

locale-gen
eselect locale list
eselect locale set X <- SET en_GB.UTF-8
env-update && source /etc/profile && export PS1="(chroot) ${PS1}"

Create Swap File

touch /swap/swapfile
chmod 600 /swap/swapfile
chattr +C /swap/swapfile
dd if=/dev/zero of=/swap/swapfile bs=1M count=4096
mkswap /swap/swapfile
swapon /swap/swapfile

Hostname

echo HOSTNAME > /etc/hostname

vim /etc/hosts

-- /etc/hosts --
127.0.0.1 CHANGE-ME <- Add this additional line.
127.0.0.1 localhost
::1       localhost

Colemak & Windows Key Fix

To enable colemak on boot and to stop the windows key from switching VTs we can do the following:

vim /etc/conf.d/keymaps

-- /etc/conf.d/keymaps --
keymap="en-latin9"
windowkeys="NO"

rc-update add keymaps default

Accounts

NAME is a placeholder for the user you want to create.

passwd <- Set root password.
useradd -m -G users,wheel,audio,video -s /bin/bash NAME
passwd NAME

Populate /etc/fstab

Wait until the @world emerge has completed in tty1, but continue from tty2. Ensure /dev/sdX1 is mounted to /efi and /dev/sdX2 is mounted to / .

emerge sys-fs/genfstab
> /etc/fstab <- This will truncate the file to zero length (clear it).
genfstab -U / >> /etc/fstab

vim /etc/fstab

Change all instances (including efi partition) of relatime to noatime and add compress=zstd:1 to / and /home.

Network

IFACE is a placeholder for the interface name on your machine.

emerge net-misc/dhcpcd
emerge --noreplace net-misc/netifrc
cd /etc/init.d

Repeat these steps for every interface you want to use, including ethernet:

ifconfig <- Take note of the interface name.
echo 'config_IFACE="dhcp"' >> /etc/conf.d/net
ln -s net.lo net.IFACE

Add for main connection (ethernet/wifi):

rc-update add net.IFACE default

For WiFi:

emerge net-wireless/wpa_supplicant
vim /etc/wpa_supplicant/wpa_supplicant.conf

ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=wheel

update_config=1

ap_scan=1

network={
    id_str="" <- Optional name.
    ssid=""
    psk=""
    priority=5
}

Elogind & Dbus

emerge sys-auth/elogind sys-apps/dbus
rc-update add elogind boot && rc-update add dbus default

Doas

emerge app-admin/doas
echo 'permit nopass :wheel' >> /etc/doas.conf

Install Firmware/Microcode

There are some additional CPU dependant options, see the wiki for up-to-date information.

echo 'sys-kernel/linux-firmware @BINARY-REDISTRIBUTABLE' | tee -a /etc/portage/package.license
emerge sys-kernel/linux-firmware sys-firmware/sof-firmware

# Additionally for Intel CPUs.
echo 'sys-firmware/intel-microcode @BINARY-REDISTRIBUTABLE' | 
tee -a /etc/portage/package.license
emerge sys-firmware/intel-microcode

Install Kernel

This can take around 45 minutes.

echo 'sys-kernel/installkernel dracut' >> /etc/portage/package.use/installkernel
emerge sys-kernel/installkernel sys-kernel/gentoo-kernel-bin

Bootloader (GRUB)

echo 'GRUB_PLATFORMS="efi-64"' >> /etc/portage/make.conf
emerge sys-boot/grub
grub-install --efi-directory=/efi
vim /etc/default/grub

/etc/default/grub

GRUB_CMDLINE_LINUX="rootflags=subvol=@"

grub-mkconfig -o /boot/grub/grub.cfg

Reboot

exit
umount -l /mnt/gentoo
reboot

Tailscale

emerge net-vpn/tailscale
rc-update add tailscale default
rc-service tailscale start
tailscale up --ssh

Post-Installation Setup

Utilities:

doas emerge app-portage/gentoolkit app-misc/fastfetch sys-fs/btrfs-progs net-misc/croc app-eselect/eselect-repository

Environment:

doas emerge x11-base/xorg-server x11-wm/i3 x11-misc/i3status x11-misc/dmenu x11-terms/alacritty

Programs:

sys-apps/flatpak

Rofi

doas emerge x11-misc/rofi
rofi -show drun -theme dmenu

Flatpak

doas emerge sys-apps/flatpak
flatpak remote-add --user --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo

flatpak install --user flathub org.mozilla.firefox
flatpak install --user flathub org.vinegarhq.Sober

Keyd (Caps to Ctrl/Esc)

This does not work in games, gamescope could counter this.

  doas eselect repository enable guru && doas emaint sync -r guru
echo "app-misc/keyd ~amd64" | doas tee -a /etc/portage/package.accept_keywords/keyd
doas emerge app-misc/keyd
doas rc-update add keyd default && doas rc-service keyd start

doas tee /etc/keyd/default.conf <<EOF
include layouts/colemak

[ids]
*

[global]
default_layout = colemak

[main]
capslock = overload(control, esc)

[colemak:layout]
EOF

doas keyd reload