emerge — configuration — ebuild repository — dispatch-conf
world file — USE flags — ebuilds — profiles
upgrades — using testing packages — binary packages
tools — gentoolkit — eselect
Portage FAQ — cheat sheet — FAQ
emerge is 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.
emerge is used to install, update, and generally maintain software packages on Gentoo Linux.
The emerge command has many possible options. For extensive documentation and a complete list of all options see man emerge.
emerge can provide rich output about what changes will be made, and will provide information and warnings about individual packages or the system. The
--verbose options are useful to have Portage show more information - by default, the emerge command will perform the requested action immediately.
Running emerge with the
--help option provides information on command line options:
emerge: command-line interface to the Portage system Usage: emerge [ options ] [ action ] [ ebuild | tbz2 | file | @set | atom ] [ ... ] emerge [ options ] [ action ] < @system | @world > emerge < --sync | --metadata | --info > emerge --resume [ --pretend | --ask | --skipfirst ] emerge --help Options: -[abBcCdDefgGhjkKlnNoOpPqrsStuUvVwW] [ --color < y | n > ] [ --columns ] [ --complete-graph ] [ --deep ] [ --jobs JOBS ] [ --keep-going ] [ --load-average LOAD ] [ --newrepo ] [ --newuse ] [ --noconfmem ] [ --nospinner ] [ --oneshot ] [ --onlydeps ] [ --quiet-build [ y | n ] ] [ --reinstall changed-use ] [ --with-bdeps < y | n > ] Actions: [ --depclean | --list-sets | --search | --sync | --version ] For more help consult the man page.
Below is an example invocation of emerge, installing "package". The options (
-atv) are short options for
--verbose. They trigger emerge to ask before proceeding, display the dependency tree of packages to be installed, and to be verbose with its output:
These are the packages that would be merged, in reverse order:
Calculating dependencies... done! [ebuild ] category/package- - [2.0] USE="enabled -disabled toggled new (-unavailable)" MAKE_OPTIONS="-disabled" 777 kB [ebuild U ] -2.0[3.0] 777 kB [ebuild ] category/package-1.0 777 kB [ebuild ] category/package-0.5 777 kB
Total: 4 packages (1 new, 1 reinstall, 1 upgrade, 1 downgrade), Size of downloads: 3108 kBWould you like to merge these packages? [Yes/No]
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 net-proxy/tinyproxy package with
emerge --ask --verbose net-proxy/tinyproxy
-a) option is very useful, it will allow the emerge actions to be reviewed before the actual operation begins. The
-v) option will show more detailed information about what Portage will do, and is often helpful. Options can be set as default, if desired. Default options can be overridden on the command line, for example
--askoption is not provided, requested actions will be performed without ever asking for confirmation. The
--pretendoption may also be used.
Some things, such as dependencies, should not be installed in this way. See do not add dependencies to the world file section.
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
The built-in search of emerge may show limited results compared to other tools. The Latest version available is constrained by the ACCEPT_KEYWORDS in make.conf (or the environment). In addition, Latest version available and Latest installed version are not slot aware so will not show multiple versions by slot. This can lead to some confusion while tools like eix or eshowkw might show more versions.
Search for packages with proxy in their names:
emerge --search proxy
Search for packages with proxy in their names or description:
emerge --searchdesc proxy
Search packages using a regular expression:
emerge -s '%^python$'
List all packages in a category:
emerge -s '@net-ftp'
The repository can also be searched online at packages.gentoo.org.
Remove (uninstall) packages
Remove the net-proxy/tinyproxy package using the dependency sensitive
emerge --ask --verbose --depclean net-proxy/tinyproxy
This should only remove packages that are not needed as a dependency of a currently installed package.
An alternative to using
--depclean to uninstall packages, is to use emerge --deselect (or
-W option), then cleaning out orphaned packages, as described in the following section.
Do not confuse the lower case
-cswitch, which is short for
--depclean(and is safe), with the upper case
-Cswitch which risks damaging the system and should only be used when absolutely required (see warning below).
Do not use the
-C) option (unless its particular behavior is known to be specifically required). This option will remove important packages that are needed for the system to function, without warning.
Cleaning out orphaned packages
See Upgrading Gentoo for how to update packages.
Get system information
Extra information may be output by using the
Verifying and (re)downloading distfiles
To re-verify the integrity of and re-download previously removed/corrupted distfiles for all currently installed packages, run:
emerge --ask --fetchonly --emptytree @world
Do not add dependencies to the world file
If a dependency must be reinstalled, use the
--oneshot option. Installing dependencies with the emerge package 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.
If an emerge of several packages is interrupted (e.g. ctrl+c, crash...), the emerge may be resumed from the failed package with the
--resume option. The
--skipfirst options may also be of interest. See the emerge man page for details.
Setting environment variables
The emerge command can be preceded by environment variables, in order to affect behavior for that invocation alone. For example, to merge app-editors/emacs with the
svg USE flag enabled, but not make this USE flag setting permanent:
USE='svg' emerge app-editors/emacs
Or to pass extra configuration options to packages that use the
econf function in their ebuild:
EXTRA_ECONF='--without-compress-install' emerge app-editors/emacs
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:
portageq envvar PORTAGE_TMPDIR
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.