emerge Command: Tutorial & Examples

Install, remove, and manage software packages on Gentoo-based systems using the Portage system

emerge is the primary command-line interface for package management on Gentoo Linux and its derivatives. It allows users to install, update, and remove software packages by retrieving source code, resolving dependencies, and compiling software tailored to the system's configuration. Built on the flexible Portage system, emerge provides powerful customization options to control package features through USE flags, package masking, and overlays.

This article explores how emerge works, its common usage patterns, important command-line options, and practical examples. It also discusses troubleshooting common issues, advanced customization, automation, and security considerations to help administrators effectively manage Gentoo-based systems.

What emerge Does

emerge is the interface to the Portage package management system, which is designed around the concept of building packages from source code. Unlike binary package managers found in other distributions, emerge downloads ebuild scripts that define how to fetch, configure, and compile software. It handles dependencies automatically, ensuring that all required libraries and tools are installed before compiling a package.

Users can install new software, update existing packages, remove unwanted software, and search for available packages in the Portage tree. The system is highly customizable, allowing precise control over package features via USE flags and package masks.

How emerge Works

At its core, emerge interacts with the Portage tree, a collection of ebuild scripts stored locally on the system (typically in /usr/portage or another configured overlay). Ebuilds are shell scripts that contain metadata and instructions for downloading, configuring, compiling, and installing software.

When a user runs emerge package_name, the tool:

Parses the ebuild metadata including dependencies and USE flags.
Resolves dependencies recursively, determining the full set of packages needed.
Checks package masks and system profiles to ensure compatibility.
Downloads source archives from mirrors or version control systems.
Applies patches and configuration options as specified by USE flags.
Compiles the software from source.
Installs the compiled binaries and updates the package database.

This process allows Gentoo to optimize software specifically for the target hardware and user preferences, but it also means that package installation can take longer than binary-based systems.

Common Command Line Parameters

emerge provides a variety of options to control its behavior. Some of the most commonly used parameters include:

package_name
Installs or updates the specified package.
--update (-u)
Updates the specified package(s) and their dependencies if newer versions are available.
--deep (-D)
Performs a deep dependency check, including indirect dependencies.
--newuse (-N)
Rebuilds packages if USE flags have changed since the last build.
--unmerge (-C)
Removes the specified package and its files from the system.
--search (-s)
Searches the Portage tree for packages matching a keyword.
--list-installed (-I)
Lists all packages currently installed on the system.
--sync
Synchronizes the Portage tree with remote repositories, updating available package metadata and ebuilds.
--oneshot
Installs a package without recording it as a system package to be updated later — useful for temporary use.
--verbose (-v)
Displays detailed information about package use flags and dependencies.

Basic Usage

Below are some common emerge commands with example usage and sample output.

Installing a New Package

Run:

emerge vim

Sample output snippet:

>>> Emerging (1 of 1) app-editors/vim-8.2.3456::gentoo
>>> Downloading 'http://distfiles.gentoo.org/distfiles/vim-8.2.3456.tar.gz'
>>> Configuring...
>>> Compiling...
>>> Installing...
>>> Recording app-editors/vim-8.2.3456

Updating Installed Packages

To update all installed packages considering USE flag changes and deep dependencies, run:
```
emerge --update --deep --newuse @world
```
This command checks for updates to all packages in the @world set.
Removing a Package

To uninstall a package and clean up its files:
```
emerge --unmerge vim
```

Searching for Packages

To search for packages related to "nginx":

emerge --search nginx

Sample output:

Searching... 9 matches found.
[M] www-servers/nginx
[M] www-servers/nginx-mod-http-image-filter
[M] www-servers/nginx-mod-http-xslt-filter
...

Listing Installed Packages
```
emerge --list-installed
```
This lists all packages currently installed.
Synchronizing the Portage Tree
```
emerge --sync
```
This updates the local Portage tree with the latest ebuilds from the remote repository.

Advanced Usage

USE Flags

USE flags are keywords that enable or disable optional features in packages. They allow you to customize package builds to include or exclude functionality such as GUI support, database backends, or language bindings.

For example, to install vim with Python support enabled, you might set the python USE flag in /etc/portage/make.conf or use:

    USE="python" emerge vim

You can see the current USE flags and their effects with:

    emerge --pretend --verbose vim

Package Masking and Unmasking

Gentoo allows masking packages to prevent their installation, either because they are unstable or incompatible. You can override masks in /etc/portage/package.accept_keywords.

Overlays

Overlays are additional repositories users can add to extend or customize the Portage tree, managed with tools like layman.

Potential Problems and Troubleshooting

Build Failures:
Compilation errors can occur due to missing dependencies or incompatible USE flags. Check the build log (usually in /var/tmp/portage/package-category/package-version/temp/build.log).
Conflicting USE Flags:
Some packages do not support certain combinations of USE flags, leading to errors. Use emerge --pretend to preview changes.
Disk Space:
Building from source requires sufficient disk space and CPU time.
Slow Updates:
Synchronizing and compiling packages can be time-consuming on older hardware.

Customization and Configuration

Important configuration files include:

/etc/portage/make.conf — Main Portage configuration, including USE flags, compiler options.
/etc/portage/package.accept_keywords — Package keyword overrides.
/etc/portage/package.use — Per-package USE flags.
/etc/portage/repos.conf — Repository definitions.

Automation and Scripting

emerge can be used in scripts for automated system updates or package installation. For example, a simple script to update the system:

#!/bin/bash
emerge --sync
emerge --update --deep --newuse @world
emerge --depclean

Security Considerations

Since emerge builds from source, ensure that your Portage tree is synced from trusted repositories. Validate GPG keys used for signing ebuilds and source files to avoid security issues.

Alternatives and Related Commands

equery — Tool to query installed packages and dependencies.
etc-update — Helps update configuration files after package updates.
emerge --sync — Synchronizes the Portage tree.
layman — Manages overlays (extra repositories).