Gentoo Linux Installation Guide (Basic)

Table of Contents

Article Overview
#

This is Part 1 of the Gentoo Linux Installation Guide series: Basic Installation.

Series Navigation:

Basic Installation (This Article): Installing Gentoo base system from scratch
Desktop Configuration: Graphics drivers, desktop environment, input methods

Recommended Reading Path:

As needed: Basic Installation (Sections 0-11) → Desktop Configuration (Section 12)

About This Guide
#

This guide is a full Gentoo install walkthrough with plenty of links back to the official Wiki and source docs at every step, so you can dig into the why behind each command.

It's a guided reference, not a copy-paste recipe. Part of using Gentoo is learning to read the Wiki yourself and work problems out from there — search engines and AI tools help, but the official handbook and the links in this article are the canonical source.

If you have questions or find any issues while reading, feel free to reach out through:

Gentoo Community: Gentoo Forums | IRC: #gentoo @ Libera.Chat

Highly recommend following the official handbook:

Last verified: 25 November 2025

What is Gentoo?
#

Gentoo is a source-based Linux distribution. You compile most software from source, which means:

Hardware-tuned binaries — built with flags that match your CPU and hardware
Full control — you choose what's in the system and what isn't
Learning by doing — you understand Linux better because you built it
Time cost — expect a 3–6 hour initial install
Linux basics required — comfort with the command line helps

Who it's for

People who want to learn Linux from the inside out
Users who care about tuning the system to their hardware
Anyone who enjoys building their own setup

Who it's not for

People who just want a system that works in 20 minutes — try Ubuntu or Fedora first
People who don't want to spend time configuring a system

Core Concepts Overview (Click to Expand)

Before starting the installation, let's understand some core concepts:

Stage3 (Wiki) A minimal Gentoo base system tarball. It contains the basic toolchain (compiler, libraries, etc.) needed to build a complete system. You'll extract it to your hard drive as the "foundation" of your new system.

Portage (Wiki) Gentoo's package manager. Rather than installing pre-compiled packages, it downloads source code, compiles it according to your configuration, and installs it. The core command is emerge.

USE Flags (Wiki) Feature switches that control software functionality. For example, USE="bluetooth" enables Bluetooth support in all software that supports it during compilation. This is the core of Gentoo customization.

Profile (Wiki) A default system configuration template. For example, the desktop/plasma/systemd profile automatically enables default USE flags suitable for a KDE Plasma desktop.

Emerge (Wiki) Portage's command-line tool. Common commands:

emerge --ask <package> - Install software
emerge --sync - Sync software repository
emerge -avuDN @world - Update the entire system

Installation Time Estimate (Click to Expand)

Step	Estimated Time
Prepare installation media	10-15 min
Disk partitioning & formatting	15-30 min
Download & extract Stage3	5-10 min
Configure Portage & Profile	15-20 min
Compile kernel (most time-consuming)	30 min - 2 hours
Install system tools	20-40 min
Configure bootloader	10-15 min
Install desktop environment (optional)	1-3 hours
Total	3-6 hours (depending on hardware)

Tip

Using pre-compiled kernels and binary packages can significantly reduce time, but at the cost of some customization.

Disk Space Requirements & Pre-Installation Checklist (Click to Expand)

Disk Space Requirements
#

Minimal installation: 10 GB (no desktop environment)
Recommended: 30 GB (lightweight desktop)
Comfortable: 80 GB+ (full desktop + compilation cache)

Pre-Installation Checklist
#

All important data has been backed up
An 8GB+ USB flash drive is prepared
Stable network connection (wired is best)
Sufficient time reserved (recommend a full half-day)
Some Linux command-line experience
Another device available to reference documentation (or use a GUI LiveCD)

Guide Overview
#

This guide will walk you through installing Gentoo Linux on an x86_64 UEFI platform.

This guide will teach you:

Installing the Gentoo base system from scratch (partitioning, Stage3, kernel, bootloader)
Configuring Portage and optimizing compilation parameters (make.conf, USE flags, CPU flags)
Optional configuration (LUKS root-filesystem encryption)
Desktop Configuration covers desktop environments, locale configuration, fonts, the Fcitx5 input method, Flatpak, and system maintenance

Important Notice

Please disable Secure Boot first Before starting the installation, enter your BIOS settings and temporarily disable Secure Boot. Enabling Secure Boot may prevent the installation media from booting, or prevent the installed system from booting. You can re-enable Secure Boot after installation is complete and the system is successfully booting.

Back up all important data! This guide involves disk partitioning operations. Please back up all important data before starting!

0. Prepare Installation Media
#

Reference: Gentoo Handbook: AMD64 - Choosing the Installation Media

0.1 Download Gentoo ISO
#

Obtain the download link from the downloads page

Note

The commands below read the current ISO filename from Gentoo's current-install-amd64-minimal directory.

Download the Minimal ISO:

ISO_DIR=https://distfiles.gentoo.org/releases/amd64/autobuilds/current-install-amd64-minimal
ISO=$(wget -qO- "$ISO_DIR/latest-install-amd64-minimal.txt" | grep -E '^install-amd64-minimal-[0-9]{8}T[0-9]{6}Z[.]iso ' | cut -d' ' -f1)
test -n "$ISO" || exit 1
wget "$ISO_DIR/$ISO" "$ISO_DIR/$ISO.asc"

Beginners: Use the LiveGUI USB Image

If you want to use a browser during installation or connect to Wi-Fi more easily, choose the LiveGUI USB Image from the official downloads page.

The official Gentoo LiveGUI image includes:

KDE Plasma desktop environment
Browser and Wi-Fi support
Multiple terminal support
Login credentials: live / live / live

Verify signature (recommended):

# Import the Gentoo release signing key.
# Preferred: use the local copy that ships with Live media or sec-keys/openpgp-keys-gentoo-release
gpg --import /usr/share/openpgp-keys/gentoo-release.asc
# Fallback: autobuilds are signed by the automated weekly release key; without a local key, retrieve it from keys.gentoo.org:
#   gpg --keyserver hkps://keys.gentoo.org --recv-keys 13EBBDBEDE7A12775DFDB1BABB572E0E2D182910

# Verify the ISO signature
gpg --verify "$ISO.asc" "$ISO"

0.2 Create Bootable USB
#

Linux:

sudo dd if="$ISO" of=/dev/sdX bs=4M status=progress oflag=sync
# Replace sdX with your USB device name (e.g., /dev/sdb)

Windows: Use Rufus → Select ISO → Choose DD mode when writing.

1. Enter Live Environment and Connect to Network
#

Reference: Gentoo Handbook: AMD64 - Configuring the Network

Why is this step needed?

Gentoo's installation process relies entirely on the network to download source packages (Stage3) and the software repository (Portage). Configuring the network in the Live environment is the first step of installation.

The current Gentoo Live media boots with NetworkManager enabled, so wired connections usually come up automatically via DHCP and Wi-Fi can be configured with a single TUI.

Easiest path — NetworkManager (Live media default):

nmtui   # interactive: pick "Activate a connection" or "Edit a connection"

Confirm with:

ping -c3 gentoo.org

If you prefer manual configuration (or the Live media is the older Minimal ISO without NetworkManager), use the sections below.

1.1 Wired Network (manual)
#

ip link              # View network interface names (e.g. eno1, eth0)
dhcpcd eno1          # Enable DHCP on the wired interface
ping -c3 gentoo.org  # Test network connectivity

1.2 Wireless Network (manual)
#

Interactive helper:

net-setup

wpa_supplicant (fill in your interface, SSID, password):

wpa_passphrase "SSID" "PASSWORD" | tee /etc/wpa_supplicant/wpa_supplicant.conf
wpa_supplicant -B -i wlp0s20f3 -c /etc/wpa_supplicant/wpa_supplicant.conf
dhcpcd wlp0s20f3

Note

If WPA3 is unstable, try falling back to WPA2.

Advanced Settings: Enable SSH for Remote Access (Click to Expand)

passwd                      # Set root password (required for remote login)
rc-service sshd start       # Start SSH service
rc-update add sshd default  # Enable SSH on boot (optional in Live environment)
ip a | grep inet            # View current IP address
# From another device: ssh root@<IP>

2. Plan Disk Partitioning
#

Reference: Gentoo Handbook: AMD64 - Preparing the Disks

Why is this step needed?

We need to allocate dedicated storage space for the Linux system. UEFI systems typically need an ESP partition (boot) and a root partition (system). Proper planning makes future maintenance easier.

What is the EFI System Partition (ESP)?
#

When installing Gentoo on a system that boots via UEFI (rather than BIOS), creating an EFI System Partition (ESP) is required. The ESP must be a FAT variant (sometimes displayed as vfat on Linux systems). The official UEFI specification states that UEFI firmware recognizes FAT12, 16, or 32 file systems, but FAT32 is recommended.

Warning If the ESP is not formatted with a FAT variant, the system's UEFI firmware will not find the bootloader (or Linux kernel) and will likely be unable to boot the system!

Recommended Partition Scheme (UEFI)
#

The table below provides a recommended default partition layout for a Gentoo installation.

Device Path	Mount Point	Filesystem	Description
`/dev/nvme0n1p1`	`/efi`	vfat	EFI System Partition (ESP)
`/dev/nvme0n1p2`	`swap`	swap	Swap partition
`/dev/nvme0n1p3`	`/`	xfs	Root partition

cfdisk Practical Example (Recommended)
#

cfdisk is a graphical partitioning tool with a simple, intuitive interface.

cfdisk /dev/nvme0n1

Operation tips:

Select GPT label type.
Create ESP: New partition → size 1G → type EFI System.
Create Swap: New partition → size 4G → type Linux swap.
Create Root: New partition → remaining space → type Linux filesystem (default).
Select Write to write changes, type yes to confirm.
Select Quit to exit.

                                                                 Disk: /dev/nvme0n1
                                              Size: 931.51 GiB, 1000204886016 bytes, 1953525168 sectors
                                            Label: gpt, identifier: 9737D323-129E-4B5F-9049-8080EDD29C02

    Device                                     Start                   End                   Sectors               Size Type
    /dev/nvme0n1p1                                34                  32767                 32734                16M Microsoft reserved
    /dev/nvme0n1p2                             32768              879779839             879747072             419.5G Microsoft basic data
    /dev/nvme0n1p3                        1416650752             1418747903               2097152                 1G EFI System
    /dev/nvme0n1p4                        1418747904             1437622271              18874368                 9G Linux swap
    /dev/nvme0n1p5                        1437622272             1953523711             515901440               246G Linux filesystem
>>  /dev/nvme0n1p6                         879779840             1416650751             536870912               256G Linux filesystem

 ┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
 │  Partition UUID: F2F1EF58-82EA-46A6-BF49-896AA40C6060                                                                                           │
 │  Partition type: Linux filesystem (0FC63DAF-8483-4772-8E79-3D69D8477DE4)                                                                        │
 │ Filesystem UUID: b4b0b42d-20be-4cf8-be81-9775efa6c151                                                                                           │
 │Filesystem LABEL: crypthomevar                                                                                                                   │
 │      Filesystem: crypto_LUKS                                                                                                                    │
 └─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
                                   [ Delete ]  [Resize]  [ Quit ]  [ Type ]  [ Help ]  [ Sort ]  [ Write ]  [ Dump ]


                                                        Quit program without writing changes

Advanced Settings: fdisk Command-Line Partitioning (Click to Expand)

fdisk is a command-line partitioning tool.

fdisk /dev/nvme0n1

1. View current partition layout

Use the p key to display the current disk partition configuration.

Command (m for help): p
Disk /dev/nvme0n1: 931.51 GiB, 1000204886016 bytes, 1953525168 sectors
Disk model: NVMe SSD
Units: sectors of 1 * 512 = 512 bytes
Sector size (logical/physical): 512 bytes / 4096 bytes
I/O size (minimum/optimal): 4096 bytes / 4096 bytes
Disklabel type: gpt
Disk identifier: 3E56EE74-0571-462B-A992-9872E3855D75

Device           Start        End    Sectors   Size Type
/dev/nvme0n1p1    2048    2099199    2097152     1G EFI System
/dev/nvme0n1p2 2099200   10487807    8388608     4G Linux swap
/dev/nvme0n1p3 10487808 1953523711 1943035904 926.5G Linux root (x86-64)

2. Create a new disk label

Press g to immediately delete all existing partitions and create a new GPT disk label:

Command (m for help): g
Created a new GPT disklabel (GUID: ...).

3. Create EFI System Partition (ESP)

Enter n to create a new partition, select partition number 1, accept the default first sector (2048), and enter +1G for the last sector:

Command (m for help): n
Partition number (1-128, default 1): 1
First sector (2048-..., default 2048): <Enter>
Last sector, +/-sectors or +/-size{K,M,G,T,P} (...): +1G

Created a new partition 1 of type 'Linux filesystem' and of size 1 GiB.

Mark the partition as EFI System (type code 1):

Command (m for help): t
Selected partition 1
Partition type or alias (type L to list all): 1
Changed type of partition 'Linux filesystem' to 'EFI System'.

4. Create Swap partition

Command (m for help): n
Partition number (2-128, default 2): 2
First sector (...): <Enter>
Last sector (...): +4G

Command (m for help): t
Partition number (1,2, default 2): 2
Partition type or alias (type L to list all): 19
Changed type of partition 'Linux filesystem' to 'Linux swap'.

(Note: Type 19 is Linux swap)

5. Create root partition

Command (m for help): n
Partition number (3-128, default 3): 3
First sector (...): <Enter>
Last sector (...): <Enter>

Created a new partition 3 of type 'Linux filesystem' and of size 926.5 GiB.

6. Write changes

After verifying, enter w to write changes and exit:

Command (m for help): w
The partition table has been altered.
Calling ioctl() to re-read partition table.
Syncing disks.

3. Create Filesystems and Mount
#

Reference: Gentoo Handbook: AMD64 - Preparing the Disks · Ext4 · XFS · Btrfs

Why is this step needed?

Disk partitioning only allocates space, but doesn't enable data storage yet. Creating a filesystem (such as ext4, Btrfs) allows the operating system to manage and access that space. Mounting connects these filesystems to specific locations in the Linux file tree.

3.1 Format
#

mkfs.fat -F 32 /dev/nvme0n1p1  # Format ESP partition as FAT32
mkswap /dev/nvme0n1p2          # Format Swap partition
mkfs.xfs /dev/nvme0n1p3        # Format Root partition as XFS

For Btrfs:

mkfs.btrfs -L gentoo /dev/nvme0n1p3

For ext4:

mkfs.ext4 /dev/nvme0n1p3

3.2 Mount (XFS example)
#

mount /dev/nvme0n1p3 /mnt/gentoo        # Mount root partition
mkdir -p /mnt/gentoo/efi                # Create ESP mount point
mount /dev/nvme0n1p1 /mnt/gentoo/efi    # Mount ESP partition
swapon /dev/nvme0n1p2                   # Enable Swap partition

Advanced Settings: Btrfs Subvolume Example (Click to Expand)

1. Format

mkfs.fat -F 32 /dev/nvme0n1p1  # Format ESP
mkswap /dev/nvme0n1p2          # Format Swap
mkfs.btrfs -L gentoo /dev/nvme0n1p3 # Format Root (Btrfs)

2. Create subvolumes

mount /dev/nvme0n1p3 /mnt/gentoo
btrfs subvolume create /mnt/gentoo/@
btrfs subvolume create /mnt/gentoo/@home
umount /mnt/gentoo

3. Mount subvolumes

mount -o compress=zstd,subvol=@ /dev/nvme0n1p3 /mnt/gentoo
mkdir -p /mnt/gentoo/{efi,home}
mount -o subvol=@home /dev/nvme0n1p3 /mnt/gentoo/home
mount /dev/nvme0n1p1 /mnt/gentoo/efi    # Note: ESP must be FAT32
swapon /dev/nvme0n1p2

4. Verify mounts

lsblk

Output example:

NAME             MAJ:MIN RM   SIZE RO TYPE  MOUNTPOINTS
nvme0n1          259:1    0 931.5G  0 disk
├─nvme0n1p1      259:7    0     1G  0 part  /mnt/gentoo/efi
├─nvme0n1p2      259:8    0     4G  0 part  [SWAP]
└─nvme0n1p3      259:9    0 926.5G  0 part  /mnt/gentoo/home
                                            /mnt/gentoo

Btrfs Snapshot Recommendation

It is recommended to use Snapper to manage snapshots. A proper subvolume layout (e.g., separating @ and @home) makes system rollback much easier.

Advanced Settings: Encrypted Partition (LUKS) (Click to Expand)

LUKS-specific partition layout

Device	Mount point	Filesystem	Description
`/dev/nvme0n1p1`	`/efi`	vfat	EFI System Partition (ESP), 1G
`/dev/nvme0n1p2`	`/boot`	ext4	Unencrypted, stores the kernel and initramfs, 1G
`/dev/nvme0n1p3`	`swap`	swap	Swap partition
`/dev/nvme0n1p4`	`/`	btrfs	LUKS-encrypted root partition

GRUB must read the kernel and initramfs before decryption, so they must reside on unencrypted /boot; the root partition remains encrypted.

1. Create encrypted container

cryptsetup luksFormat --type luks2 --pbkdf argon2id --hash sha512 --key-size 512 /dev/nvme0n1p4

This procedure encrypts only the root partition /dev/nvme0n1p4. The ESP, separate /boot partition, and separate Swap partition are not protected by LUKS; swapped memory pages are written to unencrypted Swap.

2. Open encrypted container

The mapper name cryptroot is reused in the dracut/fstab/bootloader steps later. Keep it consistent if you change it.

cryptsetup luksOpen /dev/nvme0n1p4 cryptroot

3. Format

mkfs.fat -F 32 /dev/nvme0n1p1                   # Format ESP
mkfs.ext4 /dev/nvme0n1p2                        # Format unencrypted /boot
mkswap /dev/nvme0n1p3                           # Format Swap
mkfs.btrfs --label root /dev/mapper/cryptroot   # Format Root (Btrfs) on top of LUKS

4. Mount

mount /dev/mapper/cryptroot /mnt/gentoo
btrfs subvolume create /mnt/gentoo/@
btrfs subvolume create /mnt/gentoo/@home
umount /mnt/gentoo
mount -o compress=zstd,subvol=@ /dev/mapper/cryptroot /mnt/gentoo
mkdir -p /mnt/gentoo/boot
mount /dev/nvme0n1p2 /mnt/gentoo/boot
mkdir -p /mnt/gentoo/{efi,home}
mount -o subvol=@home /dev/mapper/cryptroot /mnt/gentoo/home
mount /dev/nvme0n1p1 /mnt/gentoo/efi
swapon /dev/nvme0n1p3

5. Verify mounts

lsblk

Output example:

NAME             MAJ:MIN RM   SIZE RO TYPE  MOUNTPOINTS
nvme0n1          259:1    0 931.5G  0 disk
├─nvme0n1p1      259:7    0     1G  0 part  /mnt/gentoo/efi
├─nvme0n1p2      259:8    0     1G  0 part  /mnt/gentoo/boot
├─nvme0n1p3      259:9    0     4G  0 part  [SWAP]
└─nvme0n1p4      259:10   0 925.5G  0 part
  └─cryptroot    253:0    0 925.5G  0 crypt /mnt/gentoo

Recommendation

After mounting, use lsblk to verify mount points are correct.

lsblk

Output example:

NAME             MAJ:MIN RM   SIZE RO TYPE  MOUNTPOINTS
 nvme0n1          259:1    0 931.5G  0 disk
├─nvme0n1p1      259:7    0     1G  0 part  /efi
├─nvme0n1p2      259:8    0     4G  0 part  [SWAP]
└─nvme0n1p3      259:9    0 926.5G  0 part  /

4. Download Stage3 and Enter chroot
#

Reference: Gentoo Handbook: AMD64 - Installing the Gentoo Installation Files · Stage file

Why is this step needed?

Stage3 is a minimal Gentoo base system environment. We extract it to the hard drive as the "foundation" of the new system, then use chroot to enter this new environment for subsequent configuration.

4.1 Choose Stage3
#

OpenRC: stage3-amd64-openrc-*.tar.xz
systemd: stage3-amd64-systemd-*.tar.xz
Desktop variants just have some USE flags pre-enabled; the standard version is more flexible.

4.2 Download and Extract
#

Download the current Stage3 archive from Gentoo's autobuild directory:

cd /mnt/gentoo
# OpenRC:
BASE=https://distfiles.gentoo.org/releases/amd64/autobuilds
STAGE3=$(wget -qO- "$BASE/latest-stage3-amd64-openrc.txt" | grep -E '^[0-9]{8}T[0-9]{6}Z/stage3-amd64-openrc-[0-9]{8}T[0-9]{6}Z[.]tar[.]xz ' | cut -d' ' -f1)
# For systemd, replace both occurrences of openrc in the preceding line with systemd.
test -n "$STAGE3" || exit 1
wget "$BASE/$STAGE3"
wget "$BASE/$STAGE3.asc"
gpg --verify "${STAGE3##*/}.asc" "${STAGE3##*/}"
tar xpvf "${STAGE3##*/}" --xattrs-include='*.*' --numeric-owner

4.3 Copy DNS and Mount Pseudo-Filesystems
#

cp --dereference /etc/resolv.conf /mnt/gentoo/etc/ # Copy DNS configuration
mount --types proc /proc /mnt/gentoo/proc          # Mount process information
mount --rbind /sys /mnt/gentoo/sys                 # Bind mount system information
mount --rbind /dev /mnt/gentoo/dev                 # Bind mount device nodes
mount --rbind /run /mnt/gentoo/run                 # Bind mount runtime information
mount --make-rslave /mnt/gentoo/sys                # Set as slave mount (prevents affecting host on unmount)
mount --make-rslave /mnt/gentoo/dev
mount --make-rslave /mnt/gentoo/run

OpenRC users can omit the /run step.

4.4 Enter chroot
#

chroot /mnt/gentoo /bin/bash    # Switch root directory to new system
source /etc/profile             # Load environment variables
export PS1="(chroot) ${PS1}"    # Modify prompt to distinguish environment

5. Initialize Portage and make.conf
#

Reference: Gentoo Handbook: AMD64 - Installing the Gentoo Base System

Why is this step needed?

Portage is Gentoo's package management system and its core feature. Initializing Portage and configuring make.conf is like setting the "build blueprint" for your new system, determining how software is compiled, what features are included, and where to download from.

5.1 Sync Tree
#

emerge-webrsync   # Get the latest Portage snapshot (faster than rsync)
emerge --sync     # Sync Portage tree (get latest ebuilds)
emerge --ask app-editors/vim # Install Vim editor (recommended)
eselect editor list          # List available editors
eselect editor set vi        # Set Vim as default editor

Configure mirror (choose one):

emerge --ask --verbose --oneshot app-portage/mirrorselect
mirrorselect -i -o >> /etc/portage/make.conf
# Or manually set a mirror from the official list:
# https://www.gentoo.org/downloads/mirrors/

5.2 make.conf Example
#

Reference: Gentoo Handbook: AMD64 - USE Flags · /etc/portage/make.conf

Edit /etc/portage/make.conf:

vim /etc/portage/make.conf

Quick/beginner configuration (copy-paste ready):

Tip

Adjust the -j value in MAKEOPTS to match your CPU core count (e.g., use -j8 for an 8-core CPU).

# ========== Compilation Optimization Flags ==========
# -march=native: Optimize for the current CPU architecture
# -O2: Recommended optimization level, balancing performance and compile time
# -pipe: Use pipes to speed up compilation
COMMON_FLAGS="-march=native -O2 -pipe"
CFLAGS="${COMMON_FLAGS}"    # C compiler flags
CXXFLAGS="${COMMON_FLAGS}"  # C++ compiler flags
FCFLAGS="${COMMON_FLAGS}"   # Fortran compiler flags
FFLAGS="${COMMON_FLAGS}"    # Fortran 77 compiler flags

# ========== Parallel Compilation Settings ==========
# The number after -j = CPU thread count (run nproc to check)
# Reduce if running low on memory (e.g., -j4)
MAKEOPTS="-j8"

# ========== Language & Localization ==========
# LC_MESSAGES=C: Keep build output in English for easier searching
LC_MESSAGES=C
# L10N/LINGUAS: Supported languages (affects software translations and docs)
L10N="en en-US"
LINGUAS="en en_US"

# ========== Mirror Configuration ==========
# Use mirrorselect to pick the nearest mirror automatically
# Official mirror list: https://www.gentoo.org/downloads/mirrors/

# ========== USE Flags ==========
# Set only USE flags that differ from the profile defaults.
USE="git dist-kernel"

# ========== License Configuration ==========
# "*" accepts all licenses; "@FREE" accepts only free software
ACCEPT_LICENSE="*"

Confirm USE Flags Provided by the Profile

The systemd profile provides systemd and udev; the desktop profile provides dbus, policykit, and bluetooth; desktop/plasma provides networkmanager and forces policykit. The profile is the primary source of USE flags, so make.conf should contain only settings that differ from the profile defaults. Use these commands to inspect the current USE set and a package's USE flags:

emerge --info | grep '^USE='
emerge -pv <package>

Detailed Configuration Example (Recommended Reading) (Click to Expand)

# vim: set filetype=bash  # Tell Vim to use bash syntax highlighting

# ========== System Architecture (do not modify manually) ==========
CHOST="x86_64-pc-linux-gnu"

# ========== Compilation Optimization Flags ==========
# -march=native    Optimize for current CPU architecture
#                  Note: compiled programs may not run on other CPUs
# -O2              Recommended optimization level, balanced performance and stability
#                  Avoid -O3, which may cause some software to fail to compile
# -pipe            Use pipes instead of temp files, speeds up compilation
COMMON_FLAGS="-march=native -O2 -pipe"
CFLAGS="${COMMON_FLAGS}"      # C compiler flags
CXXFLAGS="${COMMON_FLAGS}"    # C++ compiler flags
FCFLAGS="${COMMON_FLAGS}"     # Fortran compiler flags
FFLAGS="${COMMON_FLAGS}"      # Fortran 77 compiler flags

# CPU instruction set optimization (run cpuid2cpuflags to auto-generate)
# CPU_FLAGS_X86="aes avx avx2 f16c fma3 mmx mmxext pclmul popcnt sse sse2 ..."

# ========== Parallel Compilation Settings ==========
MAKEOPTS="-j8"  # Adjust to your actual CPU thread count

# ========== Language & Localization ==========
LC_MESSAGES=C
L10N="en en-US"
LINGUAS="en en_US"

# ========== Mirror Configuration ==========
# Use mirrorselect to automatically choose the best mirror:
# mirrorselect -i -o >> /etc/portage/make.conf
# Official mirror list: https://www.gentoo.org/downloads/mirrors/

# ========== Emerge Default Options ==========
EMERGE_DEFAULT_OPTS="--ask --verbose --with-bdeps=y --complete-graph=y"

# ========== USE Flags (global feature switches) ==========
# Set only USE flags that differ from the profile defaults; this enables git and dist-kernel.
USE="git dist-kernel"

# ========== License Configuration ==========
ACCEPT_LICENSE="*"

# ========== Video Card Configuration (optional) ==========
# Choose based on your GPU:
# VIDEO_CARDS="intel"
# VIDEO_CARDS="amdgpu radeonsi"
# VIDEO_CARDS="nvidia"

# ========== Portage Features (optional) ==========
# Enable split debug information
# FEATURES="${FEATURES} splitdebug"

# ========== Portage Logging (recommended) ==========
PORTAGE_ELOG_CLASSES="warn error log"
PORTAGE_ELOG_SYSTEM="save"

Beginner Tips

The number in MAKEOPTS="-j8" should match your CPU thread count, check with nproc
If you run out of memory during compilation, reduce parallel jobs (e.g., change to -j4)
USE flags are Gentoo's core feature, determining which features are compiled into software

Advanced Settings: CPU Instruction Set Optimization (CPU_FLAGS_X86) (Click to Expand)

Reference: CPU_FLAGS_*

To let Portage know which CPU instruction sets your processor supports (e.g., AES, AVX, SSE4.2), configure CPU_FLAGS_X86.

Install detection tool:

emerge --ask app-portage/cpuid2cpuflags

Run detection and write to config:

cpuid2cpuflags >> /etc/portage/make.conf

Check the end of /etc/portage/make.conf, you should see something like:

CPU_FLAGS_X86="aes avx avx2 f16c fma3 mmx mmxext pclmul popcnt rdrand sse sse2 sse3 sse4_1 sse4_2 ssse3"

5.3 Binary Packages (binhost) (Optional)
#

References: Gentoo Binary Host Quickstart · Binary package guide · gentoo-zh mirror list

Purpose

Gentoo normally compiles software from source, and compilation accounts for much of the time in the installation schedule. The official binhost provides signed, prebuilt binary packages. When a package matches the configuration, Portage installs it directly; otherwise, it still compiles the package from source. A binhost changes only the package source, not the system layout, so you can enable or disable it at any time.

Confirm the repository configuration
#

Stage3 preconfigures the official binhost in /etc/portage/binrepos.conf/gentoo.conf. Inspect the current configuration first:

cat /etc/portage/binrepos.conf/gentoo.conf

A typical configuration is:

[gentoo]
priority = 1
sync-uri = https://distfiles.gentoo.org/releases/amd64/binpackages/23.0/x86-64
location = /var/cache/binhost/gentoo
verify-signature = true

sync-uri must point to the directory containing the Packages index. When changing mirrors, change only the host; keep the path unchanged. See the gentoo-zh mirror list for available mirrors.

Choose an instruction-set level
#

The final component of the sync-uri path is the instruction-set level. Stage3 uses the generic x86-64 level by default. A higher level provides packages optimized for newer instruction sets.

First, check the levels supported by the machine:

ld.so --help

Look for Subdirectories of glibc-hwcaps directories in the output. A level marked supported, searched is available on this machine:

Subdirectories of glibc-hwcaps directories, in priority order:
  x86-64-v4 (supported, searched)
  x86-64-v3 (supported, searched)
  x86-64-v2 (supported, searched)

The official amd64 binhost builds only x86-64 and x86-64-v3; it does not provide v2 or v4. Use x86-64-v3 if the output includes x86-64-v3 (supported, searched); otherwise retain x86-64. The example machine supports v4, but v3 remains the highest available level.

After confirming the level, change the final component of sync-uri:

# /etc/portage/binrepos.conf/gentoo.conf
sync-uri = https://distfiles.gentoo.org/releases/amd64/binpackages/23.0/x86-64-v3

arm64 has one level only, at /releases/arm64/binpackages/23.0/arm64; no selection is needed.

Note

The level affects only the instruction set used by binary packages; it does not affect local compilation. Packages fetched for a level unsupported by the CPU will crash with an illegal instruction. Use the output of ld.so --help, not the CPU model, to choose the level.

Enable automatic use
#

To let emerge automatically use a suitable binary package when one is available:

# Add to /etc/portage/make.conf
FEATURES="${FEATURES} getbinpkg"

For one command only:

emerge --ask --getbinpkg sys-kernel/gentoo-kernel

-bin packages are not binary packages

Packages ending in -bin, such as sys-kernel/gentoo-kernel-bin, use prebuilt artifacts from the upstream release. The ebuild only downloads and extracts them, but they still follow the ordinary ebuild path and emerge -pv displays [ebuild]. The binary packages in this section are built by Portage and distributed through a binhost as .gpkg.tar files; they display as [binary].

Therefore, gentoo-kernel-bin in Section 7 neither compiles nor uses the binhost. Packages built from source, including sys-kernel/gentoo-kernel and large desktop-guide packages such as browsers, LLVM, and Rust, can use the binhost to reduce compilation time.

Confirm that a binary package is used
#

Only the [binary] prefix in emerge -pv output means the item uses a binary package; [ebuild] means Portage must compile it from source:

emerge -pv sys-kernel/gentoo-kernel

If the configuration is correct but the result still shows [ebuild], the usual causes are:

USE mismatch. --binpkg-respect-use is enabled by default. Portage skips a binary package when its USE flags do not match the current configuration. The official binhost uses profile-default USE flags, so changing more USE flags in make.conf reduces the match rate.
Dependency changes. --binpkg-changed-deps is enabled by default. Portage skips the package when an ebuild dependency changed after the package was built.
The version is not indexed. The binhost provides only versions that have already been built; newer versions from a synchronized tree are compiled from source.

CFLAGS do not participate in matching, so -march=native in make.conf does not invalidate official binary packages. Locally compiled packages use native optimization, while packages from the binhost use a generic instruction set; the two can coexist.

Related options
#

Option	Purpose
`-k` / `--usepkg`	Use a package from the local `PKGDIR` when available
`-g` / `--getbinpkg`	Fetch from a remote binhost; implies `-k`
`-K` / `--usepkgonly`	Use local binary packages only; fail if unavailable
`-G` / `--getbinpkgonly`	Use binary packages only; prefer remote packages over local ones

Use -g for installation. -K and -G disable --binpkg-respect-use and --binpkg-changed-deps, so installed packages may not match the USE flags in make.conf; do not use them at this stage.

Signature verification
#

verify-signature = true requires packages from this repository to carry a trusted signature. Recent Portage versions verify remote binary packages by default and run getuto automatically on the first download to establish a trusted keyring in /etc/portage/gnupg. Users of the official binhost do not need to configure FEATURES="binpkg-request-signature". Retrieved packages are cached in the directory named by location, separately from packages produced locally by FEATURES="buildpkg". See the news item dated 2026-05-03 for both changes. After installation, you can also run eselect news read.

Advanced: gentoo-zh binary packages, local builds, and LAN sharing (Click to Expand)

gentoo-zh binhost

The gentoo-zh overlay provides prebuilt versions of compilation-heavy packages including browsers, office suites, and Electron applications. It currently supports amd64 only and has stable and unstable channels; import the community signing key separately. It is an additional repository, not a replacement for the official binhost. See the gentoo-zh Overlay page for configuration. The desktop guide configures the overlay in Section 12.9, so configure it only after completing that section.

Build your own binary packages

Create binary packages while compiling so they can be reused when reinstalling or setting up a second machine:

# Add to /etc/portage/make.conf
FEATURES="${FEATURES} buildpkg"
PKGDIR="/var/cache/binpkgs"

Package already installed can be packaged afterward:

emerge --ask app-portage/gentoolkit
quickpkg --include-config=y sys-apps/portage

Share with other machines

Publish PKGDIR through any HTTP server. On each client, add a repository pointing to that directory in /etc/portage/binrepos.conf/. Address both of the following:

Packages compiled with -march=native run only on the same CPU model. To share them, set the build machine's COMMON_FLAGS to an explicit architecture, such as -march=x86-64-v3.
Locally built packages are unsigned by default. Either set verify-signature = false for that repository on the client, or enable FEATURES="binpkg-signing" on the build machine and import its public key into the client's /etc/portage/gnupg.

Clean up

Binary packages continually consume disk space:

eclean-pkg -p       # First see what would be removed
eclean-pkg          # Remove packages replaced by newer versions
eclean-pkg -d       # Retain only the minimum set needed to reinstall

6. Profile, System Settings & Localization
#

Reference: Gentoo Handbook: AMD64 - Installing the Gentoo Base System

6.1 Choose Profile
#

eselect profile list          # List all available profiles
eselect profile set <number>  # Set the selected profile
emerge -avuDN @world          # Update system to match new profile

Common options:

default/linux/amd64/23.0/desktop/plasma/systemd
default/linux/amd64/23.0/desktop/gnome/systemd
default/linux/amd64/23.0/desktop (OpenRC desktop)

6.2 Timezone and Locale
#

Reference: Gentoo Wiki: Localization/Guide

# Set timezone (use your actual timezone)
# List available timezones:
ls /usr/share/zoneinfo/
# Examples: UTC, America/New_York, Europe/London, Asia/Tokyo, Australia/Sydney

echo "UTC" > /etc/timezone
emerge --config sys-libs/timezone-data

echo "en_US.UTF-8 UTF-8" > /etc/locale.gen
locale-gen                      # Generate selected locales
eselect locale set en_US.utf8   # Set system default locale
env-update && source /etc/profile && export PS1="(chroot) ${PS1}"

6.3 Hostname and Network Configuration
#

Set hostname:

echo "gentoo" > /etc/hostname

Network manager options:

Option A: NetworkManager (recommended, universal)

Reference: NetworkManager

Suitable for most desktop users, supports both OpenRC and systemd.

emerge --ask net-misc/networkmanager
# OpenRC:
rc-update add NetworkManager default
# systemd:
systemctl enable NetworkManager

Configuration Tips

GUI: Run nm-connection-editor CLI: Use nmtui (graphical wizard) or nmcli

Advanced: Use iwd backend (Click to Expand)

NetworkManager supports using iwd as the backend (faster than wpa_supplicant).

echo "net-misc/networkmanager iwd" >> /etc/portage/package.use/networkmanager
emerge --ask --newuse net-misc/networkmanager

Then edit /etc/NetworkManager/NetworkManager.conf, and add wifi.backend=iwd under [device].

Option B: Lightweight Options (Click to Expand)

Wired network (dhcpcd)

Reference: dhcpcd

emerge --ask net-misc/dhcpcd
# OpenRC:
rc-update add dhcpcd default
# systemd:
systemctl enable dhcpcd

Wireless network (iwd)

Reference: iwd

emerge --ask net-wireless/iwd
# OpenRC:
rc-update add iwd default
# systemd:
systemctl enable iwd

Tip: iwd is a modern, lightweight wireless daemon.

Option C: Native Network Management (Click to Expand)

Use the init system's built-in network management, suitable for servers or minimal environments.

OpenRC network interface service:

Reference: OpenRC · OpenRC: Network Management

vim /etc/conf.d/net

Note

Replace enp5s0 below with your actual network interface name (check with ip link).

Write the following:

config_enp5s0="dhcp"

ln -s /etc/init.d/net.lo /etc/init.d/net.enp5s0 # Create symlink for network service
rc-update add net.enp5s0 default                # Enable at boot

Systemd native network management:

Reference: systemd-networkd · systemd-resolved

systemd includes built-in network management, suitable for servers or minimal environments:

systemctl enable systemd-networkd
systemctl enable systemd-resolved

Note: Requires manually writing .network configuration files.

6.4 Configure fstab
#

Reference: Gentoo Handbook: AMD64 - fstab · Gentoo Wiki: /etc/fstab

Why is this step needed?

The system needs to know which partitions to mount at boot. The /etc/fstab file is like a "partition list" that tells the system:

Which partitions to automatically mount at boot
Where each partition is mounted
What filesystem type to use

Use UUID: Device paths (e.g., /dev/sda1) may change with hardware changes, but UUIDs are unique filesystem identifiers that never change.

Method A: Auto-generate with genfstab (Recommended)
#

Click to Expand for Detailed Steps

Installing genfstab

genfstab ships in the sys-fs/genfstab package (originally from Arch Linux's arch-install-scripts).

Gentoo LiveGUI / Arch LiveISO: pre-installed, ready to use
Gentoo Minimal ISO: install it first with emerge --ask sys-fs/genfstab

genfstab flags

Flag	Identifier	Notes
`-U`	filesystem UUID	Recommended
`-L`	filesystem LABEL	Requires preset labels
`-t PARTUUID`	GPT PARTUUID	GPT only
(none)	device path (`/dev/sdX`)	Not recommended

Use -U. UUIDs are unique to the filesystem and don't change when drive ordering shifts.

Standard usage (run outside chroot):

# 1. Confirm all partitions are correctly mounted
lsblk
mount | grep /mnt/gentoo

# 2. Generate fstab (using UUID)
genfstab -U /mnt/gentoo >> /mnt/gentoo/etc/fstab

# 3. Check the generated file
cat /mnt/gentoo/etc/fstab

Alternative if already in chroot

If you've already chrooted into the new system, you can:

Method 1: Run inside chroot (simplest)

emerge --ask sys-fs/genfstab
genfstab -U / >> /etc/fstab
vim /etc/fstab  # Check and clean up extra entries (e.g., /proc, /sys, /dev)

Method 2: Open a new terminal window (LiveGUI)

If using a Live environment with a GUI (like the official Gentoo LiveGUI), open a new terminal:

genfstab -U /mnt/gentoo >> /mnt/gentoo/etc/fstab

Method 3: TTY switch (Minimal ISO)

Press Ctrl+Alt+F2 to switch to a new TTY (Live environment)

Install and run:

emerge --ask sys-fs/genfstab
genfstab -U /mnt/gentoo >> /mnt/gentoo/etc/fstab

Press Ctrl+Alt+F1 to return to chroot

genfstab compatibility notes

genfstab detects every filesystem under the target mount point. According to its source it explicitly supports:

Btrfs subvolumes — the subvol= option is preserved (no false bind-mount detection).
LUKS-encrypted partitions — uses the decrypted device's UUID (/dev/mapper/xxx).
Regular partitions — ext4, xfs, vfat and the usual filesystems.

Prerequisite: every partition must already be mounted correctly (including Btrfs subvolumes and unlocked LUKS partitions) before you run genfstab.

Method B: Manual Edit
#

Click to Expand for Manual Configuration

1. Get partition UUIDs

blkid

Output example:

/dev/nvme0n1p1: UUID="7E91-5869" TYPE="vfat" PARTLABEL="EFI"
/dev/nvme0n1p2: UUID="7fb33b5d-..." TYPE="swap" PARTLABEL="swap"
/dev/nvme0n1p3: UUID="8c08f447-..." TYPE="xfs" PARTLABEL="root"

2. Edit fstab

vim /etc/fstab

Basic configuration example (ext4/xfs):

# <UUID>                                   <Mount>      <Type> <Options>         <dump> <fsck>
UUID=7E91-5869                             /efi         vfat   umask=0077,tz=UTC  0      2
UUID=7fb33b5d-4cff-47ff-ab12-7b461b5d6e13  none         swap   sw                0      0
UUID=8c08f447-c79c-4fda-8c08-f447c79ce690  /            xfs    defaults,noatime  0      1

fstab fields

Field	Meaning
UUID	Unique filesystem identifier (get it from `blkid`)
Mount	Mount point (`none` for swap)
Type	`vfat`, `ext4`, `xfs`, `btrfs`, `swap`, etc.
Options	Comma-separated mount options
dump	Backup flag — usually `0`
fsck	Boot-time check order: `1` = root, `2` = others, `0` = skip

Btrfs subvolume configuration

With genfstab:

If the Btrfs subvolumes are already mounted correctly, genfstab -U picks up subvol= automatically.

# Confirm subvolume mounts
mount | grep btrfs
# Example output:
#   /dev/nvme0n1p3 on /mnt/gentoo type btrfs (rw,noatime,compress=zstd:3,subvol=/@)

# Generate
genfstab -U /mnt/gentoo >> /mnt/gentoo/etc/fstab

Manual example:

# Root subvolume
UUID=7b44c5eb-caa0-413b-9b7e-a991e1697465  /       btrfs  defaults,noatime,compress=zstd:3,discard=async,space_cache=v2,subvol=@       0 0

# Home subvolume (same UUID, different subvolume)
UUID=7b44c5eb-caa0-413b-9b7e-a991e1697465  /home   btrfs  defaults,noatime,compress=zstd:3,discard=async,space_cache=v2,subvol=@home   0 0

# Swap (separate partition)
UUID=7fb33b5d-4cff-47ff-ab12-7b461b5d6e13  none    swap   sw                                                                            0 0

# EFI partition
UUID=7E91-5869                             /efi    vfat   defaults,noatime,fmask=0022,dmask=0022                                        0 2

Common Btrfs mount options

Option	Meaning
`compress=zstd:3`	zstd compression at level 3 (good performance/ratio balance)
`discard=async`	Async TRIM (recommended for SSDs)
`space_cache=v2`	v2 space cache (default; better performance)
`subvol=@`	The subvolume to mount
`noatime`	Skip access-time updates (slight performance win)

Notes

All subvolumes of the same Btrfs partition share the same UUID.
Always use blkid to read your real UUIDs.

LUKS encrypted partition configuration

Key point

fstab must use the decrypted mapper device UUID (/dev/mapper/xxx), not the UUID of the LUKS container.

With genfstab:

genfstab detects the decrypted device and uses the correct UUID automatically:

# Confirm LUKS is unlocked
lsblk
# You should see something like: nvme0n1p4 → cryptroot → mount point

# Generate (uses /dev/mapper/cryptroot's UUID)
genfstab -U /mnt/gentoo >> /mnt/gentoo/etc/fstab

Manual: telling the two UUIDs apart

blkid

# LUKS container (TYPE="crypto_LUKS") — do NOT use this!
/dev/nvme0n1p4: UUID="562d0251-..." TYPE="crypto_LUKS"

# Decrypted device (TYPE="btrfs") — use this one!
/dev/mapper/cryptroot: UUID="7b44c5eb-..." TYPE="btrfs"

Manual example (Btrfs on LUKS):

# Root (UUID of the decrypted /dev/mapper/cryptroot)
UUID=7b44c5eb-caa0-413b-9b7e-a991e1697465  /       btrfs  defaults,noatime,compress=zstd:3,discard=async,space_cache=v2,subvol=@       0 0

# Boot (unencrypted)
UUID=9a856e43-a0be-4477-8647-e6ab51cf80ef  /boot   ext4   defaults,noatime                                                                        0 2

# Home (different subvolume on the same encrypted partition, same UUID)
UUID=7b44c5eb-caa0-413b-9b7e-a991e1697465  /home   btrfs  defaults,noatime,compress=zstd:3,discard=async,space_cache=v2,subvol=@home   0 0

# Swap (separate partition or encrypted swap)
UUID=7fb33b5d-4cff-47ff-ab12-7b461b5d6e13  none    swap   sw                                                                            0 0

# EFI (unencrypted)
UUID=7E91-5869                             /efi    vfat   defaults,noatime,fmask=0022,dmask=0022                                        0 2

FAQ

Q: Why can't I use the LUKS container UUID? A: A LUKS container holds the encrypted raw bytes — the OS can't read a filesystem out of it. After unlock, the /dev/mapper/xxx device exposes a readable filesystem with its own UUID.

Q: Is discard=async safe on top of LUKS? A: LUKS2 + discard is generally safe. If you're particularly security-conscious, drop the option (at the cost of some SSD performance).

7. Kernel and Firmware
#

Reference: Gentoo Handbook: AMD64 - Configuring the Linux Kernel

Why is this step needed?

The kernel is the core of the operating system, responsible for managing hardware. Gentoo allows you to manually trim the kernel, keeping only the drivers you need, for maximum performance and a lean system. Beginners can also choose a pre-compiled kernel to get started quickly.

7.1 Install Firmware and Microcode
#

mkdir -p /etc/portage/package.license
# Accept the Linux firmware license terms
echo 'sys-kernel/linux-firmware linux-fw-redistributable no-source-code' > /etc/portage/package.license/linux-firmware
# Pick the installkernel USE flags that match your bootloader. Pick ONE row:
#   GRUB users          → 'sys-kernel/installkernel dracut grub'
#   systemd-boot users  → 'sys-kernel/installkernel dracut systemd systemd-boot'
#   Limine / other      → 'sys-kernel/installkernel dracut' (bootloader handled manually)
echo 'sys-kernel/installkernel dracut grub' > /etc/portage/package.use/installkernel
# systemd-boot users must also set the kernel command line before the first kernel installation:
# printf 'root=UUID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx rw quiet\n' > /etc/kernel/cmdline
emerge --ask sys-kernel/linux-firmware
emerge --ask sys-firmware/intel-microcode  # Intel CPU users
emerge --ask sys-kernel/installkernel

7.2 Quick Option: Pre-compiled Kernel
#

emerge --ask sys-kernel/gentoo-kernel-bin
# If the kernel was installed through the old order, reapply the installkernel configuration:
emerge --ask sys-kernel/installkernel && emerge --ask --config sys-kernel/gentoo-kernel-bin

Remember to regenerate the bootloader configuration after kernel upgrades.

Advanced Settings: Manual Kernel Compilation (Click to Expand)

Beginner Tip

Kernel compilation is complex and time-consuming. If you want to experience Gentoo quickly, you can skip this section and use the pre-compiled kernel from 7.2.

Manual kernel compilation gives you full control over system features, removing unneeded drivers for a leaner, more efficient kernel customized for your hardware.

Quick start (using Genkernel for automation):

emerge --ask sys-kernel/gentoo-sources sys-kernel/genkernel
eselect kernel list
eselect kernel set <gentoo-sources corresponding number>
genkernel --install all  # Auto-compile and install kernel, modules, and initramfs
                         # --install: Auto-install to /boot upon completion
                         # all: Full build (kernel + modules + initramfs)

8. Base Tools
#

Reference: Gentoo Handbook: AMD64 - Installing the Necessary System Tools

Why is this step needed?

Stage3 only has the most basic commands. We need to add essential components like system logging, network management, and filesystem tools to make the system work correctly after rebooting.

8.1 System Service Tools
#

OpenRC User Configuration (Click to Expand)

1. System logging

Reference: Syslog-ng

emerge --ask app-admin/syslog-ng
rc-update add syslog-ng default

2. Cron (scheduled tasks)

emerge --ask sys-process/cronie
rc-update add cronie default

3. Time synchronization

Reference: System Time · System Time (OpenRC)

emerge --ask net-misc/chrony
rc-update add chronyd default

systemd User Configuration (Click to Expand)

systemd includes built-in logging and scheduled task services, no additional installation needed.

Time synchronization

Reference: System Time · System Time (systemd)

systemctl enable --now systemd-timesyncd

8.2 Filesystem Tools
#

Install tools for your chosen filesystem (required):

emerge --ask sys-fs/e2fsprogs  # ext4
emerge --ask sys-fs/xfsprogs   # XFS
emerge --ask sys-fs/dosfstools # FAT/vfat (required for EFI partition)
emerge --ask sys-fs/btrfs-progs # Btrfs

9. Create Users and Permissions
#

Reference: Gentoo Handbook: AMD64 - Finalizing

Why is this step needed?

Linux does not recommend using the root account daily. We need to create a regular user and grant them sudo privileges to improve system security.

Replace the placeholder below with your actual account name; both commands must use the same name:

passwd root # Set root password
useradd -m -G wheel,video,audio,plugdev <username> # Create user and add to common groups
passwd <username> # Set user password
emerge --ask app-admin/sudo

Allow users in the wheel group to execute commands as root by editing the sudoers file:

visudo

Uncomment the following line (remove the # at the beginning):

%wheel ALL=(ALL:ALL) ALL

If using systemd, add the account to network, lp, and other groups as needed.

10. Install Bootloader
#

Reference: Gentoo Handbook: AMD64 - Configuring the Bootloader

Important Warning for Windows Dual Boot Users:
Windows updates often scan and forcibly overwrite /EFI/BOOT/bootx64.efi (the default boot path). Consequence: If you used this default path, Linux will fail to boot. Solution:
Use an independent filename/directory: Don't install the bootloader only as bootx64.efi.
Manually register the boot entry: Use efibootmgr to register the new file in the UEFI boot list.
All tutorials below (GRUB/systemd-boot/Limine) are already configured to use independent paths to avoid this issue.
Note: Windows updates may also change the UEFI boot order (placing Windows first). If this happens, enter BIOS and adjust the order.

10.1 Option A: GRUB (Recommended/Standard)
#

GRUB is the most feature-complete bootloader with the best compatibility, and supports automatic Windows detection. When using LUKS, an unencrypted separate /boot from the Chapter 3 LUKS partition layout is required; otherwise, GRUB cannot read the kernel.

Reference: GRUB

1. Install and configure

emerge --ask sys-boot/grub:2
# Install to ESP (--bootloader-id=Gentoo automatically creates a separate directory, avoiding conflicts)
grub-install --target=x86_64-efi --efi-directory=/efi --bootloader-id=Gentoo

2. Multi-OS configuration (Windows/Linux/other)

If you have Windows or other Linux distributions installed, enable os-prober to automatically detect them:

emerge --ask sys-boot/os-prober
# Enable os-prober (disabled by default for security)
echo 'GRUB_DISABLE_OS_PROBER=false' >> /etc/default/grub

3. Generate configuration file

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

(For multi-OS users only) Check the output to confirm it contains "Found Windows Boot Manager..." or other OS boot entries

10.2 Option B: systemd-boot (Minimal/Fast)
#

systemd-boot (formerly Gummiboot) is lightweight and simply configured, suitable for UEFI systems.

Reference: systemd-boot

1. Install

systemd users: For systemd version >= 254, you must enable the boot USE flag to use bootctl:

mkdir -p /etc/portage/package.use
echo "sys-apps/systemd boot" >> /etc/portage/package.use/systemd
emerge --ask --oneshot --verbose sys-apps/systemd

Then install the bootloader and inspect its entries:

bootctl --esp-path=/efi install
bootctl --esp-path=/efi list

OpenRC Users (systemd-utils) - Click to Expand

OpenRC users need to install sys-apps/systemd-utils with boot and kernel-install USE flags:

mkdir -p /etc/portage/package.use
echo "sys-apps/systemd-utils boot kernel-install" >> /etc/portage/package.use/systemd-utils
emerge --ask --oneshot --verbose sys-apps/systemd-utils
bootctl --esp-path=/efi install
bootctl --esp-path=/efi list

2. Configure loader

Edit /efi/loader/loader.conf:

timeout 3
console-mode auto

3. Use installkernel-managed Gentoo entries

Before the first kernel installation, systemd-boot users must select sys-kernel/installkernel dracut systemd systemd-boot in Section 7.1 and write the root parameters to /etc/kernel/cmdline. installkernel creates ${ESP}/gentoo/<actual-release>/linux, initrd, and the corresponding BLS entry.

If the kernel was installed through the old order, run emerge --ask sys-kernel/installkernel && emerge --ask --config sys-kernel/gentoo-kernel-bin.

4. Windows dual boot configuration

systemd-boot will automatically detect the Windows boot manager located on the same ESP (/efi/EFI/Microsoft/Boot/bootmgfw.efi), usually requiring no additional configuration.

If your Windows installation is on a different disk's ESP, or automatic detection fails, manually create /efi/loader/entries/windows.conf:

title      Windows 11
efi        /EFI/Microsoft/Boot/bootmgfw.efi

10.3 Option C: Limine (Modern/Flexible)
#

Limine has flexible configuration and supports dynamic menus.

Reference: Limine

1. Install

echo 'sys-boot/limine ~amd64' >> /etc/portage/package.accept_keywords/limine
emerge --ask sys-boot/limine

2. Deploy boot files (critical step)

To prevent Windows from overwriting, we deploy Limine as a Gentoo-specific boot entry, rather than the default BOOTX64.EFI.

# Copy the installed kernel and initramfs to the ESP before mounting the ESP at /boot.
ls -1 /boot/vmlinuz-* /boot/initramfs-*
cp -v /boot/vmlinuz-* /boot/initramfs-* /efi/
# Change the ESP mount point in /etc/fstab from /efi to /boot.
vim /etc/fstab
umount /efi
mount /boot
mkdir -p /boot/EFI/Gentoo
cp -v /usr/share/limine/BOOTX64.EFI /boot/EFI/Gentoo/limine.efi
cp -v /usr/share/limine/limine-bios.sys /boot/ # (optional) only needed for BIOS

3. Configure Limine

Edit /boot/limine.conf on the ESP. Replace the two placeholders below with the complete filenames for the same kernel release from the preceding ls output:

timeout: 5

/Gentoo Linux
    protocol: linux
    kernel_path: boot():/<vmlinuz-filename>
    module_path: boot():/<initramfs-filename>
    cmdline: root=UUID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx rw

/Windows 11
    protocol: efi
    path: boot():/EFI/Microsoft/Boot/bootmgfw.efi

After a kernel update, the new kernel and initramfs are written to the ESP mounted at /boot. Before each reboot after an update, run ls -1 /boot/vmlinuz-* /boot/initramfs-* and update kernel_path and module_path to the matching new filenames.

4. Register UEFI boot entry

Because we're not using the default path, we must tell the motherboard where to boot Limine via efibootmgr:

emerge --ask sys-boot/efibootmgr
# Create a boot entry named "Gentoo Limine"
# -d: disk device (e.g., /dev/nvme0n1)
# -p: partition number (e.g., 1)
# -L: label name
# -l: loader path (Windows-style backslash)
efibootmgr --create --disk /dev/nvme0n1 --part 1 --label "Gentoo Limine" --loader '\EFI\Gentoo\limine.efi'

Advanced Settings: Encryption Support (Encrypted Users Only) - Click to Expand

Step 1: Install LUKS dependencies for your init system

# systemd profile:
mkdir -p /etc/portage/package.use
echo "sys-apps/systemd cryptsetup" >> /etc/portage/package.use/fde
emerge --ask --oneshot sys-apps/systemd sys-kernel/dracut

# OpenRC profile:
emerge --ask sys-fs/cryptsetup sys-kernel/dracut

Step 2: Generate initramfs with the crypt module

Edit /etc/dracut.conf.d/luks.conf:

Note: Change btrfs to xfs or ext4 based on your root filesystem.

# systemd profile:
add_dracutmodules+=" btrfs systemd crypt dm "
# OpenRC profile:
add_dracutmodules+=" btrfs crypt dm "

Regenerate initramfs:

# gentoo-kernel-bin:
emerge --ask --config sys-kernel/gentoo-kernel-bin

# Genkernel or a manually built kernel:
dracut --kver $(make -C /usr/src/linux -s kernelrelease) --force

Step 3: Get LUKS partition UUID

# Get the UUID of the LUKS encrypted container (NOT the filesystem UUID inside it)
blkid /dev/nvme0n1p4

Output example (look for the line with TYPE="crypto_LUKS"):

/dev/nvme0n1p4: UUID="a1b2c3d4-e5f6-7890-abcd-ef1234567890" TYPE="crypto_LUKS" ...

Use the LUKS UUID in the blkid output above in the following configuration files; replace the example value with your own system's actual output rather than copying it.

Step 4: Configure boot kernel parameters

GRUB (/etc/default/grub):
Edit /etc/default/grub and set GRUB_CMDLINE_LINUX to:
```
# Full example (replace UUID with your actual UUID)
GRUB_CMDLINE_LINUX="rd.luks.uuid=<LUKS-UUID> rd.luks.allow-discards root=UUID=<decrypted-root-filesystem-UUID> rootfstype=btrfs"
```
Parameter explanation:
- rd.luks.uuid=<UUID>: UUID of the LUKS encrypted partition (get with blkid /dev/nvme0n1p4).
- rd.luks.allow-discards: Allow SSD TRIM commands through the encryption layer (improves SSD performance).
- root=UUID=<UUID>: UUID of the decrypted root filesystem (get with blkid /dev/mapper/cryptroot).
- rootfstype=btrfs: Modify as appropriate (e.g., xfs, ext4).
Remember to run grub-mkconfig -o /boot/grub/grub.cfg after modifying.
systemd-boot:
```
printf 'rd.luks.name=<LUKS-UUID>=cryptroot root=/dev/mapper/cryptroot rootfstype=btrfs rd.luks.allow-discards\n' > /etc/kernel/cmdline
emerge --ask --config sys-kernel/gentoo-kernel-bin
```
Parameter explanation:
- rd.luks.name=<LUKS-UUID>=cryptroot: Specify the LUKS partition UUID and map it as cryptroot.
- root=/dev/mapper/cryptroot: Specify the decrypted root partition device.
- rootfstype=btrfs: Modify as appropriate (e.g., xfs, ext4).

Limine (limine.conf):

/Gentoo Linux
    protocol: linux
    kernel_path: boot():/<vmlinuz-filename>
    module_path: boot():/<initramfs-filename>
    cmdline: rd.luks.name=<LUKS-UUID>=cryptroot root=/dev/mapper/cryptroot rootfstype=btrfs rd.luks.allow-discards

Parameter explanation:

rd.luks.name: Same as above, specifies the LUKS partition UUID.
root: Specifies the decrypted root partition device.
rootfstype=btrfs: Modify as appropriate (e.g., xfs, ext4).

Only perform this step when choosing LUKS in the encrypted-partition workflow in section 3.

11. Final Steps
#

11.1 Final Checklist
#

emerge --info runs without errors
UUIDs in /etc/fstab are correct (verify again with blkid)
Root and regular user passwords have been set
grub-mkconfig has been run or bootctl/Limine configuration is complete
If using LUKS, confirm initramfs includes cryptsetup

11.2 Exit Chroot and Reboot
#

After confirming everything is correct, exit the chroot environment and unmount:

exit
umount -l /mnt/gentoo/dev{/shm,/pts,}
umount -R /mnt/gentoo
swapoff -a
reboot

Congratulations! You have completed the basic Gentoo installation.

Next step: Desktop Configuration

Article Overview#

About This Guide#

What is Gentoo?#

Disk Space Requirements#

Pre-Installation Checklist#

Guide Overview#

0. Prepare Installation Media#

0.1 Download Gentoo ISO#

0.2 Create Bootable USB#

1. Enter Live Environment and Connect to Network#

1.1 Wired Network (manual)#

1.2 Wireless Network (manual)#

2. Plan Disk Partitioning#

What is the EFI System Partition (ESP)?#

Recommended Partition Scheme (UEFI)#

cfdisk Practical Example (Recommended)#

3. Create Filesystems and Mount#

3.1 Format#

3.2 Mount (XFS example)#

4. Download Stage3 and Enter chroot#

4.1 Choose Stage3#

4.2 Download and Extract#

4.3 Copy DNS and Mount Pseudo-Filesystems#

4.4 Enter chroot#

5. Initialize Portage and make.conf#

5.1 Sync Tree#

5.2 make.conf Example#

5.3 Binary Packages (binhost) (Optional)#

Confirm the repository configuration#

Choose an instruction-set level#

Enable automatic use#

Confirm that a binary package is used#

Related options#

Signature verification#

6. Profile, System Settings & Localization#

6.1 Choose Profile#

6.2 Timezone and Locale#

6.3 Hostname and Network Configuration#

6.4 Configure fstab#

Method A: Auto-generate with genfstab (Recommended)#

Method B: Manual Edit#

7. Kernel and Firmware#

7.1 Install Firmware and Microcode#

7.2 Quick Option: Pre-compiled Kernel#

8. Base Tools#

8.1 System Service Tools#

8.2 Filesystem Tools#

9. Create Users and Permissions#

10. Install Bootloader#

10.1 Option A: GRUB (Recommended/Standard)#

10.2 Option B: systemd-boot (Minimal/Fast)#

10.3 Option C: Limine (Modern/Flexible)#

11. Final Steps#

11.1 Final Checklist#

11.2 Exit Chroot and Reboot#

Related

Article Overview
#

About This Guide
#

What is Gentoo?
#

Disk Space Requirements
#

Pre-Installation Checklist
#

Guide Overview
#

0. Prepare Installation Media
#

0.1 Download Gentoo ISO
#

0.2 Create Bootable USB
#

1. Enter Live Environment and Connect to Network
#

1.1 Wired Network (manual)
#

1.2 Wireless Network (manual)
#

2. Plan Disk Partitioning
#

What is the EFI System Partition (ESP)?
#

Recommended Partition Scheme (UEFI)
#

cfdisk Practical Example (Recommended)
#

3. Create Filesystems and Mount
#

3.1 Format
#

3.2 Mount (XFS example)
#

4. Download Stage3 and Enter chroot
#

4.1 Choose Stage3
#

4.2 Download and Extract
#

4.3 Copy DNS and Mount Pseudo-Filesystems
#

4.4 Enter chroot
#

5. Initialize Portage and make.conf
#

5.1 Sync Tree
#

5.2 make.conf Example
#

5.3 Binary Packages (binhost) (Optional)
#

Confirm the repository configuration
#

Choose an instruction-set level
#

Enable automatic use
#

Confirm that a binary package is used
#

Related options
#

Signature verification
#

6. Profile, System Settings & Localization
#

6.1 Choose Profile
#

6.2 Timezone and Locale
#

6.3 Hostname and Network Configuration
#

6.4 Configure fstab
#

Method A: Auto-generate with genfstab (Recommended)
#

Method B: Manual Edit
#

7. Kernel and Firmware
#

7.1 Install Firmware and Microcode
#

7.2 Quick Option: Pre-compiled Kernel
#

8. Base Tools
#

8.1 System Service Tools
#

8.2 Filesystem Tools
#

9. Create Users and Permissions
#

10. Install Bootloader
#

10.1 Option A: GRUB (Recommended/Standard)
#

10.2 Option B: systemd-boot (Minimal/Fast)
#

10.3 Option C: Limine (Modern/Flexible)
#

11. Final Steps
#

11.1 Final Checklist
#

11.2 Exit Chroot and Reboot
#