Emerge

Emerge is the package manager for Gentoo Linux, providing sophisticated dependency resolution and customization through USE flags, profiles, and per-package configuration.

Basic Commands

Command	Description
emerge --version	Show emerge version
emerge --help	Display help information
emerge --info	Display system information
emerge -s <package>	Search for package
emerge -S <package>	Search package descriptions
emerge <package>	Install package
emerge -u <package>	Update package
emerge -C <package>	Uninstall package

Package Installation

Basic Installation

# Install single package
emerge app-editors/vim

# Install multiple packages
emerge dev-lang/python dev-lang/go sys-apps/git

# Install with dependencies
emerge -u vim

# Install but don't fetch (if cached)
emerge --usepkg vim

# Install as binary only
emerge --getbinpkg vim

# Install specific version
emerge "=dev-lang/python-3.10.5"

Installation Options

# Ask before installing
emerge -a vim

# Pretend (show what would be done)
emerge -p vim

# Pretend + ask
emerge -ap vim

# Verbose output
emerge -v vim

# Very verbose output
emerge -vv vim

# Quiet mode
emerge -q vim

# No colors in output
emerge --nocolor vim

# Keep binary files
emerge -b vim

# Build from source, ignore binaries
emerge --usepkgonly=n vim

Repository Synchronization

# Sync package repository
emerge --sync

# Sync with specific depth
emerge --sync --repo=gentoo

# Update all installed packages
emerge --update --deep world

# Update with new slots
emerge --update --newslot --deep world

# Check for updates without installing
emerge --update --pretend world

# Sync and update
emerge --sync && emerge -u world

USE Flags

Understanding USE Flags

# View available USE flags for a package
emerge --info vim
cat /etc/portage/make.conf | grep USE

# Check USE flags for installed package
emerge -vvp vim | grep USE

# Show description of USE flags
euse -i X

Setting USE Flags

Global (in /etc/portage/make.conf)

# Add to /etc/portage/make.conf
echo 'USE="X gtk python -kde"' >> /etc/portage/make.conf

# Remove USE flag globally
# Edit /etc/portage/make.conf and remove -flag

Per-Package (in /etc/portage/package.use)

# Create package.use file
mkdir -p /etc/portage
cat > /etc/portage/package.use << 'EOF'
app-editors/vim -X python
dev-lang/python threads sqlite
EOF

# Or use package.use directory
mkdir -p /etc/portage/package.use
echo 'vim -X python' > /etc/portage/package.use/editors

Common USE Flags

# Common global flags
USE="X gtk perl python ruby ssl"

# System-wide examples
X          # X11 support
gtk        # GTK+ support
qt         # Qt support
gnome      # GNOME support
kde        # KDE support
python     # Python support
ruby       # Ruby support
perl       # Perl support
ssl        # SSL/TLS support
zlib       # Compression
bzip2      # Bzip2 support
lzma       # LZMA compression
doc        # Documentation
examples   # Build examples
test       # Build tests
nls        # Native language support
multilib   # 32-bit support

System Maintenance

Update System

# Update world (all non-critical packages)
emerge --update world

# Update with new versions across slots
emerge --update --newslot world

# Deep dependency update
emerge --update --deep world

# Full rebuild of world
emerge --emptytree world

# Update @system set
emerge --update @system

Clean and Optimize

# Clean unused dependencies
emerge --depclean

# Show what would be removed
emerge --depclean --pretend

# Remove distfiles (source tarballs)
eclean-dist

# Remove distfiles and binaries
eclean-dist -d
eclean-pkg

# Rebuild package after dependency changes
emerge --usepkg=n @preserved-rebuild

# Update packages that had removed files
emerge --usepkg=n @preserved-rebuild

Verify System

# Check for missing dependencies
emerge --check-news

# Check for removed dependencies
emerge --depclean --pretend

# Verify binaries integrity
cd /usr/portage && find . -name "*.ebuild" -exec emerge --digest {} \;

# Show packages with outdated licenses
emerge --update --newslot --pretend world

Package Queries

# Get package information
emerge -S vim

# List packages matching pattern
emerge -S "python*"

# Show what a package depends on
emerge -p --tree app-editors/vim

# Show reverse dependencies (what depends on this)
equery depends sys-libs/glibc

# Show files from package
equery files vim

# Show which package provides file
equery belongs /usr/bin/vim

# List package versions available
equery list -p app-editors/vim

# Show use flags for package
equery hasuse X app-editors/vim

# Get changelog
equery changes app-editors/vim

Dependency Resolution

Understanding Dependencies

# Show dependency tree
emerge -p --tree world

# Show only direct dependencies
emerge -p --tree --depth=1 vim

# Check circular dependencies
emerge --depclean --pretend

# Find blocking packages
emerge -u world

# Resolve blocks manually
emerge -C app-1
emerge app-2

Breaking Blocks

# If packages block each other
emerge -C app-one
emerge app-two app-one

# Or update if possible
emerge --update app-two
emerge app-one

# Force update (use with caution!)
emerge --update --ignore-default-opts world

Profiles

Managing Profiles

# List available profiles
eselect profile list

# Show current profile
eselect profile show

# Set profile
eselect profile set 1

# Example profiles
eselect profile list | grep stable
eselect profile set default/linux/amd64/17.1/desktop

# Get profile information
cat /etc/portage/make.profile/parent

Common Profiles

# Minimal (server)
default/linux/amd64/17.1

# Desktop with GNOME
default/linux/amd64/17.1/desktop/gnome

# Desktop with KDE
default/linux/amd64/17.1/desktop/kde

# Server
default/linux/amd64/17.1/no-multilib

# Hardened (security)
default/linux/amd64/17.1/hardened

Configuration

/etc/portage/make.conf

# Example make.conf
CFLAGS="-O2 -march=native -pipe"
CXXFLAGS="${CFLAGS}"
MAKEOPTS="-j4"

USE="X gtk python ssl -kde"

GENTOO_MIRRORS="https://mirror.example.com/gentoo"

# Languages
LINGUAS="en de"

# Video cards
VIDEO_CARDS="nvidia"

# Input
INPUT_DEVICES="libinput keyboard mouse"

# Accept licenses
ACCEPT_LICENSE="*"

# Enable parallel downloads
EMERGE_DEFAULT_OPTS="--jobs=4 --load-average=4"

/etc/portage/package.env

# Apply special environment for specific packages
app-editors/vim CFLAGS="-O3 -march=native"
dev-lang/python LDFLAGS="-L/usr/lib64"

Advanced Operations

Building Packages

# Build from source
emerge --usepkg=n vim

# Build with specific CFLAGS
CFLAGS="-O3 -march=native" emerge vim

# Build with ccache
emerge --ccache vim

# Build with distcc
DISTCC_HOSTS="host1 host2" emerge vim

# Build without compiling (pretend)
emerge --pretend --tree world

Creating Binary Packages

# Create binary packages while installing
emerge -b vim

# Create binaries for already installed packages
quickpkg vim

# Install from binary package
emerge --getbinpkg vim

# Distribute binaries to other machines
# Copy /var/cache/binpkgs/cat/package-*.tbz2 to other machines
emerge --getbinpkg vim

Rolling Back

# Check what was recently changed
less /var/log/emerge.log

# Downgrade package
emerge "=app-editors/vim-8.1.2234"

# Downgrade to specific date
emerge --update --tar-only world  # Creates backup

Troubleshooting

Fix Broken Dependencies

# Clean broken dependencies
emerge --depclean

# Check for circular dependencies
emerge --show-progress=bar --quiet world 2>&1 | grep -i "circular"

# Fix with revdep-rebuild
revdep-rebuild -i -p

# Check broken binaries
scanelf -qn /usr/lib*/

Common Issues

# Package not found
emerge --sync

# Unstable package needed
echo "category/package ~amd64" >> /etc/portage/package.accept_keywords

# Masked package
echo "category/package" >> /etc/portage/package.unmask

# License problems
echo "category/package ACCEPT_LICENSE=\"*\"" >> /etc/portage/package.license

Performance Issues

# Reduce parallel jobs
echo "EMERGE_DEFAULT_OPTS=\"--jobs=2 --load-average=2\"" >> /etc/portage/make.conf

# Speed up fetches
echo "EMERGE_DEFAULT_OPTS=\"--quiet-build=y\"" >> /etc/portage/make.conf

# Use distcc for distributed building
emerge distcc

Batch Operations

# Install set of packages
emerge @world

# Rebuild affected packages after library update
emerge --usepkg=n @preserved-rebuild

# Update entire system
emerge --update --deep --newslot world

# Install development tools
emerge -t sys-devel/base-devel

Useful Tools

# Query utilities
emerge app-portage/gentoolkit  # Provides equery, etcat

# Profile management
emerge app-portage/eselect

# Clean unnecessary packages
emerge app-portage/gentoolkit  # eclean command

# Revdep rebuild
emerge app-portage/gentoolkit  # revdep-rebuild

# Manage keywords/masks
emerge app-portage/eix

Best Practices

Regular Maintenance

# Weekly
emerge --sync
emerge --update --deep world

# Monthly
emerge --depclean --pretend
eclean-dist --pretend

# Quarterly
emerge --emptytree world  # Full rebuild

# Check system health
emerge --check-news

Safe Updates

# Always preview first
emerge --pretend --tree world

# Build packages to check for errors
emerge -b world

# Update @system first
emerge --update @system

# Then update @world
emerge --update @world

Resources

• Gentoo Wiki
• Emerge Manual
• Portage Documentation
• USE Flag Guide
• Package Masking

---

Last updated: 2025-03-30