Portage & emerge

Portage is Gentoo's package management system — a collection of ~20,000 "ebuilds" (shell scripts) that describe how to fetch, configure, compile, and install software. The emerge command is your interface to Portage.

How emerge Works

emerge Command Reference

The Portage Tree Structure

The Portage tree lives at /var/db/repos/gentoo/ and contains ebuilds organized by category:

Ebuilds

An ebuild is a bash script that tells Portage everything about a package: where to fetch the source, what to configure, how to compile, and where to install. Here's a simplified example:

# dev-libs/hello/hello-2.12.1.ebuild
DESCRIPTION="GNU Hello — classic hello world program"
HOMEPAGE="https://www.gnu.org/software/hello/"
SRC_URI="mirror://gnu/hello/${P}.tar.gz"

LICENSE="GPL-3+"
SLOT="0"
KEYWORDS="~amd64 ~arm64 ~x86"
IUSE="nls"

DEPEND="nls? ( sys-devel/gettext )"

src_configure() {
    econf $(use_enable nls)
}

src_compile() {
    emake
}

src_install() {
    emake DESTDIR="${D}" install
}

Slots

Gentoo's slot system allows multiple versions of the same package to coexist. For example, dev-lang/python:3.11 and dev-lang/python:3.12 can both be installed simultaneously. This is critical for systems that need multiple Python or Ruby versions without conflicts.

Binary Packages (Binpkgs)

Since Gentoo 23.0, official binary packages are available for common configurations. You can mix binary and source packages: install Firefox as a binary but compile your kernel by hand. Use emerge --getbinpkg or set FEATURES="getbinpkg" in make.conf to enable this.

USE Flags

USE flags are Gentoo's most powerful feature. They are keywords that tell Portage which optional features to compile into packages. Setting USE flags is how you build a system that does exactly what you want — no more, no less.

How USE Flags Work

Every package declares what USE flags it supports in its ebuild via the IUSE variable. When you enable a USE flag, the package is compiled with that feature. Disable it, and the dependency and feature are omitted entirely from the binary.

Global vs. Package-Specific Flags

Global USE flags in /etc/portage/make.conf apply to all packages. Package-specific flags in /etc/portage/package.use override them per-package:

# /etc/portage/package.use
www-client/firefox       pgo lto -telemetry
media-video/mpv          dvd bluray cdda lua
dev-lang/python:3.12     sqlite tk
sys-libs/zlib            minizip

Viewing Available USE Flags

Common USE Flags

CFLAGS — Compile Flags

Beyond USE flags, CFLAGS and CXXFLAGS in make.conf control GCC optimization settings:

# /etc/portage/make.conf — aggressive optimization example
CFLAGS="-march=native -O2 -pipe"
CXXFLAGS="${CFLAGS}"
MAKEOPTS="-j$(nproc)"  # parallel compile jobs = CPU core count

# USE flags
USE="X alsa bluetooth lto -doc -debug -gnome -kde"

# CPU features (Portage auto-detects from CPU)
CPU_FLAGS_X86="aes avx avx2 f16c fma3 mmx mmxext pclmul popcnt rdrand sse sse2 sse3 sse4_1 sse4_2 ssse3"

Installing Gentoo

Gentoo's installation is famously involved. There is no graphical installer — you do everything by hand in a terminal. This is intentional: the process teaches you exactly how a Linux system is built.

Why Gentoo Install is Legendary

The Gentoo installation process is a rite of passage in the Linux community. A typical install takes anywhere from 3 hours (on modern hardware with binary packages) to several days (compiling everything on a slow machine, including the kernel). The Gentoo Handbook covers every step in meticulous detail.

Installation Steps

1. Boot a live environment (minimal install CD, or any Linux live USB) Verify the ISO signature: gpg --verify install-amd64-minimal.iso.asc
2. Prepare the disks with fdisk or parted Typical layout: EFI partition (512MB), swap (optional), root ext4/btrfs/xfs
3. Format and mount the partitions mkfs.fat -F32 /dev/sda1 && mkfs.ext4 /dev/sda3 && mount /dev/sda3 /mnt/gentoo
4. Download the Stage 3 tarball Choose your profile: openrc, systemd, hardened, musl, desktop, or server
5. Verify and extract Stage 3 tar xpvf stage3-*.tar.xz --xattrs-include='*.*' --numeric-owner -C /mnt/gentoo
6. Configure /mnt/gentoo/etc/portage/make.conf Set CFLAGS, USE flags, MAKEOPTS, mirrors, CPU_FLAGS_X86
7. Mount and chroot into the new system mount --bind /proc /mnt/gentoo/proc && chroot /mnt/gentoo /bin/bash
8. Sync the Portage tree emerge-webrsync (bootstrap) then emerge --sync for latest
9. Choose a profile eselect profile list — pick desktop/gnome, server, hardened, etc.
10. Update the @world set emerge --ask --verbose --update --deep --newuse @world — rebuilds everything against new USE flags
11. Configure timezone and locale echo "America/New_York" > /etc/timezone && emerge --config sys-libs/timezone-data
12. Configure the Linux kernel emerge sys-kernel/gentoo-sources, then make menuconfig — the most complex step
13. Compile and install the kernel make -j$(nproc) && make modules_install && make install
14. Generate the initramfs (if needed) emerge sys-kernel/dracut && dracut --kver $(uname -r)
15. Configure /etc/fstab Map partitions by UUID to mountpoints: root, boot, swap
16. Configure networking hostname, /etc/hosts, netifrc or NetworkManager depending on profile
17. Install a bootloader emerge sys-boot/grub && grub-install /dev/sda && grub-mkconfig -o /boot/grub/grub.cfg
18. Set the root password and create a user passwd && useradd -m -G wheel,audio,video yourusername
19. Reboot into your new Gentoo system Remove the live USB, cross fingers, and enjoy your custom-compiled OS

Stage 3 Tarball

The Stage 3 is a minimal pre-compiled Gentoo base system — the starting point for every installation. It contains the C library, compiler, shell, and basic tools needed to bootstrap Portage. From Stage 3, you build everything else. Historically Gentoo also had Stage 1 and Stage 2 (compiling the C library and compiler from scratch), but these were dropped in favor of Stage 3 for all normal installations.

genkernel

For those who don't want to configure the kernel manually, genkernel automates the process — building a generic kernel with most drivers enabled, similar to what binary distros ship. Hardcore Gentoo users consider this "cheating," but it works perfectly well for most systems.

Portage Profiles

A profile is a collection of pre-set USE flags, CFLAGS, and package masks designed for a particular use case. Switching profiles is how you tell Portage what kind of system you're building:

Gentoo vs. Other Distros

Every Linux distribution makes trade-offs. Gentoo trades installation time and complexity for control, customization, and understanding. Here's how it compares.

Feature Comparison

Package Manager Comparison

Portage vs. Nix

Gentoo and NixOS represent two opposite philosophies of ultimate Linux customization. Portage optimizes through compilation and USE flags — you build what you need for your hardware. Nix optimizes through functional package management and reproducibility — every build is deterministic and rollback is trivial. Both are used by Linux power users who want total control; they just take different routes to get there.

Gentoo History

From a personal project called Enoch Linux to one of the most influential Linux distributions ever made, Gentoo's history is a story of radical ideas, community growth, and lasting impact.

Daniel Robbins

Daniel Robbins is the creator of Gentoo Linux. After leaving Gentoo and briefly joining Microsoft (2004), he went on to co-found Funtoo Linux in 2008 — a Gentoo fork with opinionated defaults and git-based ebuilds. Funtoo later pivoted to "Macaroni OS" as a binary-focused Funtoo spin. Robbins has remained active in open source throughout, writing tutorials and documenting Linux systems.

Legacy

Gentoo's lasting contributions to Linux: