Gentoo Linux on Raspberry Pi: Installation, USE Flags, and Cross-Compilation

Gentoo Linux on Raspberry Pi gives you a source-based system built entirely from your own compiler flags, USE flag selections, and kernel configuration. Nothing runs that you did not explicitly include. The cost is time: compiling a full @world set natively on a Pi 4 takes 12 to 24 hours. Cross-compilation from an x86 host cuts that to under two hours. This guide covers architecture selection, SD card preparation, the critical make.conf settings that govern everything that follows, cross-compilation setup with distcc, and the troubleshooting steps specific to ARM Gentoo installs.

Last tested: Gentoo stage3-arm64-openrc | May 2025 | Raspberry Pi 4 Model B (8GB) | Portage 3.0.65, GCC 14.1, kernel 6.6.28-gentoo-r1

Hardware and Architecture Selection for Gentoo Linux on Raspberry Pi

Pi 4 (4GB or 8GB) is the correct choice for a Gentoo build machine. The 4-core Cortex-A72 handles long compile jobs without throttling under proper cooling. The 2GB variant is usable but will struggle during kernel compilation with -j5. Pi 3 works but its Cortex-A53 cores are slower and compilations take proportionally longer. Pi Zero is not viable for native compilation of any substantial package set. For a Pi 4 vs Pi 5 hardware comparison, see Raspberry Pi 5 vs Pi 4: The Honest Breakdown.

Use the arm64 (AArch64) stage3 tarball. The 32-bit ARM stage3 still exists but there is no reason to use it on Pi 3 or Pi 4 hardware unless a specific package requires 32-bit userspace. The arm64 tarball filename follows the pattern stage3-arm64-openrc-YYYYMMDD.tar.xz. Download it from https://www.gentoo.org/downloads/ or a nearby mirror. Verify the SHA512 checksum against the .DIGESTS file before extracting.

Storage: a USB SSD is strongly preferred over an SD card. Gentoo compilation involves sustained random writes to temporary build directories. SD cards degrade quickly under this pattern and compilation errors from write failures are difficult to distinguish from actual build problems. A 32GB USB SSD is sufficient for a standard Gentoo install with common packages.

Preparing the SD Card and Bootstrapping Gentoo Linux on Raspberry Pi

These steps are performed on a Linux host machine, not the Pi. You will write to the SD card or USB SSD from the host, then move the media to the Pi for first boot.

Identify the target device (/dev/sdX or /dev/mmcblkX) and partition it:

sudo fdisk /dev/sdX

# Inside fdisk:
# o  - create new DOS partition table
# n  - new partition, primary, partition 1, first sector default, +256M
# t  - set type to b (W95 FAT32)
# n  - new partition, primary, partition 2, first sector default, last sector default
# w  - write and exit

Format and mount the partitions:

sudo mkfs.vfat -F 32 /dev/sdX1
sudo mkfs.ext4 /dev/sdX2
sudo mount /dev/sdX2 /mnt/gentoo
sudo mkdir /mnt/gentoo/boot
sudo mount /dev/sdX1 /mnt/gentoo/boot

Extract the stage3 tarball to the root partition:

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

Copy the Raspberry Pi boot firmware files. The Pi requires proprietary firmware blobs in the FAT32 boot partition. Clone the firmware repository on the host:

git clone --depth=1 https://github.com/raspberrypi/firmware.git
sudo cp firmware/boot/{bootcode.bin,start*.elf,fixup*.dat,*.dtb} /mnt/gentoo/boot/
sudo cp firmware/boot/overlays /mnt/gentoo/boot/overlays -r

Create a minimal /mnt/gentoo/boot/config.txt for Pi 4:

arm_64bit=1
kernel=kernel8.img
enable_uart=1

Create /mnt/gentoo/boot/cmdline.txt:

root=/dev/mmcblk0p2 rootfstype=ext4 rootwait console=ttyS0,115200 console=tty1

You need a kernel. The two options are the Raspberry Pi Foundation’s pre-built kernel or a self-compiled kernel. For a first Gentoo install on Pi, use the pre-built kernel to get a bootable system before investing time in a custom build:

sudo cp firmware/boot/kernel8.img /mnt/gentoo/boot/

Expected result: The Pi boots to a login prompt. Serial console output appears on the UART pins if a USB-to-serial adapter is connected. If the screen is blank after the rainbow splash, check config.txt values and confirm kernel8.img is present in the boot partition. Use ls /mnt/gentoo/boot/ on the host to verify before removing the media.

Configuring make.conf, USE Flags, and Portage

After first boot, the first file to configure is /etc/portage/make.conf. Every package compiled by Portage reads this file. Getting it right before any emerge command avoids recompiling the entire system later.

A working make.conf for Pi 4 arm64:

CHOST="aarch64-unknown-linux-gnu"
CFLAGS="-O2 -pipe -march=armv8-a+crc -mtune=cortex-a72"
CXXFLAGS="${CFLAGS}"

# Use all 4 cores plus 1 for link jobs
MAKEOPTS="-j5"

# Global USE flags -- keep minimal until packages are known
USE="systemd -X -gtk -gnome -kde -qt5 -pulseaudio"

# Accept only stable packages
ACCEPT_KEYWORDS="arm64"

# Mirrors -- update to a mirror near you
GENTOO_MIRRORS="https://mirrors.kernel.org/gentoo/"

# Portage features
FEATURES="parallel-fetch"

The -march=armv8-a+crc flag targets the Cortex-A72’s ARMv8.0 instruction set with CRC extensions. Using -march=native does not work reliably on ARM cross-compilation scenarios and is unnecessary here since the target architecture is fixed. The -O2 optimisation level is the correct default. -O3 is not beneficial for most packages and occasionally produces incorrect code.

USE flags control which features are compiled into each package. Setting them globally in make.conf applies to every package. Per-package overrides go in /etc/portage/package.use/. A lean starting set for a headless Pi server:

# /etc/portage/package.use/server
# Enable SSL and IPv6 system-wide for server use
net-misc/openssh X509
dev-libs/openssl -bindist

# Example: enable Python 3.12 target system-wide
*/* PYTHON_TARGETS: python3_12
*/* PYTHON_SINGLE_TARGET: python3_12

Select the correct Gentoo profile. For a Pi 4 headless server, the default arm64 profile is appropriate:

eselect profile list
eselect profile set default/linux/arm64/23.0

Sync the Portage tree and perform the initial world build. This step takes the longest on native compilation:

emerge --sync
emerge --ask --verbose --update --deep --newuse @world

Expected result: Portage calculates a dependency graph and presents the package list for confirmation. On a fresh stage3 with a minimal USE set this is typically 50 to 150 packages. Native compilation on Pi 4 with MAKEOPTS="-j5" takes 2 to 8 hours depending on which packages are in the set. If any package fails to compile, read the build log at /var/tmp/portage/<category>/<package>/temp/build.log before retrying.

Cross-Compilation and Performance on Gentoo Linux Raspberry Pi

Native compilation on a Pi 4 is practical for maintenance but painful for the initial world build or any large package like GCC, LLVM, or Qt. Cross-compilation from an x86 host using crossdev and distcc reduces multi-hour builds to under 30 minutes.

Setting up crossdev on the x86 host. The host must also be running Gentoo, or at minimum have a Gentoo Portage tree available. Install crossdev and build the arm64 cross-compiler:

# On x86 Gentoo host:
emerge --ask sys-devel/crossdev
crossdev --stable -t aarch64-unknown-linux-gnu

This builds a complete cross-compiler toolchain: binutils, GCC, Linux headers, and glibc targeted at aarch64-unknown-linux-gnu. It takes 20 to 40 minutes on a modern x86 machine. The resulting compiler is at /usr/bin/aarch64-unknown-linux-gnu-gcc.

Setting up distcc for distributed compilation. distcc allows the Pi to offload compilation jobs to the x86 host transparently. On the x86 host:

# On x86 host:
emerge --ask sys-devel/distcc
distccd --daemon --allow 192.168.1.0/24 \
  --log-file /var/log/distccd.log \
  --user distcc

On the Pi, configure Portage to use distcc:

# On Pi -- add to /etc/portage/make.conf:
FEATURES="distcc"
MAKEOPTS="-j8"   # Higher than core count since jobs run on remote host

# Configure distcc hosts:
distcc-config --set-hosts "192.168.1.x/4,lzo"

Expected result: Running emerge --ask gcc shows compilation output where individual files compile on the x86 host. Verify with distccmon-text 1 on the Pi during a build. Slot counts in the output should show jobs running on the remote host address. If all slots show localhost, distcc is not routing jobs correctly; check that distccd is running on the host and that the Pi’s firewall allows port 3632.

Kernel compilation. A custom kernel removes unnecessary drivers, reduces boot time, and enables hardware-specific options. Gentoo’s preferred method is sys-kernel/gentoo-sources with manual menuconfig. For Pi hardware, start with the Raspberry Pi Foundation’s kernel config as a base:

emerge --ask sys-kernel/gentoo-sources
cd /usr/src/linux

# Copy Pi Foundation config as starting point:
wget https://raw.githubusercontent.com/raspberrypi/linux/rpi-6.6.y/arch/arm64/configs/bcm2711_defconfig \
  -O .config

make olddefconfig
make menuconfig   # Review and adjust
make -j5 Image modules dtbs
make modules_install
cp arch/arm64/boot/Image /boot/kernel8.img
cp arch/arm64/boot/dts/broadcom/bcm271*.dtb /boot/

Expected result: The Pi boots the new kernel. Confirm with uname -r. If the Pi does not boot, connect a serial console (UART pins, 115200 baud) to read early kernel output. Missing device tree blobs and missing initramfs support are the two most common boot failures after a custom kernel build.

Troubleshooting Gentoo Linux on Raspberry Pi

Gentoo on Pi fails in specific, diagnosable ways. This section addresses the problems that actually occur rather than generic Linux troubleshooting.

Boot fails silently after rainbow splash. The Pi bootloader loaded but the kernel did not start. Check that kernel8.img is present in the FAT32 boot partition, that config.txt has arm_64bit=1, and that cmdline.txt points to the correct root device. Use blkid to get the correct UUID and use root=PARTUUID=... syntax if the device node is unreliable. Connect a serial console for early boot output: enable_uart=1 in config.txt, then connect a USB-to-serial adapter to the Pi’s UART pins (GPIO14 TX, GPIO15 RX, GND) at 115200 baud.

Compilation fails mid-build with out-of-memory errors. Large packages (GCC, LLVM, Chromium) require more RAM than a Pi 4 has available for parallel compilation. Add swap: fallocate -l 4G /swapfile && chmod 600 /swapfile && mkswap /swapfile && swapon /swapfile. Add it to /etc/fstab for persistence. Alternatively reduce MAKEOPTS to -j2 for memory-intensive packages using a per-package override in /etc/portage/env/.

emerge reports circular dependencies or slot conflicts. This is normal on a freshly synced tree and usually resolves with emerge --ask --oneshot sys-libs/glibc followed by emerge --ask @world again. For persistent conflicts, read the full output of emerge --info and check the Gentoo bug tracker for known issues with the affected package version on arm64.

Wi-Fi not working. Raspberry Pi OS handles firmware loading automatically. On Gentoo, the Broadcom Wi-Fi firmware must be installed manually from the sys-firmware/raspberrypi-wifi-ucode package, or by copying the relevant firmware blob from a Raspberry Pi OS install. The Pi 4’s CYW43455 chip needs brcmfmac43455-sdio.bin and brcmfmac43455-sdio.txt in /lib/firmware/brcm/. Do not use rpi-update on Gentoo; firmware is managed through Portage with sys-boot/raspberrypi-firmware.

SD card corruption after long compilation runs. Gentoo compilation generates enormous amounts of write I/O to /var/tmp/portage/. Move the build directory to a RAM disk or separate USB SSD: add PORTAGE_TMPDIR="/mnt/usb/portage-tmp" to make.conf, pointing to a path on faster or more durable storage. This also speeds up compilation by eliminating SD card write latency. For a full read-only root filesystem approach, see Raspberry Pi Read-Only Root Filesystem Setup.

FAQ

How long does a Gentoo world build take on Raspberry Pi?

Native compilation of a minimal headless @world set on a Pi 4 with MAKEOPTS="-j5" takes 8 to 24 hours depending on which packages are selected. A desktop environment like XFCE adds another 12 to 48 hours. Cross-compilation via distcc from an x86 host reduces the same minimal build to 1 to 3 hours. For any serious Gentoo work on Pi, setting up cross-compilation before the initial world build is worth the 30 to 60 minutes of host setup time.

Which Gentoo stage3 tarball should I use for Raspberry Pi?

Use stage3-arm64-openrc for Pi 3, Pi 4, and Pi 5. This is the 64-bit AArch64 tarball with OpenRC as the init system. Avoid the systemd variant unless you specifically need systemd; OpenRC is lighter and better documented for embedded ARM use. The musl variant exists for advanced users who want a musl libc system but has reduced package compatibility. Download from https://www.gentoo.org/downloads/ and always verify the SHA512 checksum against the .DIGESTS file before extraction.

What USE flags should I set for a headless Raspberry Pi Gentoo server?

Start with negating everything graphical: USE="-X -gtk -gnome -kde -qt5 -pulseaudio -alsa" in make.conf. Add positive flags for what the server actually needs: ssl, ipv6, python, and any application-specific flags. Keep the global USE set minimal and use per-package overrides in /etc/portage/package.use/ for packages that need specific features. Changing global USE flags after a full world build requires rebuilding every affected package, so getting the initial set right saves time.

Does Gentoo use systemd or OpenRC on Raspberry Pi?

The standard Gentoo stage3 for ARM uses OpenRC, not systemd. OpenRC is a dependency-based init system that is lighter than systemd and has been Gentoo’s default init system for over a decade. Service files live in /etc/init.d/ and are enabled with rc-update add <service> default. A systemd stage3 variant exists if you specifically need systemd, but most Gentoo Pi documentation assumes OpenRC. Portage manages both init systems through USE flags, but mixing them on a single install is not supported.

How do I update firmware on Gentoo Linux on Raspberry Pi?

Through Portage, not through rpi-update. The rpi-update script is a Raspberry Pi OS tool that pulls directly from the Foundation’s GitHub and bypasses Portage entirely, which breaks package management on Gentoo. Install the firmware package through Portage instead: emerge --ask sys-boot/raspberrypi-firmware. This installs updated firmware blobs, device trees, and kernel images to /boot in a way that Portage can track, roll back, and manage as dependencies. Wi-Fi firmware is handled separately through sys-firmware/raspberrypi-wifi-ucode.

References:

• Gentoo ARM wiki: wiki.gentoo.org/wiki/Raspberry_Pi
• Gentoo make.conf reference: wiki.gentoo.org/wiki//etc/portage/make.conf
• Gentoo crossdev guide: wiki.gentoo.org/wiki/Crossdev
• Gentoo distcc guide: wiki.gentoo.org/wiki/Distcc
• Raspberry Pi firmware repository: github.com/raspberrypi/firmware

---

About the Author

Chuck Wilson has been programming and building with computers since the Tandy 1000 era. His professional background includes CAD drafting, manufacturing line programming, and custom computer design. He runs PidiyLab in retirement, documenting Raspberry Pi and homelab projects that he actually deploys and maintains on real hardware. Every article on this site reflects hands-on testing on specific hardware and OS versions, not theoretical walkthroughs.

Last tested hardware: Raspberry Pi 4 Model B (8GB). Last tested OS: Gentoo stage3-arm64-openrc. Portage 3.0.65, GCC 14.1, kernel 6.6.28-gentoo-r1.