Gentoo is a source-based Linux distribution for advanced users who want complete control over their system. With its Portage package management system and USE flags, Gentoo allows you to compile every package optimized specifically for your hardware.
⚠️ Note: Gentoo is not recommended for beginners. It requires significant Linux knowledge, patience for compilation times, and willingness to troubleshoot.
| Principle | Description |
|---|---|
| Choice | Complete control over system configuration |
| Optimization | Compile packages for your specific CPU |
| Simplicity | Minimal base system, build up as needed |
| Flexibility | Configure every aspect via USE flags |
| Community | Knowledgeable, helpful community |
| Resource | Description | URL |
|---|---|---|
| Gentoo Handbook | Official installation & administration guide | wiki.gentoo.org/wiki/Handbook |
| Gentoo Wiki | Comprehensive documentation | wiki.gentoo.org |
| Portage Guide | Package management documentation | wiki.gentoo.org/wiki/Portage |
| USE Flag Guide | Understanding USE flags | wiki.gentoo.org/wiki/USE_flags |
| Resource | Description | URL |
|---|---|---|
| Gentoo Forums | Active community forums | forums.gentoo.org |
| Gentoo Reddit | Community subreddit | r/gentoo |
| IRC | Real-time support | #gentoo on Libera.Chat |
| Discord | Community server | Gentoo Discord |
| Mailing Lists | Development & user lists | lists.gentoo.org |
| Matrix | Matrix room | #gentoo:matrix.org |
| Resource | Purpose | URL |
|---|---|---|
| Bugzilla | Report bugs | bugs.gentoo.org |
| GitHub | Source code | github.com/gentoo |
| GitLab | Infrastructure | gitlab.com/gentoo |
| Packages | Package database | packages.gentoo.org |
| Overlays | User repositories | github.com/gentoo-mirror |
# Sync portage tree
sudo emerge --sync
# Update world (all installed packages)
sudo emerge --update --deep --newuse @world
# Install a package
sudo emerge package-name
# Remove a package
sudo emerge --unmerge package-name
# Search for packages
emerge --search keyword
emerge --searchdesc "description"
# Show package info
emerge --info package-name
# Preview installation (dry run)
sudo emerge --pretend package-name
# Check for broken dependencies
sudo emerge --depclean --pretend
# Compile with specific USE flags for one package
USE="flag1 flag2" sudo emerge package-name
# Compile without specific USE flags
USE="-flag1 -flag2" sudo emerge package-name
# Download source only
sudo emerge --fetchonly package-name
# Reinstall package with current USE flags
sudo emerge --oneshot --verbose package-name
# See what will be installed
sudo emerge --pretend --verbose package-name
# Cancel current emerge
sudo kill -INT $(pidof emerge)
| File | Purpose |
|---|---|
/etc/portage/make.conf |
Global Portage settings |
/etc/portage/package.use |
Per-package USE flags |
/etc/portage/package.accept_keywords |
Accept unstable packages |
/etc/portage/package.mask |
Prevent specific versions |
/etc/portage/repos.conf |
Repository configuration |
USE flags control optional features and dependencies:
# View current USE flags
emerge --info | grep USE
# View USE flags for specific package
emerge --info package-name | grep USE
# Search for USE flag description
equery u package-name
# Check what USE flags affect
emerge --pretend --verbose package-name
| USE Flag | Description |
|---|---|
| X | X11 support |
| gtk | GTK toolkit support |
| qt | Qt toolkit support |
| ssl | SSL/TLS encryption support |
| python | Python bindings |
| java | Java support |
| mysql | MySQL database support |
| postgres | PostgreSQL support |
| ldap | LDAP authentication |
| kerberos | Kerberos authentication |
| pulseaudio | PulseAudio sound support |
| bluetooth | Bluetooth support |
| wifi | Wireless networking |
| ipv6 | IPv6 support |
| systemd | systemd support |
Global (make.conf):
# /etc/portage/make.conf
USE="X gtk ssl python -gnome -kde"
Per-Package (package.use):
# /etc/portage/package.use/www-client-firefox
www-client/firefox pulseaudio -jack
# Install kernel sources
sudo emerge gentoo-sources
# Configure kernel
cd /usr/src/linux
sudo make menuconfig
# Compile and install kernel
sudo make && sudo make modules_install && sudo make install
# Update bootloader (GRUB example)
sudo grub-mkconfig -o /boot/grub/grub.cfg
OpenRC (Default):
# List services
rc-status
# Start service
sudo rc-service service-name start
# Enable service at boot
sudo rc-update add service-name default
# Restart service
sudo rc-service service-name restart
systemd (Optional):
# Install systemd
sudo emerge systemd
# Enable systemd
# Follow wiki.gentoo.org/wiki/Systemd
# Manage services
sudo systemctl start service-name
sudo systemctl enable service-name
# List available profiles
eselect profile list
# Select profile
sudo eselect profile set <number>
# View current profile
eselect profile show
# Update profile
sudo emerge --update --newuse --deep @world
# /etc/portage/make.conf
# Example for Intel Coffee Lake
CFLAGS="-march=skylake -O2 -pipe"
CXXFLAGS="${CFLAGS}"
# Example for AMD Ryzen
CFLAGS="-march=znver2 -O2 -pipe"
# Example for generic x86-64
CFLAGS="-march=x86-64 -O2 -pipe"
# /etc/portage/make.conf
# Set to number of CPU cores + 1
MAKEOPTS="-j9" # For 8-core CPU
# With RAM limitations
MAKEOPTS="-j4 -l8" # 4 jobs, max load 8
# /etc/portage/make.conf
# NVIDIA
VIDEO_CARDS="nvidia"
# AMD
VIDEO_CARDS="amdgpu radeonsi"
# Intel
VIDEO_CARDS="intel i965 iris"
Official Handbook:
Common Installation Issues:
# Check network interface
ip link
# Bring up interface
sudo ip link set eth0 up
# DHCP
sudo dhcpcd eth0
# Static IP
sudo ip addr add 192.168.1.100/24 dev eth0
sudo ip route add default via 192.168.1.1
# List disks
lsblk
fdisk -l
# Create partitions
fdisk /dev/sda
# Create filesystems
mkfs.ext4 /dev/sda2
mkswap /dev/sda3
swapon /dev/sda3
# Mount filesystems
mount /dev/sda2 /mnt/gentoo
mount --rbind /proc /mnt/gentoo/proc
mount --rbind /sys /mnt/gentoo/sys
mount --make-rslave /mnt/gentoo/proc
mount --make-rslave /mnt/gentoo/sys
# Chroot
chroot /mnt/gentoo /bin/bash
source /etc/profile
export PS1="(chroot) ${PS1}"
We provide professional Gentoo Linux consulting for advanced users and enterprises:
Contact us: linux-server-admin.com/contact
| Book | Author | Level |
|---|---|---|
| Gentoo Linux Handbook | Gentoo Community | All levels |
| Linux From Scratch | Gerard Beekmans | Advanced |
| The Gentoo Handbook | Various | Intermediate+ |
| Channel | Focus |
|---|---|
| Gentoo Linux | Official tutorials |
| DistroTube | Gentoo installation and usage |
| Craft Computing | Gentoo performance builds |
# Check available RAM
free -h
# Reduce MAKEOPTS if low on RAM
# Edit /etc/portage/make.conf
MAKEOPTS="-j2"
# Check for missing dependencies
sudo emerge --update --deep @world
# Check logs
cat /var/log/portage/package-name:timestamp.log
# Check for broken dependencies
sudo emerge --depclean --pretend
# Fix broken packages
sudo emerge --update --deep --newuse @world
# Remove orphaned packages
sudo emerge --depclean
# Check USE conflicts
sudo emerge --pretend --verbose package-name
# Resolve conflicts
# Edit /etc/portage/package.use
# Boot from live media
# Mount root partition
mount /dev/sda2 /mnt/gentoo
# Mount boot if separate
mount /dev/sda1 /mnt/gentoo/boot
# Chroot
mount --rbind /proc /mnt/gentoo/proc
mount --rbind /sys /mnt/gentoo/sys
chroot /mnt/gentoo /bin/bash
# Rebuild kernel modules
cd /usr/src/linux
make && make modules_install
# Update bootloader
grub-mkconfig -o /boot/grub/grub.cfg
# Force sync
sudo emerge --sync
# If that fails, use git
cd /var/db/repos/gentoo
git fetch --all
git reset --hard @{u}
| Language | Resource |
|---|---|
| English | forums.gentoo.org |
| German | gentoo.org/de |
| French | gentoo.org/fr |
| Spanish | gentoo.org/es |
| Italian | gentoo.org/it |
| Portuguese | gentoo.org/pt |
| Russian | gentoo.org/ru |
emerge --info outputWhen seeking help, include:
# System information
emerge --info
# Package in question
emerge --info package-name
# USE flags
emerge --info | grep USE
# Compilation error
# Full error message from /var/log/portage/
# Sync portage
sudo emerge --sync
# Update system
sudo emerge --update --deep --newuse @world
# Install package
sudo emerge package-name
# Remove package
sudo emerge --unmerge package-name
# Search packages
emerge --search keyword
# Check USE flags
emerge --info | grep USE
# Manage services (OpenRC)
sudo rc-service service-name start
sudo rc-update add service-name default
| File/Directory | Purpose |
|---|---|
/etc/portage/make.conf |
Global Portage settings |
/etc/portage/package.use |
Per-package USE flags |
/etc/portage/package.accept_keywords |
Unstable packages |
/var/log/portage/ |
Portage logs |
/usr/portage/ |
Portage tree |
/usr/src/linux |
Kernel sources |
/etc/init.d/ |
OpenRC init scripts |
Need expert Gentoo assistance? Contact us at linux-server-admin.com/contact for professional Gentoo installation, optimization, and ongoing support.