Gentoo Package Management Handbook

Portage is Gentoo's package management system. Core concepts: ebuild (build script), emerge (CLI), USE flags (compile-time feature switches), world set (packages explicitly installed by the user), @system (base system set).

Status Checks

# Installed packages
equery list '*'                          # All installed packages (app-editors/neovim-0.10.0)
equery list -i                           # Same as above
eix -I                                   # Installed (eix is much faster than equery)
eix -I --format '<category>/<name>-<installedversions:INSTALLEDVERSION>\n'  # Compact format
qlist -IRv                               # portage-utils version (faster)

# Package information
equery uses neovim                       # View USE flags for a package and their current status
equery depends neovim                    # Which packages depend on neovim
equery depends --indirect neovim         # Recursive reverse dependencies (including indirect)
equery files neovim                      # Which files are installed by the package
equery size neovim                       # How much disk space the package occupies
eix neovim                               # Package summary (version/description/USE/overlay)

# Check for updates
emerge --sync && emerge -puDN @world     # -p=pretend, -u=update, -D=deep, -N=new-use
emerge -puDN @world --verbose-conflicts  # With conflict details

# USE flags
emerge --info | grep USE                  # Global USE settings
portageq envvar USE                       # Currently active global USE
euse -a                                   # Status of all USE flags (+enabled/-disabled)
euse -i gtk                               # View description of the gtk flag

# World set
cat /var/lib/portage/world               # List of manually installed packages
emerge --depclean -p                      # Preview orphaned dependencies that can be cleaned

# Dependency analysis
emerge -p --depclean                      # Which packages are orphaned
revdep-rebuild -p                         # Preview broken dynamic link dependencies

Installation and Uninstallation

# Installation
emerge -av app-editors/neovim             # -a=ask (confirm), -v=verbose
emerge -av --autounmask-write neovim      # Automatically write USE/keyword changes (requires subsequent dispatch-conf)
emerge -1av neovim                        # -1=oneshot (do not add to world set)

# Uninstallation
emerge -aC app-editors/neovim             # --unmerge, remove from world set
emerge -a --depclean app-editors/neovim   # Clean up along with orphaned dependencies

# Updates
emerge -avuDN @world                       # Update everything (common)
emerge -avuDN @world --with-bdeps=y       # Include build-time dependencies
emerge -avuDN @world --exclude "sys-kernel/*" # Exclude certain packages
emerge -avuDN @world --keep-going          # Continue on error (summarize failures at the end)

# Install from overlay
emerge -av app-editors/neovim::guru       # Specify overlay

# Download only, do not install
emerge -avf neovim                         # -f=fetchonly

USE Flags Management

# Temporarily enable/disable (single emerge)
USE="gtk -qt5" emerge -av app-editors/neovim

# Package-level USE (permanent)
# Edit /etc/portage/package.use/<name> or /etc/portage/package.use
echo "app-editors/neovim gtk -qt5" >> /etc/portage/package.use/neovim

# Global USE (permanent)
# Edit /etc/portage/make.conf:
# USE="gtk -qt5"

# View which packages are affected by a USE flag
equery hasuse gtk
eix --installed-with-use gtk

# Rebuild affected packages after USE flag changes
emerge -av --changed-use @world
emerge -av --newuse @world                # Same as above (-N)

Keywords and Masking

# Accept ~amd64 (testing) for specific packages
echo "app-editors/neovim ~amd64" >> /etc/portage/package.accept_keywords/neovim
# Accept specific version
echo "=app-editors/neovim-0.10.0 ~amd64" >> /etc/portage/package.accept_keywords/neovim
# Accept ** (all keywords, including live ebuilds)
echo "app-editors/neovim **" >> /etc/portage/package.accept_keywords/neovim

# Mask (prevent installation/upgrade)
echo ">=app-editors/neovim-0.11.0" >> /etc/portage/package.mask/neovim
# Unmask (remove global mask)
echo "app-editors/neovim" >> /etc/portage/package.unmask/neovim

Configuration Updates (dispatch-conf)

# If prompted for CONFIGURATION FILES update after emerge:
dispatch-conf                            # Interactive merge of ._cfg files
# Shortcuts: u=use-new, z=zap-new (discard new config), m=merge-interactive, q=quit

# View pending configurations
find /etc -name '._cfg*'                  # List all pending configuration files to merge

# Automation (non-interactive)
etc-update                                # Another configuration merging tool

Troubleshooting and Maintenance

# Synchronization
emerge --sync                             # Update ebuild tree
emaint sync -a                            # Synchronize all repos (including overlays)
eix-sync                                  # emerge --sync + update eix cache

# Fix broken dependencies
revdep-rebuild                            # Scan and recompile broken linkage (after soname changes)
revdep-rebuild -p -- --exclude gcc        # Preview, exclude certain packages

# Rebuild @world (after major version upgrades)
emerge -e @world                          # -e=emptytree, completely recompile all packages

# After Python target upgrade
emerge -av1 --changed-deps @world         # Rebuild only if dependencies changed

# Cleanup
emerge --depclean -a                      # Remove orphaned dependencies
eclean-dist -d                            # Clean distfiles (downloaded source packages)
eclean-pkg -d                             # Clean binary packages
eclean-kernel -n 2                        # Keep the latest 2 kernels, clean old ones

# View build logs
less /var/log/emerge.log                  # emerge history
less /var/tmp/portage/*/temp/build.log    # Failed build logs

# Check system consistency
emerge -avuDN @world --verbose-conflicts   # Check for conflicts before updating
emerge @preserved-rebuild                 # Rebuild consumers of preserved-libs

# Check overlay issues
emerge --info | grep overlay
# If overlays like guru cause conflicts, temporarily disable:
# emerge -avuDN @world --exclude="*::guru"

Overlay Management

# List enabled overlays
emerge --info | grep -A 20 "Repositories"
layman -l                                # If using layman

# Add overlay (eselect-repository)
eselect repository list                  # List available overlays
eselect repository enable guru           # Enable guru overlay
eselect repository disable guru          # Disable

# Synchronize overlay
emaint sync -r guru                      # Synchronize only guru

Profile and Compiler

# Profile switching
eselect profile list                     # List available profiles
eselect profile set default/linux/amd64/23.0/desktop

# GCC version switching
gcc-config -l                            # List installed GCC versions
gcc-config x86_64-pc-linux-gnu-13.2.0    # Switch
source /etc/profile                      # Refresh environment

# Python version
eselect python list
eselect python set python3.12

# View compilation environment
emerge --info                            # Full Portage environment (CHOST/CFLAGS/USE/...)

Quick Reference: Key make.conf Configurations

# Key items in /etc/portage/make.conf:
# MAKEOPTS="-j16"                # Number of parallel compilations (≈ number of CPU cores)
# EMERGE_DEFAULT_OPTS="--jobs=4 --load-average=16"  # Parallel emerge tasks
# ACCEPT_LICENSE="*"             # Accept all licenses (use with caution in production)
# L10N="en-US zh-CN"             # Localization
# VIDEO_CARDS="amdgpu radeonsi"  # Graphics drivers
# INPUT_DEVICES="libinput"       # Input devices
# CPU_FLAGS_X86="aes avx avx2 ..."  # Compiler optimizations (cpuid2cpuflags)