Emerge

emerge is Article description::the command-line interface to [[Portage]] and is how most users will interact with Portage. It is one of the most important commands on Gentoo.

is used to install, update, and generally maintain software packages on Gentoo Linux.

Invocation
can provide rich output about what changes will be made, and will provide information and warnings about individual packages or the system. The ,  , and   options are useful to have Portage show more information - by default, the emerge command will perform the requested action immediately.

Running emerge with the  option provides information on command line options:

Below is an example invocation of, installing "package". The options are short options for ,  , and. They trigger to ask before proceeding, display the dependency tree of packages to be installed, and to be verbose with its output:

The U symbol shows a package that will be upgraded, D a package that will be downgraded, R re-emerged, N a new package. In square brackets is the version of the previously installed package. Packages present in the world file are shown in bold - these are the user-installed packages, the other packages will be dependencies, or from the system set.

In the context of Portage, the term "package" can also be referred to as an "atom", the terms can be used interchangeably. See version specifier.

Install a package
Install the package with   and   options:

What package, version, and slot, to install, and from which ebuild repository is indicated using a version specifier.

Package functionality is governed at install time by USE flags which can be set or unset depending on the intended use of a piece of software.

Search for packages
Search for packages with proxy in their names:

Search for packages with proxy in their names or description:

Search packages using a regular expression:

List all packages in a category:

The repository can also be searched online at packages.gentoo.org.

Remove (uninstall) packages
Remove the package using the dependency sensitive    option:

This should only remove packages that are not needed as a dependency of a currently installed package.

An alternative to using  to uninstall packages, is to use  (or   option), then cleaning out orphaned packages, as described in the following section.

Update packages
See Upgrading Gentoo for how to update packages.

Get system information
emerge can print system information that can be useful for troubleshooting. This information is often required to be posted when asking for support, or when filing a bug.

Extra information may be output by using the  flag.

Verifying and (re)downloading distfiles
To re-verify the integrity of and re-download previously removed/corrupted distfiles for all currently installed packages, run:

Do not add dependencies to the world file
If a dependency must be reinstalled, use the  option. Installing dependencies with the command would add them to the world file and may lead to issues.

Installing dependencies with Portage for compiling custom source software is also ill advised: it is preferable to write an ebuild.

Resume emerge
If an emerge of several packages is interrupted (e.g. ctrl+c, crash...), the emerge may be resumed from the failed package with the  option. The  and   options may also be of interest. See the emerge man page for details.

Emerging packages fail during 'unpack' stage
The following message can occur when emerging packages:

* Error messages for package dev-libs/libinput-1.16.0: * The ebuild phase 'unpack' has exited unexpectedly. This type of behavior * is known to be triggered by things such as failed variable assignments * (bug #190128) or bad substitution errors (bug #200313). Normally, before * exiting, bash should have displayed an error message above. If bash did * not produce an error message above, it's possible that the ebuild has * called `exit` when it should have called `die` instead. This behavior * may also be triggered by a corrupt bash binary or a hardware problem * such as memory or cpu malfunction. If the problem is not reproducible or * it appears to occur randomly, then it is likely to be triggered by a  * hardware problem. If you suspect a hardware problem then you should try * some basic hardware diagnostics such as memtest. Please do not report * this as a bug unless it is consistently reproducible and you are sure * that your bash binary and hardware are functioning properly.

Although this issue may be due the reasons listed in the output above, it can often be caused by low disk space in the path used by Portage to unpack the ebuild's source files. This location is set via the PORTAGE_TMPDIR variable and can be quickly found by querying Portage:

The df command may be used to view available disk space for the partition where PORTAGE_TMPDIR has been mounted (this will likely be the root partition). See Freeing disk space for details on how to free up disk space.